traitsui.extras.has_dynamic_views module

Provides a framework that assembles Traits UI Views at run time, when the view is requested, rather than at the time a class is written.

This capability is particularly useful when the object being ‘viewed’ with a Traits UI is part of a plug-in application – such as Envisage. In general, this capability allows:

  • The GUI for an object can be extendable by contributions other than from the original code writer.

  • The view can be dynamic in that the elements it is composed of can change each time it is requested.

  • Registration of a handler can be associated with the view contributions.

Either the original object writer, or a contributor, can use this framework to declare one or more dynamic views that are composed of sub-elements that only need to exist at the time the view is requested.

Users of this framework create a dynamic view by registering a DynamicView declaration. That declaration includes a name that forms the basis for the metadata attributes that are used to identify and order the desired view sub-elements into the view’s composition. In addition, the declaration includes any data to be passed into the constructor of the dynamic view and the id that should be used to persist the user’s customization of the view.

Additionally, this framework allows sub-elements themselves to also be dynamically composed of further sub-elements.

For example, a dynamic view could be composed of two sub-elements:

  1. The first is a dynamically composed HFlow, which represents a toolbar that can be extended through contributions of toolbar buttons.

  2. The second could be a dynamic tabset where each page is also a contribution.

Programmers include dynamic sub-elements within their dynamic views by contributing a DynamicViewSubElement into that view. When the framework comes across this contribution while building the view, it replaces that DynamicViewSubElement with a fully initialized Traits ViewSubElement composed in a manner similar to how the elements of the View itself were composed.

Each contribution to a dynamic view or sub-element must be an instance of a Traits ViewSubElement and must have associated metadata like the following for each dynamic view or sub-element it will display in:

_<dynamic name>_orderA float value.

The framework uses only ViewSubElements with this metadata instantiated when building the dynamic view or sub-element with the specified name. The elements are sorted by ascending order of this value using the standard list sort function.

_<dynamic name>_priorityA float value.

The framework resolves any overloading of an order value by picking the first element encountered that has the highest priority value. The other elements with the same view order are not displayed at all.

In addition, dynamic view contributions can also provide a ‘handler’, which behaves like a normal Traits Handler. That is, it can contain methods that are called when model values change and can access the Traits UIInfo object representing the actual UI instances. To provide a handler, append the following metadata to your view sub-element:

_<dynamic_name>_handlerA HasTraits instance.

The framework will connect listeners to call the handler methods as part of the handler for the dynamic view.

class traitsui.extras.has_dynamic_views.DynamicView[source]

Bases: HasTraits

Declares a dynamic view.

id = Str()

The ID of the view. This is the ID that the view’s preferences will be saved under.

keywords = Dict()

Keyword arguments passed in during construction of the actual view instance.

name = Str()

The name of the view. This is the name that should be requested when calling edit_traits() or configure_traits().

use_as_default = Bool(False)

Indicates whether this view should be the default traits view for objects it is contributed to.

class traitsui.extras.has_dynamic_views.DynamicViewSubElement[source]

Bases: ViewSubElement

Declares a dynamic sub-element of a dynamic view.

keywords = Dict()

Keyword arguments passed in during construction of the actual ViewSubElement instance.

klass = Any()

The class of the actual ViewSubElement we are dynamically creating.

name = Str()

The name of this dynamic sub-element. This controls the metadata names identifying the sub-elements that compose this element.

class traitsui.extras.has_dynamic_views.HasDynamicViews[source]

Bases: HasTraits

Provides of a framework that builds Traits UI Views at run time, when the view is requested, rather than at the time a class is written.

declare_dynamic_view(declaration)[source]

A convenience method to add a new dynamic view declaration to this instance.

trait_view(name=None, view_element=None)[source]

Gets or sets a ViewElement associated with an object’s class.

Extended here to build dynamic views and sub-elements.