class fields.Field(Control, TextEditor)

Field is an abstract base class for controls that edit a value with a textual representation. It provides facilities for converting between the text and internal representations of the value, for specifying minimum and maximum allowed values, and controlling whether the value is allowed to be empty and what representation to use for an empty value.

A Field can be in two states, editing and non-editing. In the non-editing state, the control displays the value to which it is linked via its ref attribute. When the user focuses the control and begins typing, it switches to the editing state. In this state, the text may be edited but the associated value is not yet updated. When the Return, Enter or Tab key is pressed, or a mouse click occurs anywhere outside the field, the value is updated and the control returns to the non-editing state. Updating of the value can also be forced by calling the commit() method.

Concrete subclasses of Field include TextField, IntField and FloatField.


Field(width = None)
The width may be an integer or a string, as for TextEditor. If no width is specified, but a value for min and/or max is specified at construction time, the width will be determined from the min or max value. If no other way of determining the width is available, it defaults to 100.


ref = None
Reference to the value to be edited. See Control.

min = None
Minimum allowable value. If None, no minimum value will be enforced.

max = None
Maximum allowable value. If None, no maximum value will be enforced.

empty = NotImplemented
Internal value to use when the field is empty. If set to NotImplemented, the user is not allowed to enter an empty value.

format = "%s"
Format string to use when converting the internal representation to text. See also format_value() below.

A function for converting from text to the internal representation. Typically a type object, but can be any callable object.

Read only. A boolean which is true when the control is in the editing state.


When in the editing state, causes the control's value to be updated and places the control in the non-editing state.

Default Methods

This method is called to format the value for display. By default it uses the format string specified by the format attribute. You can override this method to format the value in a different way.