This guide is designed to act as a conceptual guide to TraitsUI, an open-source package built and maintained by Enthought, Inc. The TraitsUI package is a set of GUI (Graphical User Interface) tools designed to complement Traits, another Enthought open-source package that provides explicit typing, validation, and change notification for Python. This guide is intended for readers who are already moderately familiar with Traits; those who are not may wish to refer to the Traits User Manual for an introduction. This guide discusses many but not all features of TraitsUI. For complete details of the TraitsUI API, refer to the TraitsUI API Reference.

The Model-View-Controller (MVC) Design Pattern

A common and well-tested approach to building end-user applications is the MVC (“Model-View-Controller”) design pattern. In essence, the MVC pattern the idea that an application should consist of three separate entities: a model, which manages the data, state, and internal (“business”) logic of the application; one or more views, which format the model data into a graphical display with which the end user can interact; and a controller, which manages the transfer of information between model and view so that neither needs to be directly linked to the other. In practice, particularly in simple applications, the view and controller are often so closely linked as to be almost indistinguishable, but it remains useful to think of them as distinct entities.

The three parts of the MVC pattern correspond roughly to three classes in the Traits and TraitsUI packages.

  • Model: HasTraits class (Traits package)

  • View: View class (TraitsUI package)

  • Controller: Handler class (TraitsUI package)

The remainder of this section gives an overview of these relationships.

The Model: HasTraits Subclasses and Objects

In the context of Traits, a model consists primarily of one or more subclasses or instances of the HasTraits class, whose trait attributes (typed attributes as defined in Traits) represent the model data. The specifics of building such a model are outside the scope of this manual; please see the Traits User Manual for further information.

The View: View Objects

A view for a Traits-based application is an instance of a class called, conveniently enough, View. A View object is essentially a display specification for a GUI window or panel. Its contents are defined in terms of instances of two other classes: Item and Group. [1] These three classes are described in detail in The View and Its Building Blocks; for the moment, it is important to note that they are all defined independently of the model they are used to display.

Note that the terms view and View are distinct for the purposes of this document. The former refers to the component of the MVC design pattern; the latter is a TraitsUI construct.

The Controller: Handler Subclasses and Objects

The controller for a Traits-based application is defined in terms of the Handler class. [2] Specifically, the relationship between any given View instance and the underlying model is managed by an instance of the Handler class. For simple interfaces, the Handler can be implicit. For example, none of the examples in the first four chapters includes or requires any specific Handler code; they are managed by a default Handler that performs the basic operations of window initialization, transfer of data between GUI and model, and window closing. Thus, a programmer new to TraitsUI need not be concerned with Handlers at all. Nonetheless, custom handlers can be a powerful tool for building sophisticated application interfaces, as discussed in Controlling the Interface: the Handler.

Toolkit Selection

The TraitsUI package is designed to be toolkit-independent. Programs that use TraitsUI do not need to explicitly import or call any particular GUI toolkit code unless they need some capability of the toolkit that is not provided by TraitsUI. However, some particular toolkit must be installed on the system in order to actually display GUI windows.

TraitsUI uses a separate package, traits.etsconfig, to determine which GUI toolkit to use. This package is also used by other Enthought packages that need GUI capabilities, so that all such packages “agree” on a single GUI toolkit per application. The etsconfig package contains a singleton object, ETSConfig (importable from traits.etsconfig.api), which has a string attribute, toolkit, that signifies the GUI toolkit.

The values of ETSConfig.toolkit that are supported by TraitsUI version 8.0.0 are:

  • ‘qt’ or ‘qt4’: PyQt5, PySide2 or PySide6, which provides Python bindings for the Qt framework version 5 or 6.

  • ‘wx’: wxPython, which provides Python bindings for the wxWidgets toolkit.

  • ‘null’: A do-nothing toolkit, for situations where neither of the other toolkits is installed, but Traits is needed for non-UI purposes.

The default behavior of TraitsUI is to search for available toolkit-specific packages in the order listed, and uses the first one it finds. The programmer or the user can override this behavior in any of several ways, in the following order of precedence:

  1. The program can explicitly set ETSConfig.toolkit. It must do this before importing from any other Enthought Tool Suite component, including traits. For example, at the beginning of a program:

    from traits.etsconfig.api import ETSConfig
    ETSConfig.toolkit = 'wx'
  2. The user can define a value for the ETS_TOOLKIT environment variable.

Toolkit selection is largely carried out in Pyface rather than TraitsUI, where further details can be found.

The “qt4” Toolkit

The “qt4” toolkit is the same as the “qt” toolkit in almost all respects: in older versions of TraitsUI 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 traitsui.qt4.* package namespace an alias for traitsui.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.


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

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

Structure of this Manual

The intent of this guide is to present the capabilities of the TraitsUI package in usable increments, so that you can create and display gradually more sophisticated interfaces from one chapter to the next.