Reference

class pystray.Icon(name, icon=None, title=None, menu=None, **kwargs)[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 an iterable, which will be interpreted as arguments to the Menu constructor, or None, which disables the menu.

    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.

  • kwargs

    Any non-standard platform dependent options. These should be prefixed with the platform name thus: appindicator_, darwin_, gtk_, win32_ or xorg_.

    Supported values are:

    darwin_nsapplication
    An NSApplication instance used to run the event loop. If this is not specified, the shared application will be used.
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.

SETUP_THREAD_TIMEOUT = 5.0

The timeout, in secods, before giving up on waiting for the setup thread when stopping the icon.

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.

menu

The menu.

Setting this to a falsy value will disable the menu.

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.

Please note that this function is started in a thread, and when the icon is stopped, an attempt to join this thread is made, so stopping the icon may be blocking for up to SETUP_THREAD_TIMEOUT seconds if the function is not well-behaved.

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.

run_detached(setup=None)[source]

Prepares for running the loop handling events detached.

This allows integrating pystray with other libraries requiring a mainloop. Call this method before entering the mainloop of the other library.

Depending on the backend used, calling this method may require special preparations:

macOS
Pass an instance of NSApplication retrieved from the library with which you are integrating as the argument darwin_nsapplication. This will allow this library to integrate with the main loop.
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.

Raises:NotImplementedError – if this is not implemented for the preparations taken
stop()[source]

Stops the loop handling events for the icon.

If the icon is not running, calling this method has no effect.

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.

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

items

All menu items.

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.

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.

default

Whether this is the default menu item.

enabled

Whether this menu item is enabled.

radio

Whether this item is a radio button.

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

submenu

The submenu used by this menu item, or None.

text

The menu item text.

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.