pywry.menu_proxy

IPC-backed native menu management.

MenuProxy sends commands to the pytauri subprocess to create, mutate, and attach native OS menus. See the Native Menus guide for usage patterns and examples.

---

pywry.menu_proxy.MenuProxy

MenuProxy(menu_id: str, handlers: dict[str, Callable[..., Any]] | None = None)

Proxy for a native menu living in the pytauri subprocess.

Stores the {item_id: handler} map extracted from items at creation time. Call :meth:register_handlers with a window label to wire everything up before the window is shown.

Parameters:

Name	Type	Description	Default
menu_id	str	The menu identifier (matches the subprocess-side Menu ID).	required
handlers	dict[str, Callable]	Mapping of item_id → click handler extracted from item configs.	None

Attributes

_menu_id instance-attribute

_menu_id = menu_id

_handlers instance-attribute

_handlers: dict[str, Callable[..., Any]] = handlers or {}

_registered_labels instance-attribute

_registered_labels: set[str] = set()

id property

id: str

The menu identifier.

handlers property

handlers: dict[str, Callable[..., Any]]

Mapping of item_id → click handler.

Functions

create classmethod

create(menu_id: str, items: list[MenuItemKindConfig] | None = None) -> MenuProxy

Create a native menu in the subprocess.

Handlers are automatically extracted from every item that has one.

Parameters:

Name	Type	Description	Default
menu_id	str	Unique menu identifier.	required
items	list of MenuItemKindConfig	Initial menu items. Each item must implement to_dict().	None

Returns:

Type	Description
MenuProxy	Proxy connected to the created menu.

from_config classmethod

from_config(config: MenuConfig) -> MenuProxy

Create a native menu from a :class:MenuConfig.

Handlers are extracted from the config's item tree automatically.

Parameters:

Name	Type	Description	Default
config	MenuConfig	Complete menu configuration.	required

Returns:

Type	Description
MenuProxy

register_handlers

register_handlers(label: str) -> None

Register all item handlers for a window label.

Installs a single menu:click callback on label that dispatches to the correct item handler based on data["item_id"].

Safe to call multiple times — duplicate registrations are ignored.

Parameters:

Name	Type	Description	Default
label	str	The window label to register handlers on.	required

append

append(item: MenuItemKindConfig) -> None

Append an item to the end of the menu.

prepend

prepend(item: MenuItemKindConfig) -> None

Prepend an item to the beginning of the menu.

insert

insert(item: MenuItemKindConfig, position: int) -> None

Insert an item at a specific position.

remove

remove(item_id: str) -> None

Remove a menu item by ID.

set_text

set_text(item_id: str, text: str) -> None

Update the text of a menu item.

set_enabled

set_enabled(item_id: str, enabled: bool) -> None

Enable or disable a menu item.

set_checked

set_checked(item_id: str, checked: bool) -> None

Set the checked state of a check menu item.

set_accelerator

set_accelerator(item_id: str, accelerator: str | None) -> None

Set or clear the keyboard accelerator for a menu item.

set_icon

set_icon(item_id: str, icon: bytes | None, width: int = 16, height: int = 16) -> None

Set the icon for an icon menu item.

set_as_app_menu

set_as_app_menu() -> None

Set this menu as the application-level menu bar.

set_as_window_menu

set_as_window_menu(window_label: str) -> None

Attach this menu to a specific window.

Parameters:

Name	Type	Description	Default
window_label	str	The target window's label.	required

popup

popup(window_label: str, x: float | None = None, y: float | None = None) -> None

Show this menu as a context menu.

Parameters:

Name	Type	Description	Default
window_label	str	The window to show the popup on.	required
x	float or None	X coordinate (logical pixels). None uses cursor position.	None
y	float or None	Y coordinate (logical pixels). None uses cursor position.	None

destroy

destroy() -> None

Remove and destroy this menu in the subprocess.

_send_update

_send_update(operation: str, **kwargs: Any) -> None

Send a menu update command.

__repr__

__repr__() -> str