create_menu

Create a menu with icon and theme support.

This is a convenience function that creates or retrieves a MenuManager for the parent window and uses it to build a menu from a declarative structure. The resulting menu automatically updates icon colors when the theme changes.

Each menu item is defined by a dictionary that can contain

label (str): The text displayed for the menu item
icon (str or dict): Icon specification. Can be a string icon name (e.g., "folder2-open") or a dict with 'name' and 'size' keys (e.g., {"name": "folder2-open", "size": 20})
items (list): List of submenu items for cascade menus
command (callable): Callback function executed when clicked
type (str): Menu item type - 'command', 'checkbutton', 'radiobutton', or 'separator'
variable (Variable): Tkinter variable for checkbutton/radiobutton
value (Any): Value for radiobutton items
name (str): Optional Tcl widget name for the cascade. On macOS three names trigger system-native menu integration: 'apple' gives you the application menu (Tk auto-fills it with About, Hide, Hide Others, Show All, Quit; any items you add appear before the system items), 'window' gets auto-populated with open Toplevels, and 'help' enables system Help search. Ignored on Win/Linux.
shortcut (str): Platform-aware accelerator. Accepts a registered shortcut key (e.g. 'save' if you've called Shortcuts.register('save', 'Mod+S', save_file)) or a modifier pattern like 'Mod+S', 'Ctrl+Shift+N', 'F5'. Renders as ⌘S on macOS and Ctrl+S on Win/Linux. For the actual keypress binding, register the shortcut and call Shortcuts.bind_to(app) — that's the canonical pathway.
accelerator (str): Legacy literal display string passed straight through to tk.Menu (e.g. 'Ctrl+S'). No platform translation. Prefer shortcut for new code. If both are provided, accelerator wins.
Any other valid Tkinter menu item options (underline, etc.)

Parameters:

Name	Type	Description	Default
`parent`	`Any`	The parent widget (Window, Toplevel, or Menu). If a Window or Toplevel is provided, the menu becomes the window's menubar. If a Menu is provided, items are added to that menu.	required
`items`	`list[dict]`	List of dictionaries defining the menu structure. Each dictionary represents a menu item with its configuration.	required

Returns:

Type	Description
`Menu`	The created Menu object. For window menubars, this is the menubar
`Menu`	itself. For menus attached to other widgets, this is the menu.

Examples:

Basic menubar with icons:

import bootstack as bs

app = bs.App()

menu_items = [
    {
        "label": "File",
        "items": [
            {"label": "New", "icon": "file-plus", "command": new_file},
            {"label": "Open", "icon": "folder2-open", "command": open_file},
            {"type": "separator"},
            {"label": "Exit", "icon": "x-circle", "command": app.quit}
        ]
    },
    {
        "label": "Edit",
        "items": [
            {"label": "Undo", "icon": "arrow-counterclockwise"},
            {"label": "Redo", "icon": "arrow-clockwise"}
        ]
    }
]

bs.create_menu(app, menu_items)
app.mainloop()

Nested submenus with custom icon sizes:

menu_items = [
    {
        "label": "File",
        "items": [
            {
                "label": "Recent",
                "icon": {"name": "clock-history", "size": 18},
                "items": [
                    {"label": "Document 1.txt"},
                    {"label": "Document 2.txt"}
                ]
            }
        ]
    }
]

Menu with checkbuttons and radiobuttons:

view_var = bs.BooleanVar(value=True)
theme_var = bs.StringVar(value="light")

menu_items = [
    {
        "label": "View",
        "items": [
            {
                "label": "Show Toolbar",
                "type": "checkbutton",
                "variable": view_var
            }
        ]
    },
    {
        "label": "Theme",
        "items": [
            {
                "label": "Light",
                "type": "radiobutton",
                "variable": theme_var,
                "value": "light"
            },
            {
                "label": "Dark",
                "type": "radiobutton",
                "variable": theme_var,
                "value": "dark"
            }
        ]
    }
]