bootstack.dialogs.Dialog#

class bootstack.dialogs.Dialog(*, title='bootstack', content_builder=None, footer_builder=None, buttons=None, min_size=None, max_size=None, resizable=(False, False), alert=False, mode='modal', undecorated=False, window_style=None, on_close=None, surface=None, parent=None)#

Bases: object

A flexible dialog window using the builder pattern.

Dialog provides a composition-based approach to creating modal and non-modal dialogs with customizable content, buttons, and behavior. Instead of requiring inheritance, you provide callback functions to build the dialog content and optionally the footer.

The dialog manages window creation, positioning, button handling, and keyboard shortcuts automatically.

result#

The value returned by the dialog after closing. Set automatically when a button with a result value is clicked. Defaults to None.

Parameters:

  • title (str) – Dialog window title. Defaults to 'bootstack'.

  • content_builder (Optional[ContentBuilder]) – Callback to build the dialog body. Receives an internal frame — place widgets into it using raw internal constructors or by calling widget._internal directly. If None, the dialog has no body area.

  • footer_builder (Optional[FooterBuilder]) – Callback to build a fully custom footer. Replaces the standard button row when provided.

  • buttons (Iterable[ButtonSpec] | None) – List of DialogButton (or equivalent dicts) for the footer. Ignored when footer_builder is given. Buttons are displayed right-to-left — the first entry appears rightmost.

  • min_size (tuple[int, int] | None) – Minimum window size as (width, height) in pixels.

  • max_size (tuple[int, int] | None) – Maximum window size as (width, height) in pixels.

  • resizable (tuple[bool, bool] | None) – (width, height) booleans controlling resize. Default (False, False).

  • alert (bool) – Play the system alert sound when the dialog is shown. Default False.

  • mode (DialogMode) – Interaction mode. 'modal' (default) blocks the parent; 'popover' closes on focus loss; 'sheet' renders as a Cocoa sheet on macOS and falls back to modal elsewhere.

  • undecorated (bool) – Remove OS window decorations. Useful for popover-style dialogs. Default False.

  • window_style (WindowStyle | str | None) – Windows-only pywinstyles effect ('mica', 'acrylic', 'aero', etc.). Defaults to the app’s window style setting.

  • on_close (Callable[[], Any] | None) – Callback fired when the dialog is closed by any means (button click, X button, Escape, or focus loss in popover mode). Receives no arguments. Useful for non-modal dialogs where show() does not block.

  • parent (Master) – Parent window. Defaults to the active root window.

property toplevel: Toplevel | None#

Read-only access to the underlying toplevel window.

show(*, position=None, modal=None, anchor_to=None, anchor_point='center', window_point='center', offset=(0, 0), auto_flip=False)#

Create and show the dialog with flexible positioning options.

Parameters:

  • position (Tuple[int, int] | None) – Optional (x, y) coordinates to position the dialog. If provided, takes precedence over anchor-based positioning.

  • modal (bool | None) – Override the mode’s default modality. When None, follows the mode — "modal" grabs focus and waits for the dialog to close; "popover" waits without grabbing.

  • anchor_to (Widget | Literal['screen', 'cursor', 'parent'] | None) – Positioning target. A widget anchors to that widget; "screen" anchors to the screen edges/corners; "cursor" anchors to the mouse cursor; "parent" anchors to the parent window; and None (default) centers on the parent.

  • anchor_point (Literal['n', 's', 'e', 'w', 'ne', 'nw', 'se', 'sw', 'center']) – Point on the anchor target (n, s, e, w, ne, nw, se, sw, center). Default ‘center’.

  • window_point (Literal['n', 's', 'e', 'w', 'ne', 'nw', 'se', 'sw', 'center']) – Point on the dialog window (n, s, e, w, ne, nw, se, sw, center). Default ‘center’.

  • offset (Tuple[int, int]) – Additional (x, y) offset in pixels from the anchor position.

  • auto_flip (bool | Literal['vertical', 'horizontal']) – Smart positioning to keep window on screen. - False: No flipping (default) - True: Flip both vertically and horizontally as needed - ‘vertical’: Only flip up/down - ‘horizontal’: Only flip left/right

Positioning Logic:

  1. If position is provided: Use explicit coordinates

  2. If anchor_to is provided: Use anchor-based positioning

  3. Default: Center on parent window