tray_manager is a package used for creating a system tray icon, based on pystray (https://github.com/moses-palmer/pystray by Moses Palmér), this package is an "easier" version of pystray to manipulate as it's based on the use of objects.

tray_manager is publisehd on PyPi (https://pypi.org/project/tray-manager/) and can be downloaded by using the following command in your terminal :

pip install tray-manager

1. Create and use a TrayManager object
2. Create and interact with Items
3. Add items to the Menu
4. Customize the TrayManager object
5. Customize and edit the items
6. Check for OS supported features
7. Notifications [CURRENTLY UNAVAIBLE]
8. Advanced settings

The main object of the librairy is the tray_manager.TrayManager object, it is the central element and can be considered as the icon in the system tray itself, it contains all the elements of our app.

To create one, you need to import the tray_manager.TrayManager class and create a tray object as followed :

from tray_manager import TrayManager
my_tray = TrayManager(app_name="My App")

To stop the app, you need to use the .kill() function as followed :

from tray_manager import TrayManager, Label, Button

my_tray = TrayManager("My App", run_in_seperate_thread=True)
my_menu = my_tray.menu

def my_callback():
  print("Hello")

my_label = Label("My Label")
my_button = Button("My Button", my_callback)

my_menu.add(my_label)
my_menu.add(my_button)

my_tray.kill()
-> [my_label, my_button]

The items are the elements of your app, they will be displayed in the menu they're added to. Their is different kinds of items that all works in a similar way but each have some specificities.

Here is the list of all the items :

1. Label
2. Button
3. CheckBox
4. Separator
5. Submenu

The label is the most basic item, it is only constituated of a text.

To create one, use the tray_manager.Label class as followed :

from tray_manager import Label
my_label = Label("My Label")

The button is like the label item but you can add a callback argument (FunctionType) that will be called when the user clicks on the button. You can also specify some arguments as a tuple that will be passed to your function when the button is clicked.

To create one, use the tray_manager.Button class as followed :

from tray_manager import Button
def my_callback(text: str) -> None:
  print(text)

my_button = Button("My Button", my_callback, args=("Hello",))

The CheckBox item is a bit more complex than a regular button, it has 2 differents callbacks instead of 1 and different arguments for each, one for when the checkbox switch from the 'Disabled' to 'Enabled' state (Not checked to checked), and one for when it switch from the 'Enabled' to 'Disabled' state (Checked to not checked).

You can 'Disable' the interactions with your checkbox by setting the value of check_default to None.

To create one, use the tray_manager.CheckBox class as followed :

from tray_manager import CheckBox

def checked(text: str) -> None:
  print(f"In procedure 'checked' : {text}")

def unchecked(text: str) -> None:
  print(f"In procedure 'unchecked' : {text}")

my_checkbox = CheckBox("My CheckBox", check_default=False, checked_callback=checked, checked_callback_args=("I'm now checked",),
                        unchecked_callback=unchecked, unchecked_callback_args=("I'm now unchecked",))

To get the current state of the checkbox, you can use the .get_status() function as followed :

from tray_manager import CheckBox

my_checkbox = CheckBox("My CheckBox")

my_checkbox.get_status()
-> bool | None

You can also set the state of the checkbox by using the .set_status() function as followed :

from tray_manager import CheckBox

my_checkbox = CheckBox("My CheckBox")

my_checkbox.set_status(True)
-> Checked
my_checkbox.set_status(False)
-> Unchecked
my_checkbox.set_status(None)
-> Disabled

The separator is a built-in object of Pystray, it doesn't have any parameters.

To create one, use the tray_manager.Separator class as followed :

from tray_manager import Separator
my_separator = Separator()

The submenu is like a tray_manager.Menu object and can contains other items including other submenu.

 flowchart TD
   A{My Submenu} --> B(My Label)
   A --> C(My Button)
   A --> D{My Second Submenu}
   D --> E(My Second Label)
   D --> F(My Checkbox)
   D --> |❌ tray_manager.CircularAddException| A

To create one, use the tray_manager.Submenu as followed :

from tray_manager import Submenu
my_submenu = Submenu("My Submenu")

To add an item to the submenu, use the .add() function as followed :

from tray_manager import Submenu, Label
my_submenu = Submenu("My Submenu")
my_label = Label("My Label")

my_submenu.add(my_label)

To remove an item from the submenu, use the .remove() function as followed :

from tray_manager import Submenu, Label
my_submenu = Submenu("My Submenu")
my_label = Label("My Label")

my_submenu.add(my_label)

my_submenu.remove(my_label)
-> my_label

To get the items contained in a submenu, use the .get_items() function as followed:

from tray_manager import Submenu, Label, Button

def my_callback()
  print("Hello")

my_submenu = Submenu("My Submenu")
my_label = Label("My Label")
my_button = Button("My Button", my_callback)

my_submenu.add(my_label)
my_submenu.add(my_button)

my_submenu.get_items()
-> [my_label, my_button]

The tray_manager.Menu is one of the central elements of this library, it works like a submenu and is created automatically when you create a tray_manager.TrayManager object as the tray_manager.TrayManager.menu object and cannot be removed.

To use the menu, acces the tray_manager.TrayManager.menu object as followed :

from tray_manager import TrayManager
my_tray = TrayManager("My App", run_in_seperate_thread=True)
my_menu = my_tray.menu

To add an item to the menu, use the .add() function as followed :

from tray_manager import TrayManager, Label
my_tray = TrayManager("My App", run_in_seperate_thread=True)
my_menu = my_tray.menu

my_label = Label("My Label")

my_menu.add(my_label)

To remove an item from the menu, you can use the .remove() function as followed :

from tray_manager import TrayManager, Label
my_tray = TrayManager("My App", run_in_seperate_thread=True)
my_menu = my_tray.menu

my_label = Label("My Label")
my_menu.add(my_label)

my_menu.remove(my_label)
-> my_label

To get the items contained in a menu, you can use the .get_items() function as followed:

from tray_manager import TrayManager, Menu, Label, Button

def my_callback()
  print("Hello")

my_tray = TrayManager("My App", run_in_seperate_thread=True)
my_menu = my_tray.menu

my_label = Label("My Label")
my_button = Button("My Button", my_callback)

my_menu.add(my_label)
my_menu.add(my_button)

my_menu.get_items()
-> [my_label, my_button]

To update the menu items (The items contained inside the menu), use the .update() function.

from tray_manager import TrayManager
my_tray = TrayManager("My App", run_in_seperate_thread=True)
my_menu = my_tray.menu

my_menu.update()

You can customize your TrayManager object in different ways such as :

1. Setting a new name for the app
2. Setting a new icon for the app
3. Hiding / Showing the app in the system tray

To set a new name for your app use the .set_app_name() function as followed :

from tray_manager import TrayManager
my_tray = TrayManager("My App", run_in_seperate_thread=True)

my_tray.set_app_name("My new App")

tray_manager use a memory system for icons, to set a new icon for your app, you first need to load it using the .load_icon() function, then set the icon as the new icon using the .set_icon() function of the tray_manager.TrayManager object.

To load an icon, use the .load_icon() function and pass it a file path, a encoded image, a PIL.Image object or any file that can be read and interpreted as an image by PIL. You also need to pass a name that will be used as a key in the icons dictionnary to retreive your icon.

from tray_manager import TrayManager
my_tray = TrayManager("My App", run_in_seperate_thread=True)

my_tray.load_icon("my_icon_file_path.png", "my_new_icon")

To set an icon, use the .set_icon() function and pass it the name (key) of your icon that you set when you loaded the icon.

from tray_manager import TrayManager
my_tray = TrayManager("My App", run_in_seperate_thread=True)

my_tray.load_icon("my_icon_file_path.png", "my_new_icon")
my_tray.set_icon("my_new_icon")

Instead of killing the tray_manager.TrayManager object when you want it to stop being displayed in the system tray and creating a new one once you need it again, you can use the .show() and .hide() functions of the the tray_manager.TrayManager object to control whether the app is visible in the system tray or not.

To show the app in the system tray, use the .show() function of the the tray_manager.TrayManager object as followed :

from tray_manager import TrayManager
my_tray = TrayManager("My App", run_in_seperate_thread=True)

my_tray.show()

To hide the app in the system tray, use the .hide() function of the the tray_manager.TrayManager object as followed :

from tray_manager import TrayManager
my_tray = TrayManager("My App", run_in_seperate_thread=True)

my_tray.hide()

To edit an already created item, use the .edit() function of the item, when doing so, you only need to specify which arguments you want to change, and the others will stay the same as they were.

To edit an item, do as followed :

from tray_manager import Button

def my_first_callback():
  print("Hello")
  my_button.edit(callback=my_second_callback)

def my_second_callback():
  print("World !")

my_button = Button("My Button", my_first_callback)

# When clicking on the button, this will display :
# First click
-> Hello
# Second click
-> World !

You can custom the items in different ways such as :

1. Enabling / Disabling the item (Gray look and non-responsive)
2. Setting the default attribut to the item (Bold look)
3. Setting the radio look on the checkbox (A dot instead of a crossmark)

If you want to display the item but you want it to be non-responsive (for Button, CheckBox and Submenu) and look like a disabled item, you can use the .enable() and .disable() functions of the item.

To enable your item, use the .enable() function of the item as followed :

from tray_manager import CheckBox

def checked_callback():
  print("Checked")

def unchecked_callback():
  print("Unchecked")

my_checkbox = CheckBox("My CheckBox", checked_callback=checked_callback, unchecked_callback=unchecked_callback)

my_checkbox.enable()

To disable your item, use the .disable() function of the item as followed :

from tray_manager import CheckBox

def checked_callback():
  print("Checked")

def unchecked_callback():
  print("Unchecked")

my_checkbox = CheckBox("My CheckBox", checked_callback=checked_callback, unchecked_callback=unchecked_callback)

my_checkbox.disable()

To make your item the default item of the menu / submenu and give it a bold look, you can set the default attribut when creating / editing the item to True.

To set the default attribut of the item, do as followed :

When creating the item :

from tray_manager import Label
my_label = Label("My Label", default=True)

When editing the item :

from tray_manager import Label
my_label = Label("My Label")
my_label.edit(default=True)

If you want to give a new look to your regular checkbox crossmark, you can set the use_radio_look attribut of the CheckBox to True when creating / editing the CheckBox.

To set the use_radio_look attribut of the item, do as followed :

When creating the item :

from tray_manager import CheckBox

def checked_callback():
  print("Checked")

def unchecked_callback():
  print("Unchecked")

my_checkbox = CheckBox("My CheckBox", checked_callback=checked_callback, unchecked_callback=unchecked_callback, use_radio_look=True)

When editing the item :

from tray_manager import CheckBox

def checked_callback():
  print("Checked")

def unchecked_callback():
  print("Unchecked")

my_checkbox = CheckBox("My CheckBox", checked_callback=checked_callback, unchecked_callback=unchecked_callback)
my_checkbox.edit(use_radio_look=True)

Before using features of the tray_manager package, you must check if they are compatible with your OS. To do so, use the tray_manager.Os_Support object. There is 4 differents features that you need to check before using :

1. Os_Support.SUPPORT_MENU
2. Os_Support.SUPPORT_DEFAULT
3. Os_Support.SUPPORT_RADIO
4. Os_Support.SUPPORT_NOTIFICATION [CURRENTLY UNAVAILBE]

To know if your OS support a feature the corresponding Os_Support variable must be True.

Example, to check if your OS support the menu, do as followed :

from tray_manager import Os_Support
if Os_Support.SUPPORT_MENU:
  print("The menu is supported by your OS")
else:
  print("The menu isn't supported by your OS")

If you want to create a notification on the user's screen, you can use the tray_manager.TrayManager.notification object.

To create a notification, use the .notify() function of the tray_manager.TrayManager.notification object as followed :

from tray_manager import TrayManager
my_tray = TrayManager("My App", run_in_separate_thread=True)
notification = my_tray.notification

notification.notify("My App", "Hello World !")

You can specify a delay after which the notification will be removed by passing a value in seconds to the .notify() function as the remove_after_s as followed :

from tray_manager import TrayManager
my_tray = TrayManager("My App", run_in_separate_thread=True)
notification = my_tray.notification

notification.notify("My App", "Hello World !", remove_after_s=10)
# The notification will close by itself after 10 seconds

You can also use the .remove_notification() function to manually remove the notification as followed :

from tray_manager import TrayManager
my_tray = TrayManager("My App", run_in_separate_thread=True)
notification = my_tray.notification

notification.notify("My App", "Hello World !)

# Some code here

notification.remove_notification()

If you need specific features, you can set the backend argument of the tray_manager.TrayManager object to one of the tray_manager.Backends values.