traitsui.handler module

Defines the Handler class used to manage and control the editing process in a Traits-based user interface.

class traitsui.handler.Controller(model=None, **metadata)

Bases: Handler

Defines a handler class which provides a view and controller for a specified model.

This class is used when implementing a standard MVC-based design. The model trait contains most, if not all, of the data being viewed, and can be referenced in a Controller instance’s View definition using unadorned trait names. (e.g., Item('name')).

get_perform_handlers(info)

Return a list of objects which can handle actions.

By default this returns the Controller instance and the model.

Parameters:

info (UIInfo instance or None) – The UIInfo associated with the view, or None.

Returns:

handlers – A list of objects that may potentially have action methods on them.

Return type:

list

info = Instance(UIInfo)

The Info object associated with the controller

init_info(info)

Informs the handler what the UIInfo object for a View will be.

model = Instance(HasTraits)

The model this handler defines a view and controller for

trait_context()

Returns the default context to use for editing or configuring traits.

class traitsui.handler.Handler

Bases: HasPrivateTraits

Provides access to and control over the run-time workings of a Traits-based user interface.

apply(info)

Handles the Apply button being clicked.

can_drop(info, object)

Can the specified object be inserted into the view?

can_import(info, category)

close(info, is_ok)

Handles the user attempting to close a dialog-based user interface.

This method is called when the user attempts to close a window, by clicking an OK or Cancel button, or clicking a Close control on the window). It is called before the window is actually destroyed. Override this method to perform any checks before closing a window.

While Traits UI handles “OK” and “Cancel” events automatically, you can use the value of the is_ok parameter to implement additional behavior.

Parameters:

• info (UIInfo object) – The UIInfo object associated with the view

• is_ok (Boolean) – Indicates whether the user confirmed the changes (such as by clicking OK.)

Returns:

allow_close – A Boolean, indicating whether the window should be allowed to close.

Return type:

bool

closed(info, is_ok)

Handles a dialog-based user interface being closed by the user.

This method is called after the window is destroyed. Override this method to perform any clean-up tasks needed by the application.

Parameters:

• info (UIInfo object) – The UIInfo object associated with the view

• is_ok (Boolean) – Indicates whether the user confirmed the changes (such as by clicking OK.)

configure_traits(filename=None, view=None, kind=None, edit=True, context=None, handler=None, id='', scrollable=None, **args)

Configures the object’s traits.

dock_control_for(info, parent, object)

Returns the DockControl object for a specified object.

dock_window_empty(dock_window)

Handles a DockWindow becoming empty.

edit_traits(view=None, parent=None, kind=None, context=None, handler=None, id='', scrollable=None, **args)

Edits the object’s traits.

get_perform_handlers(info)

Return a list of objects which can handle actions.

This method may be overridden by sub-classes to return a more relevant set of objects.

Parameters:

info (UIInfo instance or None) – The UIInfo associated with the view, or None.

Returns:

handlers – A list of objects that may potentially have action methods on them.

Return type:

list

init(info: UIInfo) → bool

Initializes the controls of a user interface.

This method is called after all user interface elements have been created, but before the user interface is displayed. Override this method to customize the user interface before it is displayed.

Parameters:

info (UIInfo object) – The UIInfo object associated with the view

Returns:

initialized – A Boolean, indicating whether the user interface was successfully initialized. A True value indicates that the UI can be displayed; a False value indicates that the display operation should be cancelled. The default implementation returns True without taking any other action.

Return type:

bool

init_info(info)

Informs the handler what the UIInfo object for a View will be.

This method is called before the UI for the View has been constructed. It is provided so that the handler can save the reference to the UIInfo object in case it exposes viewable traits whose values are properties that depend upon items in the context being edited.

open_view_for(control, use_mouse=True)

Creates a new view of a specified control.

perform(info, action, event)

Perform computation for an action.

The default method looks for a method matching action.action and calls it (sniffing the signature to determine how to call it for historical reasons). If this is not found, then it calls the perform() method of the action.

Parameters:

• info (UIInfo instance) – The UIInfo assicated with the view, if available.

• action (Action instance) – The Action that the user invoked.

• event (ActionEvent instance) – The ActionEvent associated with the user action.

Notes

If overriding in a subclass, the method needs to ensure that any standard menu action items that are needed (eg. “Close”, “Undo”, “Redo”, “Help”, etc.) get dispatched correctly.

position(info)

Positions a dialog-based user interface on the display.

This method is called after the user interface is initialized (by calling init()), but before the user interface is displayed. Override this method to position the window on the display device. The default implementation calls the position() method of the current toolkit.

Usually, you do not need to override this method, because you can control the window’s placement using the x and y attributes of the View object.

Parameters:

info (UIInfo object) – The UIInfo object associated with the window

revert(info)

Handles the Revert button being clicked.

setattr(info, object, name, value)

Handles the user setting a specified object trait’s value.

This method is called when an editor attempts to set a new value for a specified object trait attribute. Use this method to control what happens when a trait editor tries to set an attribute value. For example, you can use this method to record a history of changes, in order to implement an “undo” mechanism. No result is returned. The default implementation simply calls the built-in setattr() function. If you override this method, make sure that it actually sets the attribute, either by calling the parent method or by setting the attribute directly

Parameters:

• info (UIInfo instance) – The UIInfo for the current UI

• object (object) – The object whose attribute is being set

• name (string) – The name of the attribute being set

• value – The value to which the attribute is being set

show_help(info, control=None)

Shows the help associated with the view.

This method is called when the user clicks a Help button in a Traits user interface. The method calls the global help handler, which might be the default help handler, or might be a custom help handler. See traitsui.help for details about the setting the global help handler.

Parameters:

• info (UIInfo object) – The UIInfo object associated with the view

• control (UI control) – The control that invokes the help dialog box

trait_view_for(info, view, object, object_name, trait_name)

Gets a specified View object.

class traitsui.handler.ModelView(model=None, **metadata)

Bases: Controller

Defines a handler class which provides a view and controller for a specified model.

This class is useful when creating a variant of the standard MVC-based design. A subclass of ModelView reformulates a number of traits on its model object as properties on the ModelView subclass itself, usually in order to convert them into a more user-friendly format. In this design, the ModelView subclass supplies not only the view and the controller, but also, in effect, the model (as a set of properties wrapped around the original model). Because of this, the ModelView context dictionary specifies the ModelView instance itself as the special object value, and assigns the original model object as the model value. Thus, the traits of the ModelView object can be referenced in its View definition using unadorned trait names.

trait_context()

Returns the default context to use for editing or configuring traits.

class traitsui.handler.ViewHandler

Bases: Handler

traitsui.handler.close_dock_control(dock_control)

Closes a DockControl (if allowed by the associated Traits UI Handler).

traitsui.handler.default_handler(handler=None)

Returns the global default handler.

If handler is an instance of Handler, this function sets it as the global default handler.