Toolkits

Pyface is intended to provide a common API on top of distinct GUI backends to permit the same code to be run on different systems with different GUI toolkits and produce similar results. Pyface comes with three built-in backends in the core library—Qt, WxPython, and a null backend—but provides hooks for other projects to contribute toolkits and have them be discoverable.

Toolkit Selection

Pyface uses Traits’ traits.etsconfig to determine the current toolkit being used. Applications can control which toolkit to use in two ways:

• by setting the environment variable ETS_TOOLKIT to the name of the desired toolkit.

• by importing ETSConfig and setting its toolkit attribute appropriately:

  from tratis.etsconfig.api import ETSConfig
  ETSConfig.toolkit = 'qt'
  

  This must be done _before_ any widget imports in your application. Precisely, this must be set before the first call to pyface.base_toolkit.find_toolkit() (which usually happens as a side-effect of importing pyface.toolkit).

If for some reason Pyface can’t load a deliberately specified toolkit, then it will raise an exception.

If the toolkit is not specified, Pyface will try to load the qt or wx toolkits, in that order, and then any other toolkits that it knows about other than null. If all of those fail, then it will try to load the null toolkit.

Pyface tries to defer toolkit selection as long as possible until it is actually needed because importing a toolkit tends to be slow and have significant side-effects. Very occasionally an application or test suite may need to ensure that the toolkit has been selected (for example, to enable “ui” dispatch from background threads in Traits). This can be achieved by either importing pyface.toolkit or, more directly, by calling pyface.base_toolkit.find_toolkit().

Once selected, the toolkit infrastructure is largely transparent to the application.

Toolkit Objects

The selection of the correct backend object is carried out by each toolkit’s toolkit object. For all built-in toolkits, this is an instance of the pyface.base_toolkit.Toolkit class, but it is possible that other backends may use their own objects. The toolkit object for the toolkit that has been selected can be found as pyface.toolkit.toolkit_object.

This is a callable object which expects to be given an identifier for the widget in the form of a relative module name and the object name, separated by a ':'. This is most often used when creating new widget types for Pyface. The API module for the new widget class typically looks something like this:

from pyface.toolkit import toolkit_object
MyWidget = toolkit_object('my_package.my_widget:MyWidget')

The base toolkits use the identifier to select which module to import the toolkit object by constructing a full module path from the partial path and importing the object. For example the qt backend will look for the concrete implementation in pyface.ui.qt.my_package.my_widget while the wx backend will look for pyface.ui.wx.my_package.my_widget.

If no matching object is found, the toolkit will return a special Undefined class that will raise NotImplementedError when instantiated.

The basic toolkit implementation provides two other features which may be of use. It has a trait that gives the name of the toolkit, and it has a list of packages that it searches when trying to import a toolkit object. This second trait provides a hook where an application can insert other packages into the search path to override the default implementations of a toolkit’s widgets, if needed.

The “qt4” Toolkit

The “qt4” toolkit is the same as the “qt” toolkit in almost all respects: in older versions of Pyface it was the standard name for all the Qt-based toolkits whether or not they were actually using Qt4.

However it does trigger some backwards-compatibility code that may be useful for legacy applications. In particular it installs import hooks that makes the pyface.ui.qt4.* package namespace an alias for pyface.ui.qt.* modules.

This backwards-compatibility code can also be invoked by setting the ETS_QT4_IMPORTS environment variable to any non-empty value, or adding an instance of the pyface.ui.ShadowedModuleFinder module finder to sys.meta_path list.

Warning

Library code which imports from pyface.ui.qt4.* should not use this compatibility code. Instead it should be updated to import from pyface.ui.qt.* as soon as practical. Backwards-compatibility can be achieved fairly easily by using pyface.toolkit.toolkit to access objects rather than direct imports.

This backwards-compatibility code will be removed in Pyface 9, and applications which rely on the particulars of the implementation are encouraged to migrate to the newer import locations as soon as practical.

Toolkit Entrypoints

Pyface uses the standard importlib_metadata “entry point” system to allow other libraries to contribute new toolkit implementations to Pyface. The toolkit selection process discussed above looks for things contributed to the pyface.toolkits entry point. These are specified in the setup.py of the third party library, something like this:

setup(
    # ... a bunch of other standard setup.py stuff
    entry_points = {
        'pyface.toolkits': [
            'my_toolkit = my_project.my_toolkit.init:toolkit_object',
        ]
    }
)

or in a pyproject.toml something like:

[project.entry-points.'pyface.toolkits']
my_toolkit = 'my_project.my_toolkit.init:toolkit_object'

The left-hand side is the name of the toolkit, suitable for use with ETSConfig, and the right-hand side is the location of a toolkit object which matches the specification above: a callable object which takes identifiers as specified and returns concrete implementations. The easiest way to do this is to follow the examples of the current toolkits and use a pyface.base_toolkit.Toolkit instance, but this is not required.