pywry.tray_proxy¶

IPC-backed system tray icon management.

TrayProxy sends commands to the pytauri subprocess to create and control system tray icons, menus, and events. See the System Tray guide for usage patterns and examples.

pywry.tray_proxy.TrayProxy ¶

TrayProxy(tray_id: str)

Proxy for a system tray icon living in the pytauri subprocess.

Instances are not created directly — use the :meth:create class method which sends the tray_create IPC command and returns a proxy.

PARAMETER	DESCRIPTION
`tray_id`	The tray icon identifier. TYPE: `str`

Attributes¶

_all_proxies `class-attribute` ¶

_all_proxies: dict[str, TrayProxy] = {}

_tray_id `instance-attribute` ¶

_tray_id = tray_id

_menu_handler_map `instance-attribute` ¶

_menu_handler_map: dict[str, Any] = {}

_menu_dispatcher_registered `instance-attribute` ¶

_menu_dispatcher_registered = False

id `property` ¶

id: str

The tray icon identifier.

Functions¶

create `classmethod` ¶

create(tray_id: str, tooltip: str | None = None, title: str | None = None, icon: bytes | None = None, icon_width: int = 32, icon_height: int = 32, menu: MenuConfig | None = None, menu_on_left_click: bool = True) -> TrayProxy

Create a system tray icon in the subprocess.

PARAMETER	DESCRIPTION
`tray_id`	Unique tray icon identifier. TYPE: `str`
`tooltip`	Hover tooltip text. TYPE: `str or None` DEFAULT: `None`
`title`	Tray title (macOS menu bar text). TYPE: `str or None` DEFAULT: `None`
`icon`	RGBA icon bytes. TYPE: `bytes or None` DEFAULT: `None`
`icon_width`	Icon width in pixels. TYPE: `int` DEFAULT: `32`
`icon_height`	Icon height in pixels. TYPE: `int` DEFAULT: `32`
`menu`	Menu to attach. TYPE: `MenuConfig or None` DEFAULT: `None`
`menu_on_left_click`	Whether left click opens the menu. TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`TrayProxy`	Proxy connected to the created tray icon.

RAISES	DESCRIPTION
`RuntimeError`	If the subprocess cannot be started or the tray creation fails.

from_config `classmethod` ¶

from_config(config: TrayIconConfig) -> TrayProxy

Create a tray icon from a :class:TrayIconConfig.

Automatically registers any handlers declared on the config:

config.on_click → tray:click
config.on_double_click → tray:double-click
config.on_right_click → tray:right-click
Item handlers from config.menu → tray:menu-click

PARAMETER	DESCRIPTION
`config`	Complete tray icon configuration. TYPE: `TrayIconConfig`

RETURNS	DESCRIPTION
`TrayProxy`

set_icon ¶

set_icon(icon: bytes, width: int = 32, height: int = 32) -> None

Update the tray icon image.

PARAMETER	DESCRIPTION
`icon`	RGBA icon bytes. TYPE: `bytes`
`width`	Icon width. TYPE: `int` DEFAULT: `32`
`height`	Icon height. TYPE: `int` DEFAULT: `32`

set_tooltip ¶

set_tooltip(tooltip: str) -> None

Set the hover tooltip text.

set_title ¶

set_title(title: str) -> None

Set the tray title (macOS menu bar text).

set_menu ¶

set_menu(menu: MenuConfig) -> None

Attach or replace the tray menu.

Handlers declared on items in menu are registered automatically — the same as when creating via :meth:from_config. Previous menu handlers are replaced.

PARAMETER	DESCRIPTION
`menu`	New menu configuration. TYPE: `MenuConfig`

set_visible ¶

set_visible(visible: bool) -> None

Show or hide the tray icon.

set_menu_on_left_click ¶

set_menu_on_left_click(enabled: bool) -> None

Control whether left click shows the tray menu.

on ¶

on(event_type: str, callback: Any) -> None

Register a callback for tray events.

Event types use the tray: namespace:

tray:click — single click
tray:double-click — double click
tray:right-click — right click (convenience alias)
tray:enter — cursor enters tray icon area
tray:leave — cursor leaves tray icon area
tray:move — cursor moves over tray icon area

PARAMETER	DESCRIPTION
`event_type`	Event type string (e.g. `"tray:click"`). TYPE: `str`
`callback`	Handler function. TYPE: `Callable`

remove ¶

remove() -> None

Remove and destroy this tray icon in the subprocess.

remove_all `classmethod` ¶

remove_all() -> None

Remove every tracked tray icon.

Called by :meth:PyWry.destroy to guarantee cleanup regardless of whether trays were created via app.create_tray() or TrayProxy.from_config().

_register_menu_handlers ¶

_register_menu_handlers(menu: MenuConfig) -> None

Collect handlers from menu and (re-)register the dispatcher.

_send_update ¶

_send_update(**kwargs: Any) -> None

Send a tray update command.

repr ¶

__repr__() -> str