Reference

class pystray.Icon(name, icon=None, title=None, menu=None)[source]

A representation of a system tray icon.

The icon is initially hidden. Set visible to True to show it.

Parameters
  • name (str) – The name of the icon. This is used by the system to identify the icon.

  • icon – The icon to use. If this is specified, it must be a PIL.Image.Image instance.

  • title (str) – A short title for the icon.

  • menu

    A menu to use as popup menu. This can be either an instance of Menu or a tuple, which will be interpreted as arguments to the Menu constructor.

    The behaviour of the menu depends on the platform. Only one action is guaranteed to be invokable: the first menu item whose default attribute is set.

    Some platforms allow both menu interaction and a special way of activating the default action, some platform allow only either an invisible menu with a default entry as special action or a full menu with no special way to activate the default item, and some platforms do not support a menu at all.

HAS_DEFAULT_ACTION = True

Whether this particular implementation has a default action that can be invoked in a special way, such as clicking on the icon.

HAS_MENU = True

Whether this particular implementation supports menus.

HAS_MENU_RADIO = True

Whether this particular implementation supports displaying mutually exclusive menu items using the MenuItem.radio attribute.

HAS_NOTIFICATION = True

Whether this particular implementation supports displaying a notification.

property icon

The current icon.

Setting this to a falsy value will hide the icon. Setting this to an image while the icon is hidden has no effect until the icon is shown.

property menu

The menu.

Setting this to a falsy value will disable the menu.

property name

The name passed to the constructor.

notify(message, title=None)[source]

Displays a notification.

The notification will generally be visible until remove_notification() is called.

The class field HAS_NOTIFICATION indicates whether this feature is supported on the current platform.

Parameters
  • message (str) – The message of the notification.

  • title (str) – The title of the notification. This will be replaced with title if None.

remove_notification()[source]

Remove a notification.

run(setup=None)[source]

Enters the loop handling events for the icon.

This method is blocking until stop() is called. It must be called from the main thread.

Parameters

setup (callable) –

An optional callback to execute in a separate thread once the loop has started. It is passed the icon as its sole argument.

If not specified, a simple setup function setting visible to True is used. If you specify a custom setup function, you must explicitly set this attribute.

stop()[source]

Stops the loop handling events for the icon.

property title

The current icon title.

update_menu()[source]

Updates the menu.

If the properties of the menu descriptor are dynamic, that is, any are defined by callables and not constants, and the return values of these callables change by actions other than the menu item activation callbacks, calling this function is required to keep the menu in sync.

This is required since not all supported platforms allow the menu to be generated when shown.

For simple use cases where menu changes are triggered by interaction with the menu, this method is not necessary.

property visible

Whether the icon is currently visible.

Raises

ValueError – if set to True and no icon image has been set

class pystray.Menu(*items)[source]

A description of a menu.

A menu description is immutable.

It is created with a sequence of Menu.Item instances, or a single callable which must return a generator for the menu items.

First, non-visible menu items are removed from the list, then any instances of SEPARATOR occurring at the head or tail of the item list are removed, and any consecutive separators are reduced to one.

SEPARATOR = <pystray._base.MenuItem object>

A representation of a simple separator

property items

All menu items.

property visible

Whether this menu is visible.

class pystray.MenuItem(text, action, checked=None, radio=False, default=False, visible=True, enabled=True)[source]

A single menu item.

A menu item is immutable.

It has a text and an action. The action is either a callable of a menu. It is callable; when called, the activation callback is called.

The visible attribute is provided to make menu creation easier; all menu items with this value set to False will be discarded when a Menu is constructed.

property checked

Whether this item is checked.

This can be either True, which implies that the item is checkable and checked, False, which implies that the item is checkable but not checked, and None for uncheckable items.

Depending on platform, uncheckable items may be rendered differently from unchecked items.

property default

Whether this is the default menu item.

property enabled

Whether this menu item is enabled.

property radio

Whether this item is a radio button.

This is only used for checkable items. It is always set to False for uncheckable items.

property submenu

The submenu used by this menu item, or None.

property text

The menu item text.

property visible

Whether this menu item is visible.

If the action for this menu item is a menu, that also has to be visible for this property to be True.