Form

Bases: Frame

A configurable form that can be generated from data or explicit items.

Form is a field manager that provides a domain-specific API for accessing and manipulating form fields and their values.

Field Access

field(key) — returns the Field widget for a key
fields() — returns all Field widgets in order
keys() — returns all field keys in order

Value Operations

get_field_value(key) — get a single field's value
set_field_value(key, value) — set a single field's value
get() / set(values) — get/set all values as a dict
value property — get/set all values as a dict

Variable & Signal Access: - field_variable(key) — get Tk Variable for a field - field_signal(key) — get Signal for a field's value - field_textsignal(key) — get Signal for a field's text

Attributes:

Name	Type	Description
`data`	`dict`	Current form data (read-only property).
`value`	`dict`	Alias for form data (get/set property).
`result`	`Any`	Result value set by button commands.

Parameters:

Name	Type	Description	Default
`master`	`Master`	Parent widget.	`None`
`data`	`dict[str, Any] \| None`	Initial data backing the form. If items are not provided, field items are inferred from the keys and value types.	`None`
`items`	`Sequence[FormItem \| Mapping[str, Any]] \| None`	Optional explicit form definition. Accepts dictionaries that match the FieldItem/GroupItem/TabsItem shapes or the dataclass instances directly.	`None`
`col_count`	`int`	Number of columns at the top level.	`1`
`min_col_width`	`int`	Minimum width for each column in pixels.	`DEFAULT_MIN_COL_WIDTH`
`on_data_changed`	`Callable[[dict[str, Any]], Any] \| None`	Optional callback invoked with the updated data dict whenever a field value changes.	`None`
`width`	`int \| None`	Requested width for the form container.	`None`
`height`	`int \| None`	Requested height for the form container.	`None`
`accent`	`str \| None`	Accent token for the form container (e.g., 'primary', 'secondary').	`None`
`buttons`	`Sequence[ButtonInput] \| None`	Optional footer buttons. Accepts plain strings, DialogButton instances, or dictionaries that map to DialogButton kwargs.	`None`
`**kwargs`	`Any`	Additional Frame configuration options.	`{}`

data `property`

data: dict[str, Any]

Current data backing the form.

value `property` `writable`

value: dict[str, Any]

Get or set all form field values as a dictionary.

init

__init__(
    master: Master = None,
    *,
    data: dict[str, Any] | None = None,
    items: Sequence[FormItem | Mapping[str, Any]]
    | None = None,
    col_count: int = 1,
    min_col_width: int = DEFAULT_MIN_COL_WIDTH,
    on_data_changed: Callable[[dict[str, Any]], Any]
    | None = None,
    width: int | None = None,
    height: int | None = None,
    accent: str | None = None,
    buttons: Sequence[ButtonInput] | None = None,
    **kwargs: Any,
) -> None

Build a configurable form from data or explicit items.

Parameters:

Name	Type	Description	Default
`master`	`Master`	Parent widget.	`None`
`data`	`dict[str, Any] \| None`	Initial data backing the form; keys become field names.	`None`
`items`	`Sequence[FormItem \| Mapping[str, Any]] \| None`	Explicit form layout (FieldItem/GroupItem/TabsItem or mappings).	`None`
`col_count`	`int`	Number of columns at the top level.	`1`
`min_col_width`	`int`	Minimum width per column in pixels.	`DEFAULT_MIN_COL_WIDTH`
`on_data_changed`	`Callable[[dict[str, Any]], Any] \| None`	Callback invoked with updated data when a field changes.	`None`
`width`	`int \| None`	Requested form width; if None, size naturally.	`None`
`height`	`int \| None`	Requested form height; if None, size naturally.	`None`
`accent`	`str \| None`	Accent token for the form container.	`None`
`buttons`	`Sequence[ButtonInput] \| None`	Optional footer buttons (DialogButton, mapping, or string).	`None`
`**kwargs`	`Any`	Additional Frame configuration options.	`{}`

validate

validate() -> bool

Run validation rules on all field widgets; returns True if all pass.

field

field(key: str) -> Field

Return the Field widget for the given key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The field key.	required

Returns:

Type	Description
`Field`	The Field widget instance.

Raises:

Type	Description
`KeyError`	If no field with the given key exists.

fields

fields() -> tuple[Field, ...]

Return all field widgets in insertion order.

Returns:

Type	Description
`tuple[Field, ...]`	Tuple of Field widget instances.

keys

keys() -> tuple[str, ...]

Return all field keys in insertion order.

Returns:

Type	Description
`tuple[str, ...]`	Tuple of field key strings.

get_field_value

get_field_value(key: str) -> Any

Return the current value of the field.

Parameters:

Name	Type	Description	Default
`key`	`str`	The field key.	required

Returns:

Type	Description
`Any`	The current field value.

Raises:

Type	Description
`KeyError`	If no field with the given key exists.

set_field_value

set_field_value(key: str, value: Any) -> None

Set the value of the field.

Parameters:

Name	Type	Description	Default
`key`	`str`	The field key.	required
`value`	`Any`	The new value to set.	required

Raises:

Type	Description
`KeyError`	If no field with the given key exists.

field_variable

field_variable(key: str) -> Variable | None

Return the Tk Variable for the field.

Parameters:

Name	Type	Description	Default
`key`	`str`	The field key.	required

Returns:

Type	Description
`Variable \| None`	The Tk Variable, or None if not available.

field_signal

field_signal(key: str)

Return the Signal for the field value.

Parameters:

Name	Type	Description	Default
`key`	`str`	The field key.	required

Returns:

Type	Description
	The Signal, or None if not available.

field_textsignal

field_textsignal(key: str)

Return the Signal for the field text.

Parameters:

Name	Type	Description	Default
`key`	`str`	The field key.	required

Returns:

Type	Description
	The text Signal, or None if not available.

get_field_variable

get_field_variable(key: str) -> Variable | None

Return the Tk variable associated with a field key, if any.

Deprecated

Use field_variable(key) instead.

get_field_signal

get_field_signal(key: str)

Return the Signal associated with a field key, if any.

Deprecated

Use field_signal(key) instead.

get_field_textsignal

get_field_textsignal(key: str)

Return the TextSignal associated with a field key, if any.

Deprecated

Use field_textsignal(key) instead.

get

get() -> dict[str, Any]

Return all field values as a dictionary.

Returns:

Type	Description
`dict[str, Any]`	Dictionary mapping field keys to their current values.

set

set(values: Mapping[str, Any]) -> None

Set multiple field values from a dictionary.

Parameters:

Name	Type	Description	Default
`values`	`Mapping[str, Any]`	Dictionary mapping field keys to values.	required

Form

data property

value property writable

__init__

validate

field

fields

keys

get_field_value

set_field_value

field_variable

field_signal

field_textsignal

get_field_variable

get_field_signal

get_field_textsignal

get

set

data `property`

value `property` `writable`

init