Traits User Interface Class David C. Morrill Enthought, Inc.

What We’re Going To Cover… The DockWindow component Using DockWindows in a Traits UI DockWindow usage

The DockWindow Component A DockWindow is a enthought.pyface component that organizes and manages sets of controls into: –Notebooks –Splitter groups –Dockable groups It gives users the ability to organize a user interface in a way that makes sense to, or is comfortable for, them.

The DockWindow Component The DockWindow component is in enthought.pyface.dock This package defines the following classes: –DockWindow: The window –DockSizer: The layout manager –DockSection: A splitter group –DockRegion: A notebook –DockControl: An “atomic” control (might be a panel)

The DockWindow Component DockWindow DockSizer DockSection DockRegion DockControl DockSection DockRegion DockControl wx.Control

The DockWindow Component DockWindow wx.Controlwx.Panelwx.Controlwx.Panelwx.Control parent

The DockWindow Component The developer defines the initial DockSection/DockRegion/DockControl object hierarchy. After that the DockSizer manages the interface and reorganizes the object hierarchy as the user interacts with the DockWindow. Custom layouts can be saved and restored using the GetStructure/SetStructure methods on the DockSizer. –GetStructure returns a data structure specifically designed to be pickled.

The DockWindow Component SetStructure uses an intelligent algorithm that correctly deals with: –Developers adding new elements to a UI –Developers removing existing elements from a UI –Imbedding “foreign” objects within a UI

Using DockWindows in a Traits UI The good news is that as a Traits UI developer, creating and using DockWindows is completely transparent to you. DockWindows are automatically created whenever you use a Group with layout set to either ‘tabbed’ or ‘split’. As long as nested Groups use the tabbed/split styles, they will all be part of the same DockWindow. A break in the nesting chain results in multiple DockWindows being created. Each DockWindow is isolated from other DockWindows.

Using DockWindows in a Traits UI To make creating DockWindows easier, new Group subclasses have been defined: –Tabbed: Tabbed DockWindow notebook –HSplit: Horizontally split DockWindow –VSplit: Vertically split DockWindow –HGroup: Horizontally arranged non- DockWindow –VGroup: Vertically arranged non- DockWindow

Using DockWindows in a Traits UI There are four DockWindow styles: –Fixed: Elements cannot be docked –Horizontal: Horizontal drag bar –Vertical: Vertical drag bar –Tab: Notebook tab drag bar The DockWindow style is specified using the new dock trait, which is defined on the Item, Group and View classes. The dock trait is inherited, so setting it on a View means all items in the View will use the View’s dock style by default. The default dock style is fixed (i.e. the user cannot rearrange elements within the View).

Using DockWindows in a Traits UI The user’s layout preferences for a View can be automatically saved and restored using the standard Traits UI preference mechanism: –Define a non-empty View id (e.g. “enthought.foo.bar.baz”). It should be globally unique. –Define a non-empty id for the top-level Tabbed, HSplit or VSplit group. This id only has to be unique within the View. The inner groups do not have to have an id defined.

Using DockWindows in a Traits UI The case of Instance traits needs a little more explanation. To save the user’s layout preferences you must: –Make sure the Instance trait’s Item has a non-empty id. –Make sure the View referenced by the Instance trait has a non-empty id. –Make sure the top-level DockWindow enabled Group within the View has a non-empty id. Only the layout data for the most recently displayed Instance View is preserved.

Using DockWindows in a Traits UI The new image trait allows you to define an icon to display on a notebook page next to the element’s name (e.g. image = ImageResource( ‘folder’ ) ).

DockWindow usage These are user level notes on how to interact with a DockWindow enabled view. You can rearrange tabs within a notebook by dragging a tab until you see the docking insertion marker highlight the gap between the two pages you want to insert into. You can drag a tab out of a notebook by dragging its tab into another notebook, or onto the drag bar of another element.

DockWindow usage You can add a stand-alone element to a notebook by dragging its drag bar onto the notebook. You can add an element or tab to another tab or element by holding down the Ctrl key while dragging. Wait until you see the horizontal docking bar appear along the bottom edge of the tab or drag bar, then release. The item will be added to the target. You can then rearrange items within the target after the drop as usual.

DockWindow usage You can drag the splitter bars between elements to control how much of each element is visible. You can click the icons on the splitter bars to snap the splitter to either edge, or back to its last position before being snapped to an edge.

DockWindow usage You can move an entire notebook or splitter group by dragging a tab or drag bar within the group while holding down the Alt key. You can restore the original layout designed by the developer by clicking any DockWindow element while holding down the Ctrl and Shift keys. Performing the same action again will restore the previous layout (i.e. it’s a toggle).

DockWindow usage You can lock the current layout by clicking any DockWindow element while holding down the Alt and Shift keys. Locking the layout removes all drag bars, and does not allow tabs to be moved or rearranged. However, splitter bars still behave normally. You can unlock the layout by performing the same action again (i.e. it’s a toggle also).