pyaccesskit.forms.builder¶

pyaccesskit.forms.builder ¶

Fluent builder for :class:FormSpec objects.

The builder never talks to Access. It accumulates controls and produces a validated :class:FormSpec; when obtained from db.forms.create(...) it also knows how to save itself, which builds the whole form in one atomic step (nothing is created in Access until then)::

with db.forms.create("frmCustomers", record_source="Customers") as form:
    form.textbox("CustomerName", label="Customer name")
    form.checkbox("IsActive")
    form.button("cmdClose", caption="Close", on_click="DoCmd.Close acForm, Me.Name")
# saved here; if the block raises, nothing is created

FormBuilder ¶

FormBuilder(
    name: str,
    *,
    on_save: Callable[[FormSpec], _R] | None = None,
    **form_options: Any,
)

Bases: Generic[_R]

Accumulates controls for a form and produces a :class:FormSpec.

Parameters:

Name	Type	Description	Default
`name`	`str`	Form name.	required
`on_save`	`Callable[[FormSpec], _R] \| None`	Called with the finished spec by :meth:`save` (set by `db.forms.create`); its return value is returned by :meth:`save`.	`None`
`**form_options`	`Any`	Any other :class:`FormSpec` field (`record_source`, `caption`, `default_view`...).	`{}`

is_saved `property` ¶

is_saved: bool

Whether :meth:save completed.

add ¶

add(control: ControlSpec) -> Self

Append an already-built control spec.

textbox ¶

textbox(
    field: str | None = None,
    *,
    label: str | Literal[False] | None = None,
    control_source: str | None = None,
    format: str | None = None,
    enabled: bool = True,
    locked: bool = False,
    after_update: str | Vba | None = None,
    **options: Unpack[_ControlOptions],
) -> Self

Add a text box bound to field (or showing control_source="=...").

checkbox ¶

checkbox(
    field: str | None = None,
    *,
    label: str | Literal[False] | None = None,
    enabled: bool = True,
    locked: bool = False,
    after_update: str | Vba | None = None,
    **options: Unpack[_ControlOptions],
) -> Self

Add a check box bound to field.

combobox ¶

combobox(
    field: str | None = None,
    *,
    row_source: str,
    row_source_type: RowSourceType = RowSourceType.TABLE_QUERY,
    bound_column: int = 1,
    column_count: int = 1,
    column_widths: Sequence[Length] | None = None,
    limit_to_list: bool = True,
    label: str | Literal[False] | None = None,
    enabled: bool = True,
    locked: bool = False,
    after_update: str | Vba | None = None,
    **options: Unpack[_ControlOptions],
) -> Self

Add a combo box bound to field with rows from row_source.

label ¶

label(
    caption: str, **options: Unpack[_ControlOptions]
) -> Self

Add a free-standing label.

button ¶

button(
    name: str,
    *,
    caption: str,
    on_click: str | Vba | None = None,
    section: Section = Section.DETAIL,
    at: tuple[Length, Length] | None = None,
    width: Length | None = None,
    height: Length | None = None,
    visible: bool = True,
    properties: dict[str, PropertyValue] | None = None,
) -> Self

Add a command button; on_click is the VBA body of its Click event procedure.

on_load ¶

on_load(code: str | Vba) -> Self

Set the VBA body of the form's Load event.

on_current ¶

on_current(code: str | Vba) -> Self

Set the VBA body of the form's Current event.

module_code ¶

module_code(code: str) -> Self

Append extra VBA (helper procedures, module-level declarations) to the form's module.

to_spec ¶

to_spec() -> FormSpec

Validate and return the finished :class:FormSpec.

save ¶

save() -> _R

Build the form in Access (atomically) and return the result of on_save.

Raises:

Type	Description
`PyAccessKitError`	If the builder has no save target or was already saved/discarded.

discard ¶

discard() -> None

Abandon the builder without creating anything.

pyaccesskit.forms.builder¶