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, padding=20, gap=8, parent=None, _raw_content=False)#

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. The content area is a public container set as the active parent, so the callback creates widgets directly — no parent= needed, like an App body. Declare a single parameter (def build(content): ...) to also receive the content container. 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.

  • padding (Padding) – Space in pixels between the dialog body edge and its content. Defaults to 20.

  • gap (int) – Space in pixels between stacked content widgets. Defaults to 8.

  • 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 (PublicWidgetBase | Literal['screen', 'cursor', 'parent'] | None) – Positioning target. A widget (e.g. a bs.Button) 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