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.

Parameters:

Name	Type	Description	Default
tray_id	str	The tray icon identifier.	required

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.

Parameters:

Name	Type	Description	Default
tray_id	str	Unique tray icon identifier.	required
tooltip	str or None	Hover tooltip text.	None
title	str or None	Tray title (macOS menu bar text).	None
icon	bytes or None	RGBA icon bytes.	None
icon_width	int	Icon width in pixels.	32
icon_height	int	Icon height in pixels.	32
menu	MenuConfig or None	Menu to attach.	None
menu_on_left_click	bool	Whether left click opens the menu.	True

Returns:

Type	Description
TrayProxy	Proxy connected to the created tray icon.

Raises:

Type	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

Parameters:

Name	Type	Description	Default
config	TrayIconConfig	Complete tray icon configuration.	required

Returns:

Type	Description
TrayProxy

set_icon

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

Update the tray icon image.

Parameters:

Name	Type	Description	Default
icon	bytes	RGBA icon bytes.	required
width	int	Icon width.	32
height	int	Icon height.	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.

Parameters:

Name	Type	Description	Default
menu	MenuConfig	New menu configuration.	required

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

Parameters:

Name	Type	Description	Default
event_type	str	Event type string (e.g. "tray:click").	required
callback	Callable	Handler function.	required

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