Widgets

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 public API for every widget is provided by the appropriate interface class: IWidget and its subclasses such as IApplicationWindow and ITextField.

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.

Lifecycle

When a Widget instance is created only the traits are initialized. The underlying toolkit widget is not created until the widget’s 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() method calls 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 create() methods, as appropriate for their purpose.

To destroy the toolkit object, the destroy() 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 destroy() method calls the _remove_event_listeners() method to handle unhooking of change handlers. Some widget subclasses may do additional things in their destroy() methods.

Basic Interface

Every widget has a control trait which holds a reference to the toolkit control that is actually doing the work. Additionally, there is a parent trait 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 visible trait, or by calling show(). Similarly the enabled state is accessible via the enabled trait, or by calling enable().

Widgets also provide a trait tooltip that 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.

IWidget Subclasses

The key subclasses/subinterfaces of IWidget include the following.

IWindow

The IWindow interface represents a top-level window, and so provides additional traits such as size, position and title, as well as events for the window’s lifecycle and user interactions.

The open() and close() methods provide the standard way of bring up non-modal windows and closing them with the option of a user veto.

Additionally there are convenience methods that create message dialogs correctly parented to the window.

IDialog

The 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.

For modal dialogs, open() is blocking, and returns the return_code of the dialog after the user is done. Typical usage looks like:

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, override the _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.

• Standard Dialogs
  • About Dialog
  • Color Dialog
  • Confirmation Dialog
  • Directory Dialog
  • File Dialog
  • Font Dialog
  • Message Dialog
  • Progress Dialog
  • Single-Choice Dialog

IApplicationWindow

The IApplicationWindow interface 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 menu_bar_manager, status_bar_manager and tool_bar_managers 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 _create_contents() method to populate the actual contents of the window.

IField

The 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.