Skip to content

MenuManager

Manages menus with icon support and theme-aware color updates.

This class provides a declarative way to create menus with automatic icon support and theme-aware color updates. When the theme changes, all menu icons are automatically updated to match the new theme's foreground color.

The MenuManager tracks all menu items that have icons and listens for <<ThemeChanged>> events on the root window. When a theme change is detected, it recreates and updates all icons to ensure they match the new theme.

Attributes:

Name Type Description
parent Any

The parent widget (typically a Window or Toplevel).
style

The Style instance for accessing theme colors.
menu_items dict[str, tuple[Menu, int, str, int]]

Dictionary tracking menu items with icons for theme updates.

__init__ 

__init__(parent: Any)

Initialize the MenuManager.

Sets up the menu manager with the given parent widget, initializes the style and icon provider, and establishes theme change monitoring to automatically update icon colors when themes change.

Parameters:

Name Type Description Default
parent Any

The parent widget, typically a Window, Toplevel, or root widget. This is used to access the style, icon provider, and to bind theme change events.

 required

for_widget classmethod 

for_widget(widget: Any) -> MenuManager

Return the singleton MenuManager for widget's root window.

Creates one on first access and stores it on the root as _menu_manager. Use this to share icon-tracking and theme monitoring across all tk.Menu-based widgets in an application (menubars, context menus, etc.) without each one binding its own <<ThemeChanged>> handler.

translate_label staticmethod 

translate_label(text: Optional[str]) -> Optional[str]

Run a label through MessageCatalog.translate.

Semantic keys (e.g. 'table.sort_asc') become localized strings; plain text passes through unchanged because translate returns the source when no translation is registered.

resolve_icon 

resolve_icon(
    icon_spec: Union[str, dict, None],
) -> tuple[Any, Optional[str], int]

Resolve an icon spec to a (PhotoImage, name, size) triple.

Returns (None, None, 0) for empty/unsupported specs. The returned PhotoImage is the same kind MenuManager uses internally for its own menus, so the caller can pass it straight to menu.add_command(image=..., compound='left').

register_icon 

register_icon(
    menu: Menu, index: int, icon_name: str, icon_size: int
) -> None

Track a menu item for theme-aware icon re-rendering.

Call after menu.add_*(image=icon) so subsequent <<ThemeChanged>> events refresh the entry's icon color.

unregister_menu 

unregister_menu(menu: Menu) -> None

Drop all tracking entries for menu.

Call when the menu is being destroyed or fully rebuilt so stale (menu, index) references don't try to reconfigure deleted entries on the next <<ThemeChanged>>.

create_menu 

create_menu(parent: Any, items: list[dict]) -> tk.Menu

Create a menu from a list of item dictionaries.

Parameters:

Name Type Description Default
parent Any

The parent widget (Window, Toplevel, or Menu).

 required
items list[dict]

List of menu item dictionaries defining the menu structure.

 required

Returns:

Type Description
Menu

The created Menu object.