Skip to content

Dialog

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.

Attributes:

Name Type Description
result Any

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

Parameters:

Name Type Description Default
master Master

Parent widget for the dialog. If None, uses the default root window.

 None
title str

Dialog window title displayed in the title bar. Defaults to "bootstack".

 'bootstack'
content_builder Optional[ContentBuilder]

Optional callback function to build dialog content. Receives a Frame widget as parameter. Should pack/grid widgets into it. If None, dialog will have no content area. Defaults to None.

 None
footer_builder Optional[FooterBuilder]

Optional callback function to build custom footer. Receives a Frame widget as parameter. If provided, replaces the standard button footer. Defaults to None.

 None
buttons Iterable[ButtonSpec] | None

Optional list of DialogButton or dict specifications for footer buttons. Ignored if footer_builder is provided. Button order in list determines right-to-left display order (first button appears rightmost). Defaults to None (no footer).

 None
minsize tuple[int, int] | None

Optional (width, height) minimum window size in pixels. Defaults to None (no minimum).

 None
maxsize tuple[int, int] | None

Optional (width, height) maximum window size in pixels. Defaults to None (no maximum).

 None
resizable tuple[bool, bool] | None

Optional (width, height) tuple of booleans controlling window resize. (True, True) allows full resizing, (False, False) prevents all resizing. Defaults to (False, False).

 (False, False)
alert bool

If True, plays system alert sound when dialog is shown. Defaults to False.

 False
mode DialogMode

Dialog interaction mode. - "modal": Blocks parent window interaction, requires user response - "popover": Closes automatically when focus leaves dialog - "sheet": Like "modal" but on macOS applies the Cocoa sheet window class for a chromeless, sheet-styled dialog tied to its parent (via transient). Falls back to plain modal behavior on Windows/Linux where there's no equivalent. Defaults to "modal".

 'modal'
frameless bool

If True, removes window decorations (title bar, borders) and adds a solid border frame around the dialog content. Useful for dropdown-style menus or popover UIs. Defaults to False.

 False
window_style str | None

Windows-only pywinstyles effect. Options include 'mica', 'acrylic', 'aero', 'transparent', 'win7', etc. If None (default), uses AppSettings.window_style.

 None

toplevel property 

toplevel: Toplevel | None

Read-only access to the underlying toplevel window.

show 

show(
    position: Optional[Tuple[int, int]] = None,
    modal: Optional[bool] = None,
    *,
    anchor_to: Optional[
        Union[Widget, Literal["screen", "cursor", "parent"]]
    ] = None,
    anchor_point: AnchorPoint = "center",
    window_point: AnchorPoint = "center",
    offset: Tuple[int, int] = (0, 0),
    auto_flip: Union[
        bool, Literal["vertical", "horizontal"]
    ] = False,
)

Create and show the dialog with flexible positioning options.

Parameters:

Name Type Description Default
position Optional[Tuple[int, int]]

Optional (x, y) coordinates to position the dialog. If provided, takes precedence over anchor-based positioning.

 None
modal Optional[bool]

Override the mode's default modality. - If None, uses mode: - "modal": grab_set + wait_window - "popover": no grab, but wait_window

 None
anchor_to Optional[Union[Widget, Literal['screen', 'cursor', 'parent']]]

Positioning target. Can be: - Widget: Anchor to a specific widget - "screen": Anchor to screen edges/corners - "cursor": Anchor to mouse cursor location - "parent": Anchor to parent window (same as widget) - None: Centers on parent (default)

 None
anchor_point AnchorPoint

Point on the anchor target (n, s, e, w, ne, nw, se, sw, center). Default 'center'.

 'center'
window_point AnchorPoint

Point on the dialog window (n, s, e, w, ne, nw, se, sw, center). Default 'center'.

 'center'
offset Tuple[int, int]

Additional (x, y) offset in pixels from the anchor position.

 (0, 0)
auto_flip Union[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

 False
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