A Widget in Pyface is an object wraps a control from the underlying toolkit and provides standard traits and methods that abstract the differences between the interfaces presented by the toolkit widgets.
The actual implementation is provided by the corresponding toolkit-dependent
Widget subclass, but with shared functionality split
into separate mixins:
MWidget and so on, following
the general design described in the Overview section.
Widget instance is created only the traits
are initialized. The underlying toolkit widget is not created until the
create() method is called, which is
responsible for creating the toolkit object, configuring it, and connecting
handlers that react to changes at the toolkit level or on the traits,
keeping the state of the Python class synchronised with the state of the
underlying toolkit object. The
_create_control() method to create the
actual toolkit control and configure it, and also calls the
_add_event_listeners() method to handle hooking
up the different types of change handlers. Some widget subclasses may do
additional things in their
as appropriate for their purpose.
To destroy the toolkit object, the
method is called which cleans up the code that listens for changes to the
object, and destroys the underlying toolkit control (and, for most toolkits,
any children). The
_remove_event_listeners() method to
handle unhooking of change handlers. Some widget subclasses may do
additional things in their
Every widget has a
control trait which
holds a reference to the toolkit control that is actually doing the work.
Additionally, there is a
which references the toolkit control which is the parent of the widget’s
control, however this may be
None for top-level windows.
Additionally, every widget has two states associated with it: it can be
visible or hidden, and it can be enabled or disabled. The visibile
state is accessible via the
trait, or by calling
the enabled state is accessible via the
enabled trait, or by calling
Widgets also provide a trait
provides a string to display to the user when they hover the mouse over the
widget. If the string is empty then there will be no tooltip displayed.
The key subclasses/subinterfaces of
Additionally there are convenience methods that create message dialogs correctly parented to the window.
IDialog interface represents short-lived,
usually modal, dialog windows. Often these are standard system dialogs,
in which case the class is responsible for configuring and invoking them,
but it also includes subclasses which have custom content.
dialog = MyModalDialog() if dialog.open() == OK: # do something based on dialog state ... else: # user cancelled, clean-up if needed and stop ...
For custom dialogs, there are protected methods for creating the contents
of the dialog and its buttons. In most cases you will need to, at a minimum,
_create_dialog_area() method to
populate the widgets inside the main dialog.
Pyface provides a number of standard dialog classes and convenience functions to access them.
represents a main window of an application with the associated additional
features which go with these, such as menubars, toolbars, and status bars.
Users can supply
objects to provide the functionality, and the concrete implementations will
use these to create the toolkit-level objects.
Writers of custom subclasses will have to override the
method to populate the actual contents of the window.
IField interface is the base for widgets
which present a value to be edited by the user, such as text fields, sliders,
combo-boxes and so on. The interface is described in more detail in the
section on Fields.