bootstack.ContextMenu#

class bootstack.ContextMenu(target=None, *, min_width=150, width=None, min_height=None, height=None, anchor='nw', attach='se', offset=None, hide_on_outside_click=True, trigger='right_click', on_select=None, items=None, density='default', parent=None)#

Bases: object

A popup menu that attaches to a target widget and opens on a gesture or manual call.

The menu renders as a themed floating popup on Windows and Linux, and as a native system menu on macOS. The public API is identical across platforms.

Parameters:

  • target (Any) – Widget the menu attaches to for positioning and auto-trigger binding. Accepts any bootstack widget. If omitted, call show(position=(x, y)) manually.

  • min_width (int) – Minimum menu width in pixels. Default 150.

  • width (int | None) – Fixed menu width in pixels. Defaults to auto (uses min_width).

  • min_height (int | None) – Minimum menu height in pixels. Defaults to auto.

  • height (int | None) – Fixed menu height in pixels. Defaults to auto-size to content.

  • anchor (Anchor) – Point on the menu aligned to attach on the target. Default 'nw'.

  • attach (Anchor) – Point on the target the menu aligns to. Default 'se'.

  • offset (tuple[int, int] | None) – (dx, dy) pixel nudge applied after alignment.

  • hide_on_outside_click (bool) – Hide the menu when the user clicks outside it. Default True.

  • trigger (Literal['right_click', 'left_click', 'double_click', 'manual'] | None) – Gesture that auto-shows the menu on target. None means manual only — call show() yourself. Default 'right_click'.

  • on_select (Callable[[MenuSelectEvent], Any] | None) – Callback fired whenever any item is activated. Called with a MenuSelectEvent (type, text, value of the activated item).

  • items (list[Any] | None) – Initial items — ContextMenuItem objects or item dicts (each with a type key plus item kwargs such as text, icon, on_click).

  • density (WidgetDensity) – Item density. Default 'default'.

  • parent (Any) – Parent widget for the Tk hierarchy. Defaults to target.

property keys: tuple[str, ...]#

Keys of all items in insertion order.

add_check_item(label, *, value=False, on_click=None, key=None)#

Add a checkbutton item.

Parameters:

  • label (str) – Item label text.

  • value (bool) – Initial checked state. Default False.

  • on_click (Callable[[], Any] | None) – Callback fired when the item is toggled.

  • key (str | None) – Unique string identifier. Auto-generated if omitted.

Returns:

The key assigned to this item.

Return type:

str

add_item(label, *, on_click=None, icon=None, shortcut=None, disabled=False, key=None)#

Add a command item.

Parameters:

  • label (str) – Item label text.

  • on_click (Callable[[], Any] | None) – Callback fired when the item is clicked.

  • icon (str | None) – Icon name shown beside the label.

  • shortcut (str | None) – Keyboard shortcut hint displayed on the right. Accepts a modifier pattern ('Mod+S' → 'Ctrl+S' / '⌘S'), a key registered with the Shortcuts service, or a literal string.

  • disabled (bool) – If True, item is visible but non-interactive.

  • key (str | None) – Unique string identifier. Auto-generated if omitted.

Returns:

The key assigned to this item.

Return type:

str

add_items(items)#

Add multiple items at once.

Parameters:

items (list[ContextMenuItem | dict[str, Any]]) – List of ContextMenuItem objects or item dicts. Each dict has a type key ('command', 'check', 'radio', or 'separator') plus item kwargs such as text, icon, value, and on_click.

add_radio_item(label, *, value=None, on_click=None, key=None)#

Add a radiobutton item.

All radio items in a menu share one group — selecting one deselects the others. Use check items if you need independent toggles.

Parameters:

  • label (str) – Item label text.

  • value (Any) – Value passed to on_select when this item is selected.

  • on_click (Callable[[], Any] | None) – Callback fired when the item is selected.

  • key (str | None) – Unique string identifier. Auto-generated if omitted.

Returns:

The key assigned to this item.

Return type:

str

add_separator(*, key=None)#

Add a horizontal separator.

Parameters:

key (str | None) – Unique string identifier. Auto-generated if omitted.

Returns:

The key assigned to this separator.

Return type:

str

destroy()#

Destroy the menu and release all resources.

hide()#

Hide the menu without destroying it.

insert_item(index, type, *, on_click=None, **kwargs)#

Insert an item at a specific position.

Parameters:

  • index (int) – Zero-based position to insert at.

  • type (str) – Item type — 'command', 'check', 'radio', or 'separator'.

  • on_click (Callable[[], Any] | None) – Callback fired when the item is activated.

  • **kwargs (Any) – Other item options (text, icon, value, disabled, key, …).

Returns:

The key assigned to the new item.

Return type:

str

item(key)#

Return an item’s current configuration as a dict.

Parameters:

key (str) – Key returned by an add_* method.

move_item(key, to_index)#

Move an existing item to a new position.

Parameters:

  • key (str) – Key of the item to move.

  • to_index (int) – Target zero-based index.

remove_item(key)#

Remove an item by key.

Parameters:

key (str) – Key returned by an add_* method.

show(position=None)#

Show the menu, optionally at an explicit screen position.

Parameters:

position (tuple[int, int] | None) – Screen (x, y) coordinates. If omitted, the menu is positioned relative to its target widget.

Returns:

self — allows chaining – menu.add_item("Edit").show().

Return type:

ContextMenu

update_item(key, **kwargs)#

Reconfigure an item after creation.

Parameters:

  • key (str) – Key returned by an add_* method.

  • **kwargs (Any) – Item options to change (text, icon, disabled, on_click, …).