The basic purpose of Pyface is to provide an abstraction layer between the interface exposed to the users of the library and the actual implementation in terms of the underlying GUI library. To achieve this, Pyface provides three types of object:
- Interface classes express the public interface for Pyface widgets. They use Trait’s Interfaces to express this. Interface objects are not meant to be instantiated, but should be used to express the types of objects that you expect in a toolkit-independent manner.
- Mixin classes provide concrete implementations of certain functionality for a widget that are not toolkit-dependent, or can be provided purely using other parts of the abstract interface. Concrete implementations can choose to inherit from the mixin class to use that common functionality.
- Toolkit Implementations
- Each toolkit can provide classes that are full implementations of the abstract Interfaces using the widgets and other facilities provided by the toolkit.
In addition there is a class heirarchy othogonal to this specifying the relationship between different types of widgets. A “dialog” for example, is a subclass of “window”, which is in turn a subclass of “widget”. This heirarchy roughly mirrors the typical widget class system of a GUI library, and so presents a general framework that can be abstracted between different backends.
For example, a file dialog is specified using the
interface, which in turn inherits from
IWidget, and the full usable interface
is the combination of these. The
MFileDialog class provides some
mix-in capabilities around the expression of filters for file types. And then
there are two concrete implementations,
for wxPython and
pyface.ui.qt4.file_dialog.FileDialog for the Qt
backends. These toolkit classes in turn inherit from the appropriate toolkit’s
Widget classes, as well
Finally, the toolkit selected for use determines which backend class is actually used when a program is run, allowing a developer to write code like the following to generate a platform-independent file dialog:
from pyface.api import FileDialog, OK def open_python_file(): """ Ask the user for a Python file to open """ dialog = FileDialog(action='open', wildcard=FileDialog.WILDCARD_PY) result = dialog.open() if result == OK: return dialog.path else: return None
There is a lot more to the library than just this, of course, but with this framework in mind you can understand how Pyface is intended to be used.
Building A Pyface Application¶
For a minimal Pyface application, you need to do two things: create a subclass
ApplicationWindow containing your UI,
and use the
pyface.gui.GUI instance to start your application’s
This example shows how to create an application window containing a simple text label:
from pyface.api import ApplicationWindow, HeadingText class MainWindow(ApplicationWindow): """ The main application window. """ # The window title. title = 'Hello World' def _create_contents(self, parent): """ Create the editor. """ self._label = HeadingText(parent, text="Hello World") return self._label.control
IApplicationWindow interface also allows you to provide
methods for creating menus, toolbars, and so forth. In this example we have
used a generic cross-toolkit label widget for our content, but if we are
willing to forgo cross-platform compatibility we could create toolkit-specific
Having defined your main window class, you then need to create an instance of
it, open it, and start the event loop. We do this in a
for our application:
from pyface.api import GUI def main(): # Create the GUI. gui = GUI() # Create and open the main window. window = MainWindow() window.open() # Start the GUI event loop! gui.start_event_loop() # Application entry point. if __name__ == '__main__': main()
An immediate desire when building a traditional GUI application is to add
menus and toolbars to allow basic user interaction via the mouse or keyboard
shortcuts. Pyface provides these via
Actions provide the information needed to display a menu or toolbar item and
such as the title text, accelerator keys, icon and whether the action has
“radio” or “toggle” behaviour. In addition the action needs to supply a
function to perform when the user activates it. This is usually done by
either supplying a callable for the
on_perform trait of the
Action or by subclassing and overriding the
on_perform is a callable that should expect no parameters to
be passed to it, so it should have all the context it needs to do what it
needs. At its simplest, the action might look something like this:
from pyface.action.api import Action def hello_world(): print 'Hello world!' hello_action = Action( name="Hello", tooltip="Say hello", accelerator="Ctrl+Shift+H", on_perform=hello_world, )
The equivalent written as a subclass of
Action would look like
from pyface.action.api import Action class HelloAction(Action): #: The action's name (displayed on menus/tool bar tools etc). name = "Hello" #: Keyboard accelerator. accelerator = "Ctrl+Shift+H" #: A short description of the action used for tooltip text etc. tooltip = "Say hello" def perform(self, event=None): print 'Hello world!'
Because actions usually require some context, the most common use will be to
supply a class method as the
on_perform callable. And for toolbar
actions, you usually want to supply an
image trait as well.
Actions can be organized hierarchically into groups within menus and toolbars, and a menubar can contain multiple menus. The following example shows how to define a very simple Python editor application with menus:
class MainWindow(ApplicationWindow): """ The main application window. """ def __init__(self, **traits): """ Creates a new application window. """ # Base class constructor. super(MainWindow, self).__init__(**traits) # Add a menu bar. self.menu_bar_manager = MenuBarManager( MenuManager( Group( Action( name='&Open...', accelerator='Ctrl+O', on_perform=self.open_file ), Action( name='&Save', accelerator='Ctrl+S', on_perform=self.save_file ), id='document_group', ), Action( name='&Close', accelerator='Ctrl+W', on_perform=self.close ), name='&File') ) def open_file(self): """ Open a new file. """ if self.control: dlg = FileDialog(parent=self.control, wildcard="*.py") if dlg.open() == OK: self._editor.path = dlg.path def save_file(self): """ Save the file. """ if self.control: try: self._editor.save() except IOError, e: # If you are trying to save to a file that doesn't exist, # open up a FileDialog with a 'save as' action. dlg = FileDialog( parent=self.control, action='save as', wildcard="*.py") if dlg.open() == OK: self._editor.save(dlg.path) def _create_contents(self, parent): """ Create the editor. """ self._editor = PythonEditor(parent) return self._editor.control
Toolbars work in a similar way to menus, each toolbar having a collection of
groups of actions. However in addition to the options available to a menu
item, a toolbar item can have an
Action that provides a widget
to embed in the toolbar. At its simplest this is done by specifying the
style to be
"widget" and then providing a
control_factory callable that returns a toolkit object.
There are two utility subclasses provided to handle common use cases. The
FieldAction class takes a
IField class and a dictionary of parameters
that specify the behaviour, and use this as the factory to create the
FieldAction also overrides the
perform method to pass the new value of the field
The second is the
class which embeds an arbitrary TraitsUI in the toolbar.
Pyface provides two application frameworks that help in building complex, composable interfaces for applications. The first is Workbench, which is an older framework; the second is Tasks, which is newer and more flexible than Workbench. The Tasks framework is under active support, while Workbench is a legacy codebase.
For new projects, it’s recommended that developers should use Tasks if they need such an application framework.
Both these frameworks are designed to be extensible using Envisage plugins, and are currently documented as part of the Envisage project’s documentation.
Examples of building simple applications in each framework are provided in the Pyface examples, and the APIs are auto-documented in these documents.
Pyface and TraitsUI¶
Pyface is generally a lower-level GUI toolkit than TraitsUI, and many users will find that TraitsUI provides all that they need. TraitsUI uses Pyface for some of its functionality, and the Workbench and Tasks are designed to easily incoprorate UIs built using TraitsUI.
It is fairly straightforward to use or embed a TraitsUI view into a Pyface
widget: the basic approach is to call
kind='panel' from inside the
_create_control() method (or
_create_contents() when embedding in a window
or dialog) of the widget, extract the toolkit control from the resulting
ui object, and return or embed that control.
For example, to embed a TraitsUI View in an
you might do something like this:
class Person(HasTraits): """ Model class representing a person """ #: the name of the person name = Str #: the age of the person age = Int(18) #: the gender of the person gender = Enum('female', 'male') # a default traits view view = View( Item('name', resizable=True), Item('age', resizable=True), Item('gender', resizable=True), resizable=True, ) class MainWindow(ApplicationWindow): """ The main application window. """ # The size of the window. size = (320, 240) # The window title. title = 'TraitsUI Person' # The traits object to display person = Instance(Person, ()) def _create_contents(self, parent): """ Create the editor. """ self._ui = self.person.edit_traits(kind='panel', parent=parent) return self._ui.control
A similar approach can be used when working with Enaml, Matplotlib, or other libraries which can produce a toolkit-specific control.