# Reference

class pystray.Icon(name, icon=None, title=None, menu=None, **kwargs)

  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.

  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)

    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()

    Remove a notification.

  run(setup=None)

    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)

    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()

    Stops the loop handling events for the icon.

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

  property title

    The current icon title.

  update_menu()

    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)

  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)

  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`.