Common toolkit loading utilities and classes
This module provides common code for ETS packages that need to do GUI toolkit discovery and loading. The common patterns that ETS has settled on are that where different GUI toolkits require alternative implementations of features the toolkit is expected to provide a callable object which takes a relative module path and an object name, separated by a colon and return the toolkit’s implementation of that object (usually this is a class, but it could be anything). The assumption is that this is implemented by objects in sub-modules of the toolkit, but plugin authors are free to use whatever methods they like.
Which toolkit to use is specified via the
package, but if this is not explicitly set by an application at startup or via
environment variables, there needs to be a way of discovering and loading any
available working toolkit implementations. The default mechanism is via the
“entry point” system.
This module provides three things:
import_toolkit()that attempts to find and load a toolkit entry point for a specified toolkit name
find_toolkit()that attempts to find a toolkit entry point that works
Toolkitclass that implements the standard logic for finding toolkit objects.
These are done in a library-agnostic way so that the same tools can be used not just for different pyface backends, but also for TraitsUI and ETS libraries where we need to switch between different GUI toolkit implementations.
Note that there is no requirement for new toolkit implementations to use this
Toolkit implementation, but they should be compatible with it.
Default toolkit loading logic¶
find_toolkit() function uses the following logic when attempting
to load toolkits:
if ETSConfig.toolkit is set, try to load a plugin with a matching name. If it succeeds, we are good, and if it fails then we error out.
after that, we try every ‘pyface.toolkit’ plugin we can find. If one succeeds, we consider ourselves good, and set the ETSConfig.toolkit appropriately. The order is configurable, and by default will try to load the qt4 toolkit first, wx next, then all others in arbitrary order, and null last.
finally, if all else fails, we try to load the null toolkit.
Toolkit(package, toolkit, *packages, **traits)¶
A basic toolkit implementation for use by specific toolkits.
This implementation uses pathname mangling to find modules and objects in those modules. If an object can’t be found, the toolkit will return a class that raises NotImplementedError when it is instantiated.
The name of the package (eg. pyface)
The name of the toolkit
The packages to look in for implementations.
Attempt to import an toolkit specified by an entry point.
toolkit_object – A callable object that implements the Toolkit interface.
- Return type
RuntimeError – If no toolkit is found, or if the toolkit cannot be loaded for some reason.
find_toolkit(entry_point, toolkits=None, priorities=<function <lambda>>)¶
Find a toolkit that works.
If ETSConfig is set, then attempt to find a matching toolkit. Otherwise try every plugin for the entry_point until one works. The ordering of the plugins is supplied via the priorities function which should be suitable for use as a sorting key function. If all else fails, explicitly try to load the “null” toolkit backend. If that fails, give up.
entry_point (str) – The name of the entry point that holds our toolkits.
toolkits (collection of strings) – Only consider toolkits which match the given strings, ignore other ones.
priorities (callable) – A callable function that returns an priority for each plugin.
toolkit – A callable object that implements the Toolkit interface.
- Return type
RuntimeError – If no ETSConfig.toolkit is set but the toolkit cannot be loaded for some reason.