Pyface provides a small collection of simple field widgets that are pre-bound to a Traits interface, so that you can use them in a cross-toolkit manner.

Where possible, these classes share a common API for the same functionality. In particular, all classes have a value trait which holds the value displayed in the field.

Fields where the value is user-editable rather than simply displayed implement the IEditableField interface. Code using the field can listen to changes in the value trait to react to the user entering a new value for the field without needing to know anything about the underlying toolkit event signalling mechanisms.

Fields inherit from IWidget and ILayoutItem which have a number of additional traits with useful features:


A tooltip for the widget, which should hold string.


A context menu for the widget, which should hold an IMenuManager instance.


A tuple holding the minimum size of a layout widget.


A tuple holding the minimum size of a layout widget.


A tuple holding information about the distribution of addtional space into the widget when growing in a layout. Higher numbers mean proportinally more space.


A tuple holding information about how the widget can grow and shrink.


A value holding the horizontal alignment of the contents of the field.


The IComboField interface has an arbitrary value that must come from a list of valid values. For non-text values, a formatter function should be provided, defaulting to str().


The ILabelField interface has a string for the value which is not user-editable.

In the Qt backend they can have an image for an icon.


The IImageField interface has an IImage for its value which is not user-editable.


The ISpinField interface has an integer for the value, and also requires a range to be set, either via setting the min/max values as a tuple to the bounds trait, or by setting values individually to minimum and maximum. The wrap trait determines whether the spinner wraps around at the extreme values.


The ITextField interface provides additional traits that specify whether the value should be updated on every keystroke (by setting update_text to "auto") or when the user has finished editing the field by moving focus away from the text field (by setting update_text to "editing_finshed").

The text field can be set to show a placeholder text to hint about the desired value that is shown when the box is empty via the placeholder trait. It can also be set to conceal typed text by setting echo to "password" (and the Qt backend has a number of other options as well). The text field can be set to read-only mode via the read_only trait.


The ITimeField interface has a datetime.time value. This value defaults to the current time.

ToggleField and Subclasses

The IToggleField interface holds a boolean value that is toggled between True and False by the widget. The interface is implemented by several different concrete classes with different appearances but similar behaviour:

  • CheckBoxField

  • RadioButtonField

  • ToggleButtonField

There is an abstract class ToggleField which implements much of the behaviour and is suitable for use by custom implementations to toggling behaviour.

All IToggleField implementations have can have label text set via the text trait, and in the Qt backend they can have an image for an icon.