Skip to content

FormDialog

A dialog window that embeds a Form widget for structured data entry.

FormDialog combines the Dialog and Form widgets to create modal or non-modal dialogs for data entry with automatic field generation or explicit layouts.

Attributes:

Name Type Description
result Any

The form data returned after closing (dict), or None if cancelled.
form Any

The embedded Form widget instance, accessible for advanced usage.

Parameters:

Name Type Description Default
master Master

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

 None
title str

Dialog window title. Defaults to "Form".

 'Form'
data dict[str, Any] | None

Initial data backing the form. Keys become field names.

 None
items Sequence[FormItem | Mapping[str, Any]] | None

Optional explicit form definition using FieldItem/GroupItem/TabsItem. If not provided, fields are inferred from data keys and types.

 None
col_count int

Number of columns for form layout. Defaults to 1.

 1
min_col_width int | None

Minimum width for each column in pixels. Defaults to the shared form default.

 None
on_data_changed Callable[[dict[str, Any]], Any] | None

Optional callback invoked when any field value changes. Receives the updated data dict as parameter.

 None
width int | None

Requested width for the form. Defaults to None (auto-size).

 None
height int | None

Requested height for the form. Defaults to None (auto-size).

 None
scrollable bool

Deprecated; FormDialog manages scrolling internally.

 True
scrollview_options dict[str, Any] | None

Additional options passed to ScrollView when scrollable is True.

 None
buttons Iterable[ButtonSpec | str] | None

Footer buttons. Can be DialogButton instances, dicts, or strings. If not provided, defaults to Cancel and OK buttons. First button appears rightmost (Bootstrap convention).

 None
minsize tuple[int, int] | None

Minimum dialog window size as (width, height). If None, automatically calculated based on col_count * min_col_width + padding. If provided, ensures width is at least the calculated minimum to prevent horizontal scrolling. Defaults to None (auto-calculate).

 None
maxsize tuple[int, int] | None

Maximum dialog window size as (width, height). Defaults to None.

 None
resizable tuple[bool, bool] | bool | None

Allow window resizing as (width, height) bools. Defaults to (True, True).

 False
alert bool

If True, plays system alert sound on show. Defaults to False.

 False
mode Literal['modal', 'popover']

Dialog interaction mode ("modal" or "popover"). Defaults to "modal".

 'modal'

toplevel property 

toplevel

Read-only access to the underlying toplevel window.

__init__ 

__init__(
    master: Master = None,
    *,
    title: str = "Form",
    data: dict[str, Any] | None = None,
    items: Sequence[FormItem | Mapping[str, Any]]
    | None = None,
    col_count: int = 1,
    min_col_width: int | None = None,
    on_data_changed: Callable[[dict[str, Any]], Any]
    | None = None,
    width: int | None = None,
    height: int | None = None,
    scrollable: bool = True,
    scrollview_options: dict[str, Any] | None = None,
    buttons: Iterable[ButtonSpec | str] | None = None,
    minsize: tuple[int, int] | None = None,
    maxsize: tuple[int, int] | None = None,
    resizable: tuple[bool, bool] | bool | None = False,
    alert: bool = False,
    mode: Literal["modal", "popover"] = "modal",
)

Initialize a FormDialog that wraps a Form inside a Dialog.

Parameters:

Name Type Description Default
master Master

Parent widget. Defaults to the default root window.

 None
title str

Dialog window title.

 'Form'
data dict[str, Any] | None

Initial data backing the form; keys become field names.

 None
items Sequence[FormItem | Mapping[str, Any]] | None

Optional explicit form layout (FieldItem/GroupItem/TabsItem or mappings).

 None
col_count int

Number of columns for the form layout.

 1
min_col_width int | None

Minimum width per column; defaults to the shared form default.

 None
on_data_changed Callable[[dict[str, Any]], Any] | None

Callback invoked when any field value changes.

 None
width int | None

Explicit form width; if None, size naturally.

 None
height int | None

Explicit form height; if None, size naturally.

 None
scrollable bool

Whether the form content should be scrollable.

 True
scrollview_options dict[str, Any] | None

Extra options passed to the ScrollView when scrollable.

 None
buttons Iterable[ButtonSpec | str] | None

Dialog footer buttons (DialogButton, mapping, or string).

 None
minsize tuple[int, int] | None

Minimum dialog window size (width, height).

 None
maxsize tuple[int, int] | None

Maximum dialog window size (width, height).

 None
resizable tuple[bool, bool] | bool | None

Bool or (width, height) tuple to allow window resizing.

 False
alert bool

Whether to play the system alert sound when shown.

 False
mode Literal['modal', 'popover']

Dialog interaction mode, "modal" or "popover".

 'modal'

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,
)

Show the form dialog and populate result when closed.

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