Skip to content

Field

Bases: EntryMixin, Frame

A flexible generic composite entry field widget.

Field is a base composite widget that combines a label, entry input, and message area into a complete input field component. It serves as the foundation for creating specialized entry widgets like TextEntry, PasswordEntry, NumberEntry, and other custom entry types.

The widget automatically handles layout, focus states, validation feedback, and provides a consistent API for all entry-based components. It supports both text and numeric input types through the kind parameter.

Events

  • <<Input>>: Triggered on each keystroke. Provides event.data with keys: text.

  • <<Change>>: Triggered when value changes after commit. Provides event.data with keys: value, prev_value, text.

  • <<Valid>>: Triggered when validation passes. Provides event.data with keys: value, is_valid (True), message.

  • <<Invalid>>: Triggered when validation fails. Provides event.data with keys: value, is_valid (False), message.

  • <<Validate>>: Triggered after any validation. Provides event.data with keys: value, is_valid (bool), message.

Attributes:

Name Type Description
variable Variable

Tkinter Variable linked to entry text.
signal Signal

Signal object for reactive updates.

value property writable 

value

Get or set the parsed value via the underlying entry widget.

entry_widget property 

entry_widget: NumberEntryPart | TextEntryPart

Get the underlying entry widget.

label_widget property 

label_widget

Get the label widget.

message_widget property 

message_widget

Get the message widget.

addons property 

addons

Get the dictionary of inserted addon widgets

__init__ 

__init__(
    master: Master = None,
    *,
    value: str | int | float = None,
    label: str = None,
    message: str = None,
    show_message: bool = False,
    required: bool = False,
    kind: FieldKind = "text",
    **kwargs: Any,
)

Initialize a Field widget.

Creates a composite entry field with optional label, message area, and validation support. The field type is determined by the 'kind' parameter, which selects either TextEntryPart or NumberEntryPart as the underlying entry widget.

Parameters:

Name Type Description Default
master Master

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

 None
value str | int | float

Initial value to display. Can be str, int, or float depending on the field kind. For 'text' kind, should be a string. For 'numeric' kind, can be int or float. Default is None.

 None
label str

Optional label text to display above the entry field. If required=True, an asterisk (*) is automatically appended to indicate the field is mandatory.

 None
message str

Optional message text to display below the entry field. Used for hints, instructions, or help text. This text is replaced by validation error messages when validation fails, and restored when validation passes. Default is None (no message).

 None
show_message bool

If True, displays the message area below the field. If False, hides the message area entirely (validation errors won't be shown). Default is True.

 False
required bool

If True, marks the field as required and automatically adds a 'required' validation rule. An asterisk (*) is appended to the label. The field cannot be left empty. Default is False.

 False
kind FieldKind

Type of entry field to create. Either 'text' for text input (uses TextEntryPart) or 'numeric' for numeric input (uses NumberEntryPart). Default is 'text'.

 'text'

Other Parameters:

Name Type Description
value_format str

ICU format pattern for parsing/formatting.
allow_blank bool

Allow empty input.
locale str

Locale for formatting (e.g., 'en_US').
initial_focus bool

Focus on creation.
show str

Character to mask input (e.g., '*' for passwords).
width int

Width in characters.
font str

Font specification.
justify str

Text alignment ('left', 'center', 'right').
minvalue int | float

Minimum allowed value (numeric kind only).
maxvalue int | float

Maximum allowed value (numeric kind only).
increment int | float

Step size for up/down arrows (numeric kind only).
wrap bool

Wrap around at boundaries (numeric kind only).

get 

get()

Return the raw text from the underlying entry widget.

disable 

disable()

Disable the field, preventing user input.

enable 

enable()

Enable the field, allowing user input.

readonly 

readonly(value: bool = None)

Set or toggle the readonly state of the field.

insert_addon 

insert_addon(
    widget: Type[Union[Button, Label, CheckButton]],
    position: Literal["before", "after"],
    name: str | None = None,
    pack_options: dict[str, Any] = None,
    **kwargs: Any,
)

Insert a widget addon before or after the entry input.

Addons are Button, Label, or Checkbutton widgets positioned inside the field container, either before (left of) or after (right of) the entry input. Common use cases include search buttons, icons, clear buttons, or status indicators.

The addon widget automatically: - Inherits the field's disabled state - Participates in focus state styling (highlights field on addon focus) - Is stored in the addons dictionary for later reference

Parameters:

Name Type Description Default
widget Type[Union[Button, Label, CheckButton]]

Widget class to instantiate. Must be Button, Label, or Checkbutton.

 required
position Literal['before', 'after']

Position relative to the entry input: - 'before': Insert to the left of the entry (prefix) - 'after': Insert to the right of the entry (suffix)

 required
name str | None

Optional name for the addon. If provided, the addon can be retrieved from the addons dictionary using this name. If None, the widget's string representation is used as the key.

 None
pack_options dict[str, Any]

Optional dictionary of additional pack() options to apply when placing the addon widget. Common options include padx, pady, etc. The side and after/before options are set automatically based on position.

 None
**kwargs Any

Additional keyword arguments passed to the widget constructor. For Button: text, command, icon, bootstyle, etc. For Label: text, icon, image, bootstyle, etc. Note: bootstyle and takefocus are set automatically but can be overridden.

 {}