`dip.ui`¶

The dip.ui module implements a toolkit independent API for defining a user interface declaratively.

`Action`¶

class dip.ui.Action¶

Base class: ValueTypeFactory

The Action class encapsulates an instance of an implementation of IAction. This can be used either to define an attribute type in a model or to create a factory that then creates actions bound to an attribute of a model.

__init__(bind_to='', id=None, checkable=None, checked=None, enabled=True, shortcut=None, status_tip=None, text=None, tool_tip=None, visible=True, whats_this=None, within='', **metadata)¶

Initialise the object.

Parameters:

bind_to – is the name of the attribute that actions are bound to. This may be an attribute path. This should not be specified when an attribute type is being defined.
id – is the action’s identifier. It is ignored if the action is being bound to an attribute.
checkable – is set if the action is checkable.
checked – is set if the action is checked.
enabled – is set if the action is enabled.
shortcut – is the shortcut.
status_tip – is the status tip.
text – is the text of the action. If this is not specified it will default to the name of the attribute if an attribute type is being defined, or the name of the attribute that actions are bound to. In both cases any underscores will be replaced by spaces and the first letter of each word capitalized.
tool_tip – is the tool tip.
visible – is set if the action is visible.
whats_this – is the “What’s This?” help.
within – is the identifier of an optional collection of actions that this action will be placed within.
**metadata – is additional meta-data stored with the type.

__call__(model)¶

Create the action. This behaviour is similar to a view factory.

Parameters:	model – is the model.
Returns:	the action.

bind(model, value, rebind=False)¶

This is called when a model attribute is being bound or rebound.

Parameters:	model – is the model. value – is the attribute’s new value. rebind – is set if the attribute already has a value.

clone()¶

Create a clone of this instance.

Returns:	the cloned instance.

copy()¶

Create a copy of this instance.

Returns:	the copied instance.

create()¶

Create the action.

Returns:	the action.

classmethod different(value1, value2)¶

Reimplemented to compare two instances to see if they are different.

Parameters:	value1 – is the first value. value2 – is the second value.
Returns:	`True` if the values are different.

get_default_value()¶: Get the type’s default value. This will always be a new implementation of IAction.

triggered(triggered_func)¶: This is used to decorate a method that will be invoked when the action is triggered.

validate(value)¶

Validate an instance according to the constraints. An exception is raised if the instance is invalid.

Parameters:	value – the instance to validate.
Returns:	the validated instance.

`ActionCollection`¶

class dip.ui.ActionCollection¶

Base class: ValueTypeFactory

The ActionCollection class encapsulates an instance of an implementation of IActionCollection. This can be used either to define an attribute type in a model or to create a factory that then creates action collections.

__init__(*action_ids, id=None, text='', within='', **metadata)¶

Initialise the object.

Parameters:

*action_ids – is the list of the identifiers of actions contained in the collection.
id – is the collection’s identifier. If this is not specified it will default to the name of the attribute if an attribute type is being defined.
text – is the optional text of the collection. If this is specified then the toolkit may place the actions in a hierarchy (e.g. a sub-menu).
within – is the identifier of an optional action collection that this collection will be placed within.
**metadata – is additional meta-data stored with the type.

__call__(model)¶

Create the action collection. This behaviour is similar to a view factory.

Parameters:	model – is the model.
Returns:	the action collection.

copy()¶

Create a copy of this instance.

Returns:	the copied instance.

classmethod different(value1, value2)¶

Reimplemented to compare two instances to see if they are different.

Parameters:	value1 – is the first value. value2 – is the second value.
Returns:	`True` if the values are different.

get_default_value()¶: Get the type’s default value. This will always be a new implementation of IActionCollection.

validate(value)¶

Validate an instance according to the constraints. An exception is raised if the instance is invalid.

Parameters:	value – the instance to validate.
Returns:	the validated instance.

`Application`¶

class dip.ui.Application¶

The Application class creates a singleton application that implements, or can be adapted to the IApplication interface.

static __new__(argv=None, **properties)¶

Create the application.

Parameters:	argv – is the sequence of command line arguments. By default `sys.argv` is used. **properties – are the keyword arguments used as toolkit specific property names and values that are used to configure the application.
Returns:	the application.

static information(window_title, text, parent=None)¶

Display a informational message to the user.

Parameters:	window_title – is the window title, typically used as the title of a dialog. text – is the text of the message. parent – is the optional parent view.

static question(window_title, text, parent=None, detail='', buttons=('no', 'yes'))¶

Ask the user a question.

Parameters:

window_title – is the window title, typically used as the title of a dialog.
text – is the text of the question.
parent – is the optional parent view.
detail – is the optional additional detail.
buttons – is the sequence of buttons to display. Possible buttons are ‘yes’, ‘no’, ‘cancel’, ‘save’ and ‘discard’. The first in the sequence is used as the default.

Returns:

The button that was pressed.

static warning(window_title, text, parent=None, detail='')¶

Display a warning message to the user.

Parameters:	window_title – is the window title, typically used as the title of a dialog. text – is the text of the warning. parent – is the optional parent view. detail – is the optional additional detail.

`Bindings`¶

class dip.ui.Bindings¶

Base class: Model

The Bindings class represents set of bindings between widgets of a user interface and attributes of a model.

controller_factory = Callable(): The controller factory. This must return an object that implements or can be adapted to the IController interface.

__init__(**bindings)¶

Initialise the bindings.

Parameters:	**bindings – the bindings specified as keyword arguments. The argument name is the object name of the widget that the attribute will be bound to. The argument value is the binding. If the argument value is a string then an `EditorFactory` instance will be automatically created for it.

bind(view, model, controller=None)¶

Bind a view to a model and optional controller.

Parameters:	view – is the view. model – is the model which is either a `Model` instance or a Python mapping object. controller – is the optional controller. If this is `None` then `controller_factory` will be called to create one.

`BoxLayoutFactory`¶

class dip.ui.BoxLayoutFactory¶

Base class: ContainerFactory

The BoxLayoutFactory class is the base class for all factories that create views that can contain Stretch.

create_additional_content(content)¶

Create additional content to be added to the list of sub-views.

Parameters:	content – the content from which additional content can be created.
Returns:	the additional content.

`CheckBox`¶

class dip.ui.CheckBox¶

Base class: EditorFactory

The CheckBox class implements a check box editor factory for bool attributes.

toolkit_factory = 'check_box': The name of the toolkit factory method.

`CollectionValidator`¶

class dip.ui.CollectionValidator¶

Base class: Model

The CollectionValidator class implements an editor validator for collections.

configure(editor)¶

Configure an editor to use this validator.

Parameters:	editor – is the editor.

validate(controller, editor, value)¶

Validate an editor’s value.

Parameters:	controller – is the controller. editor – is the editor. value – is the value.
Returns:	a string describing why the value is invalid. An empty string is returned if the value is valid.

`ComboBox`¶

class dip.ui.ComboBox¶

Base class: OptionSelectorFactory

The ComboBox class implements a factory for selecting an option using a combo box.

toolkit_factory = 'combo_box': The name of the toolkit factory method.

`ContainerFactory`¶

class dip.ui.ContainerFactory¶

Base class: ViewFactory

The ContainerFactory class is the base factory class for all views that can contain sub-views. A sub-class determines the layout of the sub-views.

actions = List(Callable()): The list of action factories. Each is called with the model as arguments and must return an object that implements or can be adapted to either the IAction or ActionCollection interfaces.

auto_populate = Bool(False): This is True if the contents should be automatically populated from a model’s attribute types (if no contents where explicitly set).

contents = List(): The contents of the view.

__init__(*contents, **properties)¶

Initialise the factory.

Parameters:	contents – is the list of the view’s contents. An individual item can either be a `ViewFactory` instance or a string. Strings are are assumed to be the names of attributes within a model. Such names may include one or more periods to specify an attribute path. *properties – are keyword arguments used as property names and values that are applied to the view.

configure_subviews(view, subviews)¶

Configure a sequence of sub-views before adding them to the containing view.

Parameters:	view – is the containing view. subviews – is the sequence of sub-views.

create(model, controller, parent)¶

Create a view instance.

Parameters:	model – is the model. controller – is the controller. parent – is the optional parent view.
Returns:	the view.

create_additional_content(content)¶

Create additional content to be added to the list of sub-views. This default implementation will always raise an exception.

Parameters:	content – the content from which additional content can be created.
Returns:	the additional content.

create_subviews(model, controller, view)¶

Create the sub-views for a containing view.

Parameters:	model – is the model. controller – is the controller. view – is the containing view.
Returns:	the sub-views.

finalize(view)¶

Reimplemented to finalize the sub-views.

Parameters:	view – is the view created by this factory.

`Controller`¶

class dip.ui.Controller¶

Base class: Model

The Controller class is the default implementation of a controller.

__getattr__(name)¶

Reimplemented to support convenient access to actions and editors using a name derived from an identifier.

Parameters:	name – the name of the attribute. If this has a suffix of `_action`, `_editor` or `_view` then the rest of the name is interpreted as the identifier of an action or editor (which is normally the name of the model attribute that the action or editor is bound to) or view.
Returns:	the attribute. An AttributeError will be raised if there was no such attribute, action or editor.

add_action(action)¶

Add an action to the controller.

Parameters:	action – is the action.

add_editor(editor)¶

Add an editor to the controller.

Parameters:	editor – is the editor.

editors_to_validate()¶

Return the sequence of editors to validate.

Returns:	the sequence of editors.

find_action(id, tail=False)¶

Find the action with a particular identifier.

Parameters:	id – is the identifier of the action. tail – if this is set then only the last part of a dotted action identifier is compared.
Returns:	the action or `None` if there was no such action.

find_editor(id, tail=False)¶

Find the editor with a particular identifier.

Parameters:	id – is the identifier of the editor. tail – if this is set then only the last part of a dotted editor identifier is compared.
Returns:	the editor or `None` if there was no such editor.

is_valid(editor=None)¶

Return the validity of an editor’s (or all editors) current value.

Parameters:	editor – is the editor. If this is `None` then the validity of all editors is returned.
Returns:	`True` if the editor (or all editors) is valid.

update_model()¶: Update the all the attributes of a model that have a corresponding editor.

update_view()¶: This is called after the view has been validated giving the controller an opportunity to update the state of the view. This implementation does nothing.

validate()¶: Validate the view and update the explanation as to why it is (or isn’t) invalid.

validate_view()¶

This is called after the view has been updated and only if all the view’s editors contain valid values giving the controller an opportunity to carry out cross-editor validation.

Returns:	a string which will be empty if the view is valid, otherwise it will explain why the view is invalid. This implementation always returns an empty string.

`Designer`¶

class dip.ui.Designer¶

Base class: ViewFactory

The Designer class allows any user interface created with Qt Designer (in the case of the default toolkit) to be used in a view.

bindings = Instance(Bindings): The bindings that connect the GUI to the model.

ui_file_name = Str(): The name of toolkit specific design file.

__init__(ui_file_name, **properties)¶

Initialise the item.

Parameters:	ui_file_name – is the name of the Qt Designer .ui file. **properties – are keyword arguments used as property names and values that are applied to the widget.

create(model, controller, parent)¶

Create a view instance.

Parameters:	model – is the model. controller – is the controller. parent – is the optional parent view.
Returns:	the view that is the root of the user interface defined in the .ui file.

`Dialog`¶

class dip.ui.Dialog¶

Base class: SingleSubviewContainerFactory

The Dialog class implements a dialog factory, i.e. it creates views that implement the IDialog interface.

auto_form = 'always': The contents should always be automatically wrapped in a Form.

id = 'dip.dialog': The identifier of each widget created by the factory.

toolkit_factory = 'dialog': The name of the toolkit factory method.

`DialogController`¶

class dip.ui.DialogController¶

Base class: Controller

The DialogController class is a controller for handling dialogs.

auto_update_model = False: This determines if the controller should automatically update the model when the user changes the value of an editor.

update_view()¶: Reimplemented to disable the accept button if the view is invalid.

`Dock`¶

class dip.ui.Dock¶

Base class: SingleSubviewContainerFactory

The Dock class implements a dock of a main window.

toolkit_factory = 'dock': The name of the toolkit factory method.

`EditorFactory`¶

class dip.ui.EditorFactory¶

Base class: ViewFactory

The EditorFactory class is a factory for views that implement the IEditor interface. The label, validator, status_tip, tool_tip and whats_this attributes will default to any values defined in the type’s meta-data.

bind_to = Str(): The name of the attribute that the editor is bound to. This may be an attribute path.

__init__(bind_to='', **properties)¶

Initialise the factory.

Parameters:	bind_to – the name of the attribute that the editor is bound to. It should only be an empty string if the factory is being used to create a delegate. **properties – are keyword arguments used as property names and values that are applied to the editor.

bind_editor(editor, model, name, controller)¶

Bind an editor to a model attribute and add it to a controller.

Parameters:	editor – is the editor. model – is the model. name – is the name of the attribute. It may be an attribute path. controller – is the controller.

configure(view)¶

Reimplemented to configure the IEditor specific attributes.

Parameters:	view – is the view to configure.

configure_with_attribute_type(view, attribute_type)¶

Configure the view possibly using values from the bound attribute’s type.

Parameters:	view – is the view to configure. attribute_type – is the attribute’s type.

create(model, controller, parent)¶

Create a view instance.

Parameters:	model – is the model. controller – is the controller. parent – is the optional parent view.
Returns:	the view.

set_default_validator(view)¶

Sets a view’s default validator. This implementation does nothing.

Parameters:	view – is the view.

`FilesystemLocationEditor`¶

class dip.ui.FilesystemLocationEditor¶

Base class: EditorFactory

The FilesystemLocationEditor class implements a filesystem location editor factory. Note that StorageLocationEditor should normally be used instead.

required = Bool(False): This is set if a value is required.

toolkit_factory = 'filesystem_location_editor': The name of the toolkit factory method.

set_default_validator(view)¶

Sets a view’s default validator.

Parameters:	view – is the view.

`FilesystemLocationValidator`¶

class dip.ui.FilesystemLocationValidator¶

Base class: Model

The FilesystemLocationValidator class implements an editor validator for filesystem locations.

mode = Enum('open_file', 'save_file', 'directory'): The mode of the editor. ‘open_file’ means a single, existing file will be obtained. ‘save_file’ means that a single file that may or may not exist will be obtained. ‘directory’ means a single, existing directory will be obtained.

required = Bool(False): This is set if a value is required.

configure(editor)¶

Configure an editor to use this validator.

Parameters:	editor – is the editor.

validate(controller, editor, value)¶

Validate an editor’s value.

Parameters:	controller – is the controller. editor – is the editor. value – is the value.
Returns:	a string describing why the value is invalid. An empty string is returned if the value is valid.

`FloatSpinBox`¶

class dip.ui.FloatSpinBox¶

Base class: EditorFactory

The FloatSpinBox class implements a spin box editor factory for float attributes.

toolkit_factory = 'float_spin_box': The name of the toolkit factory method.

configure_with_attribute_type(view, attribute_type)¶

Configure the view possibly using values from the bound attribute’s type.

Parameters:	view – is the view to configure. attribute_type – is the attribute’s type.

`Form`¶

class dip.ui.Form¶

Base class: ContainerFactory

The Form class arranges its contents as a form.

auto_populate = True: If there are no explicit contents then automatically populate the form with the model’s attribute types.

toolkit_factory = 'form': The name of the toolkit factory method.

configure_subviews(view, subviews)¶

Configure a sequence of sub-views before adding them to the containing view.

Parameters:	view – is the containing view. subviews – is the sequence of sub-views.

`Grid`¶

class dip.ui.Grid¶

Base class: ContainerFactory

The Grid class arranges its contents in a grid.

toolkit_factory = 'grid': The name of the toolkit factory method.

`GroupBox`¶

class dip.ui.GroupBox¶

Base class: SingleSubviewContainerFactory

The GroupBox class arranges its contents in a group box.

toolkit_factory = 'group_box': The name of the toolkit factory method.

`HBox`¶

class dip.ui.HBox¶

Base class: BoxLayoutFactory

The HBox class arranges its contents horizontally.

toolkit_factory = 'h_box': The name of the toolkit factory method.

`IAction`¶

class dip.ui.IAction¶

Base class: IObject

The IAction interface defines the API to be implemented by an action.

checkable = Bool(): This is set if the action is checkable.

checked = Bool(False): This is set if the action is checked.

enabled = Bool(): This is set if the action is enabled.

plain_text = Str(): The plain text of the action. This is the same as the text but with any formatting hints (e.g. ‘&’ or ‘...’) removed. It is typically used in action specific dialog titles.

shortcut = Str(): The shortcut.

status_tip = Str(): The status tip.

text = Str(): The text of the action.

tool_tip = Str(): The tool tip.

trigger = Trigger(): This is set when the action is triggered.

visible = Bool(): This is set if the widget is visible.

whats_this = Str(): The “What’s This?” help.

when_triggered = Callable(): This is called when the action is triggered. It is passed the action as its only argument.

within = Str(): The identifier of an optional collection of actions that this action will be placed within.

`IActionBinding`¶

class dip.ui.IActionBinding¶

Base class: Interface

The IActionBinding interface defines the additional data to be bound to an action.

attribute_is_type = Bool(): This is set if attribute in the model is a type rather than a callable.

attribute_name = Str(): The name of the attribute in the model. This is not an attribute path.

model = Instance(Model): The model containing the attribute.

`IActionCollection`¶

class dip.ui.IActionCollection¶

Base class: IObject

The IActionCollection interface defines the API to be implemented by an action collection.

actions = List(Instance(IAction, Str())): The actions contained in the collection.

text = Str(): The text of the action collection.

within = Str(): The identifier of an optional action collection that this action collection will be placed within. If it is not specified then the toolkit will place it automatically.

`IApplication`¶

class dip.ui.IApplication¶

Base class: Interface

The IApplication interface defines the API to be implemented by an application created by Application.

active_view = Instance(IView): The active view (i.e. the one with the focus).

execute()¶

Execute the application, i.e. enter its event loop. It will return when the event loop terminates.

Returns:	An integer exit code.

quit()¶: Quit the application, i.e. force its event loop to terminate.

`IBox`¶

class dip.ui.IBox¶

Base class: IContainer

The IBox interface defines the API to be implemented (typically using adaptation) by a view that can contain a mixture of sub-views and Stretch instances.

views = Tuple(Instance(IView, Stretch)): The contained sub-views.

`ICheckBox`¶

class dip.ui.ICheckBox¶

Base class: IEditor

The ICheckBox interface defines the API to be implemented by a check box.

`ICollectionEditor`¶

class dip.ui.ICollectionEditor¶

Base class: IEditor

The ICollectionEditor interface defines the API to be implemented (typically using adaptation) by an editor that handles a collection type (e.g. a list).

retrieve_invalid_reason()¶

Retrieve the invalid reason for an item in the collection.

Returns:	is the invalid reason. It will be an empty string if all items are valid.

save_invalid_reason(invalid_reason)¶

Save the invalid reason for the current item in the collection.

Parameters:	invalid_reason – is the invalid reason. It will be an empty string if the item is valid.

`IComboBox`¶

class dip.ui.IComboBox¶

Base class: IOptionSelector

The IComboBox interface defines the API to be implemented by a combo box.

`IContainer`¶

class dip.ui.IContainer¶

Base class: IView

The IContainer interface defines the API to be implemented (typically using adaptation) by a view that can contain a number of sub-views.

actions = List(Instance(IAction, IActionCollection)): The list of actions.

views = Tuple(IView): The contained sub-views.

`IController`¶

class dip.ui.IController¶

Base class: Interface

The IController interface defines the API to be implemented by a view’s controller.

actions = List(IAction): The list of actions.

auto_update_model = Bool(True): This determines if the controller should automatically update the model when the user changes the value of an editor.

editors = List(IEditor): The list of editors being controlled.

invalid_reason = Str(): This explains why the view is invalid. It will be an empty string if the view is valid.

message_areas = List(IMessageArea): The message areas for giving feedback to the user.

model = Instance(Model): The model.

view = Instance(IView): The view.

__getattr__(name)¶

Reimplemented to support convenient access to actions and editors using a name derived from an identifier.

Parameters:	name – the name of the attribute. If this has a suffix of `_action` or `_editor` then the rest of the name is interpreted as the identifier of an action or editor (which is normally the name of the model attribute that the action or editor is bound to).
Returns:	the attribute. An AttributeError will be raised if there was no such attribute, action or editor.

add_action(action)¶

Add an action to the controller.

Parameters:	action – is the action.

add_editor(editor)¶

Add an editor to the controller.

Parameters:	editor – is the editor.

find_action(id)¶

Find the action with a particular identifier.

Parameters:	id – is the identifier of the action.
Returns:	the action or `None` if there was no such action.

find_editor(id)¶

Find the editor with a particular identifier.

Parameters:	id – is the identifier of the editor.
Returns:	the editor or `None` if there was no such editor.

is_valid(editor=None)¶

Return the validity of an editor’s (or all editors) current value.

Parameters:	editor – is the editor. If this is `None` then the validity of all editors is returned.
Returns:	`True` if the editor (or all editors) is valid.

update_model()¶: Update the all the attributes of a model that have a corresponding editor.

update_view()¶: This is called after the view has been validated giving the controller an opportunity to update the state of the view.

validate()¶: Validate the view and update the explanation as to why it is (or isn’t) invalid.

validate_view()¶

This is called after the view has been updated and only if all the view’s editors contain valid values giving the controller an opportunity to carry out cross-editor validation.

Returns:	a string which will be empty if the view is valid, otherwise it will explain why the view is invalid.

`IDialog`¶

class dip.ui.IDialog¶

Base class: ISingleViewContainer

The IDialog interface defines the API to be implemented by a dialog.

acceptable = Bool(True): This is set, typically by a controller, when the contents of the dialog are acceptable.

accepted = Trigger(): This is pulled when the user accepts the dialog.

buttons = Tuple(DialogButton, default=('ok', 'cancel')): The dialog buttons.

execute()¶

Execute the dialog as a modal dialog.

Returns:	`True` if the user accepted the dialog.

`IDialogController`¶

class dip.ui.IDialogController¶

Base class: IController

The IDialogController interface defines the API to be implemented by a dialog’s controller.

view = Instance(IDialog): The view.

`IDisplay`¶

class dip.ui.IDisplay¶

Base class: Interface

The IDisplay interface defines the metadata that an object may provide so that it can be referred to in a GUI and be recognisable by the user.

name = Str(): The name to be displayed to the user. This should uniquely identify the object to the user.

short_name = Str(): The optional short name.

`IDock`¶

class dip.ui.IDock¶

Base class: ISingleViewContainer

The IDock interface defines the API to be implemented by a dock.

action = Instance(IAction): The action that will toggle the dock’s visibility.

area = Enum('left', 'right', 'top', 'bottom'): The dock area that the dock is initially placed in.

within = Str(): The identifier of an optional collection of actions that the action used to toggle the dock visibility will be placed within.

`IEditor`¶

class dip.ui.IEditor¶

Base class: IView

The IEditor interface defines the API to be implemented (typically using adaptation) by an editor.

label = Str(): A short, user friendly label for the attribute. It is typically used as a field name or the text of a push button. If not given then any corresponding value of the type’s meta-data is used instead. If that hasn’t been defined then a label based on the name of the attribute in its containing model is used.

label_policy = Enum('default', 'optional', 'embedded'): The policy a view should follow when handling the editor’s label. ‘default’ means that the editor doesn’t embed the label and the view is free to use it in any way. ‘optional’ means the editor embeds the label but the view can ask for it to be removed. ‘embedded’ means the editor embeds the label and the view cannot do anything with it.

read_only = Bool(False): This is set if the editor is read-only.

validator = Instance(IValidator): The editor’s validator.

value = Any(): The value of the editor.

remove_label()¶: Remove an editor’s label. This will only be called if the label policy is ‘optional’.

`IEditorBinding`¶

class dip.ui.IEditorBinding¶

Base class: IViewBinding

The IEditorBinding interface defines additional data to be bound to an editor.

attribute_name = Str(): The name of the attribute in the model. This is not an attribute path.

attribute_type = Instance(TypeFactory): The type of the attribute in the model.

model = Instance(Model): The model containing the attribute.

`IFilesystemLocationEditor`¶

class dip.ui.IFilesystemLocationEditor¶

Base class: IEditor

The IFilesystemLocationEditor interface defines the API to be implemented by a filesystem location editor.

filter = Str(): The filter as defined by filter.

mode = Enum('open_file', 'save_file', 'directory'): The mode of the editor. ‘open_file’ means a single, existing file will be obtained. ‘save_file’ means that a single file that may or may not exist will be obtained. ‘directory’ means a single, existing directory will be obtained.

`IFloatSpinBox`¶

class dip.ui.IFloatSpinBox¶

Base class: IEditor

The IFloatSpinBox interface defines the API to be implemented by a spin box that handles floats.

maximum = Float(): The maximum value.

minimum = Float(): The minimum value.

`IForm`¶

class dip.ui.IForm¶

Base class: IContainer

The IForm interface defines the API to be implemented by a form layout.

labels = Tuple(Str(allow_none=True)): The list of labels for the widgets. If a label is None then the corresponding widget spans the row of the form.

`IGrid`¶

class dip.ui.IGrid¶

Base class: IContainer

The IGrid interface defines the API to be implemented by a grid layout.

nr_columns = Int(): The number of columns in the grid.

nr_rows = Int(): The number of rows in the grid.

`IGroupBox`¶

class dip.ui.IGroupBox¶

Base class: ISingleViewContainer

The IGroupBox interface defines the API to be implemented by a group box.

title = Str(): The title of the group box.

`IHBox`¶

class dip.ui.IHBox¶

Base class: IBox

The IHBox interface defines the API to be implemented by a horizontal box layout.

`ILabel`¶

class dip.ui.ILabel¶

Base class: IEditor

The ILabel interface defines the API to be implemented by a label.

`ILineEditor`¶

class dip.ui.ILineEditor¶

Base class: IEditor

The ILineEditor interface defines the API to be implemented by a line editor.

`IListEditor`¶

class dip.ui.IListEditor¶

Base class: ICollectionEditor

The IListEditor interface defines the API to be implemented by a list editor.

columns = List(ListColumn): The list of columns.

item_factory = Callable(): When called this will create the data for a new item in the list.

`IMainWindow`¶

class dip.ui.IMainWindow¶

Base class: ISingleViewContainer

The IMainWindow interface defines the API to be implemented by a main window.

docks = List(IDock): The list of docks.

menu_bar = Instance(IMenuBar): The menu bar.

`IMenu`¶

class dip.ui.IMenu¶

Base class: IContainer

The IMenu interface defines the API to be implemented by a menu.

title = Str(): The menu’s title.

visible = Bool(None, allow_none=True): The visibility of the menu. If this is None then the menu will be visible only when it has some content.

views = List(Instance(IAction, 'dip.ui.IMenu', Str())): The menu’s contents. An empty string means a separator.

add_action(action)¶

Try and add an action or action collection to the menu.

Parameters:	action – is the action.
Returns:	`True` if the action was added. `False` is returned if the menu couldn’t accommodate the action’s desired positioning.

`IMenuBar`¶

class dip.ui.IMenuBar¶

Base class: IContainer

The IMenuBar interface defines the API to be implemented by a menu bar.

add_action(action)¶

Try and add an action or action collection to the menu bar.

Parameters:	action – is the action.
Returns:	`True` if the action was added. `False` is returned if the menu bar couldn’t accommodate the action’s desired positioning.

`IMessageArea`¶

class dip.ui.IMessageArea¶

Base class: IView

The IMessageArea interface defines the API to be implemented by a view that is used as a message area.

text = Str(): The text displayed in the message area.

`IObject`¶

class dip.ui.IObject¶

Base class: Interface

The IObject interface is the base class for all interfaces that support the concept of an identifier and are able to be configured.

id = Str(): The object’s identifier.

configure(properties)¶

Configure the object using a mapping of toolkit specific property names and values.

Parameters:	properties – is the mapping of the properties.

`IOptionList`¶

class dip.ui.IOptionList¶

Base class: IOptionSelector

The IOptionList interface defines the API to be implemented by an editor that selects an option from a list.

`IOptionSelector`¶

class dip.ui.IOptionSelector¶

Base class: IEditor

The IOptionalSelector interface defines the API to be implemented by an editor that allows one of a number of options to be selected.

labels = Tuple(Str()): The optional option labels. These are used to visualise the corresponding options.

options = Tuple(): The options. If an option has no corresponding label then it will be adapted to the IDisplay interface and its name used (which will default to its string representation).

sorted = Bool(False): This is set of the options should be sorted.

`IPushButton`¶

class dip.ui.IPushButton¶

Base class: IEditor

The IPushButton interface defines the API to be implemented by a push button.

`IRadioButtons`¶

class dip.ui.IRadioButtons¶

Base class: IOptionSelector

The IRadioButtons interface defines the API to be implemented by a set of radio buttons.

vertical = Bool(True): The orientation of the radio buttons.

`ISingleViewContainer`¶

class dip.ui.ISingleViewContainer¶

Base class: IContainer

The ISingleViewContainer interface defines the API to be implemented (typically using adaptation) by a view that can contain a single sub-view.

view = Instance(IView): The contained sub-view.

`ISpinBox`¶

class dip.ui.ISpinBox¶

Base class: IEditor

The ISpinBox interface defines the API to be implemented by a spin box that handles ints.

maximum = Int(): The maximum value.

minimum = Int(): The minimum value.

`ISplitter`¶

class dip.ui.ISplitter¶

Base class: IContainer

The ISplitter interface defines the API to be implemented by a splitter.

`IStorageLocationEditor`¶

class dip.ui.IStorageLocationEditor¶

Base class: IEditor

The IStorageLocationEditor interface defines the API to be implemented by a storage location editor.

filter_hints = Str(): The filter hints as defined by filter.

format = Str(): The identifier of the format.

mode = Enum('open', 'save'): The mode of the editor. ‘open’ means an existing location will be obtained. ‘save’ means that a location that may or may not exist will be obtained.

`ITabBar`¶

class dip.ui.ITabBar¶

Base class: IContainer

The ITabBar interface defines the API to be implemented by a tab bar.

current_page = Instance(ITabPage): The current page.

tabs_visible = Bool(): This is set if the tabs are visible.

views = List(ITabPage): The tab bar’s pages. Note that, unlike most other containers, the sequence of views is mutable.

`ITabPage`¶

class dip.ui.ITabPage¶

Base class: ISingleViewContainer

The ITabPage interface defines the API to be implemented by a tab page.

title = Str(): The page’s title.

`ITableEditor`¶

class dip.ui.ITableEditor¶

Base class: ICollectionEditor

The ITableEditor interface defines the API to be implemented by a table editor.

columns = List(TableColumn): The list of columns.

row_factory = Callable(): When called this will create the data for a new row in the table.

`ITextEditor`¶

class dip.ui.ITextEditor¶

Base class: IEditor

The ITextEditor interface defines the API to be implemented by a text editor.

`IToolButton`¶

class dip.ui.IToolButton¶

Base class: IEditor

The IToolButton interface defines the API to be implemented by a tool button.

action = Instance(IAction): The tool button’s action.

`IVBox`¶

class dip.ui.IVBox¶

Base class: IBox

The IVBox interface defines the API to be implemented by a vertical box layout.

`IValidator`¶

class dip.ui.IValidator¶

Base class: Interface

The IValidator interface defines the API to be implemented by an editor’s validator.

configure(editor)¶

Configure an editor to use this validator.

Parameters:	editor – is the editor.

validate(controller, editor, value)¶

Validate an editor’s value.

Parameters:	controller – is the controller. editor – is the editor. value – is the value.
Returns:	a string describing why the value is invalid. An empty string is returned if the value is valid.

`IView`¶

class dip.ui.IView¶

Base class: IObject

The IView interface defines the API to be implemented (typically using adaptation) by a view.

close_request_handlers = List(Callable()): The list of callables that will be called when the view makes a request to be closed. Each is called with the view as the only argument and must return True for the close to proceed.

enabled = Bool(True): This is set if the view is enabled.

ready = Trigger(): This is triggered when the view is about to be made visible for the first time.

status_tip = Str(): The status tip.

tool_tip = Str(): The tool tip.

visible = Bool(True): This is set if the view is visible.

whats_this = Str(): The “What’s This?” help.

window_title = Str(): The window title. This may include the marker ‘[*]’ which will be replaced by some, platform specific, indication of the application’s overall dirty state.

all_views()¶

Create a generator that will return this view and any views contained in it.

Returns:	the generator.

set_focus()¶: Give the focus to the view.

`IViewBinding`¶

class dip.ui.IViewBinding¶

Base class: Interface

The IViewBinding interface defines the additional data to be bound to a view.

controller = Instance(IController): The controller.

factory = Instance(.ViewFactory): The factory that created the view.

`IViewStack`¶

class dip.ui.IViewStack¶

Base class: IContainer

The IViewStack interface defines the API to be implemented by a view stack.

current_view = Instance(IView): The current view.

views = List(IView): The contained sub-views. Note that, unlike most other containers, the sequence of views is mutable.

`IWizard`¶

class dip.ui.IWizard¶

Base class: IContainer

The IWizard interface defines the API to be implemented by a wizard.

current_page = Instance(IWizardPage): The current page.

finished = Trigger(): This is pulled when the user finishes the wizard.

views = Tuple(IWizardPage): The wizard’s pages.

execute()¶

Execute the wizard.

Returns:	`True` if the user accepted the wizard.

`IWizardController`¶

class dip.ui.IWizardController¶

Base class: IController

The IWizardController interface defines the API to be implemented by a wizard’s controller.

current_page = Instance(IWizardPage): The current page.

view = Instance(IWizard): The view.

`IWizardPage`¶

class dip.ui.IWizardPage¶

Base class: ISingleViewContainer

The IWizardPage interface defines the API to be implemented by a wizard page.

acceptable = Bool(True): This is set, typically by a controller, when the contents of the page are acceptable.

subtitle = Str(): The page’s sub-title.

title = Str(): The page’s title.

`Label`¶

class dip.ui.Label¶

Base class: EditorFactory

The Label class implements a label editor for a string attributes.

toolkit_factory = 'label': The name of the toolkit factory method.

`LineEditor`¶

class dip.ui.LineEditor¶

Base class: EditorFactory

The LineEditor class implements a line editor factory for string attributes.

required = Enum('no', 'yes', 'stripped', allow_none=True): This specifies whether or not a value is required. It is ignored if a validator is explicitly set. ‘no’ means that a value is not required (i.e. it can be an empty string). ‘yes’ means that a value is required. ‘stripped’ means that a value with no leading or trailing whitespace is required. If it is not explicitly set then any corresponding value in the type’s meta-data is used.

toolkit_factory = 'line_editor': The name of the toolkit factory method.

set_default_validator(view)¶

Sets a view’s default validator.

Parameters:	view – is the view.

`ListColumn`¶

class dip.ui.ListColumn¶

Base class: Model

The ListColumn class represents the meta-data of the column of a list.

bind_to = Str(): The name of attribute that the column is bound to. It will be empty if a row is a list rather than a model.

column_type = Instance(TypeFactory): The type of the column. It should not be specified if the type can be inferred from the attribute type. If it is not specified and no type can be inferred or the type is Any then Str is used.

editor_factory = Callable(): The factory for the view created to edit a value in the column. It will default to the list editor’s editor_factory.

label = Str(None, allow_none=True): The label of the column. It will default to a value derived from the name of the attribute that the column is bound to.

__init__(bind_to='')¶

Initialise the column.

Parameters:	bind_to – the name of the atribute that the column is bound to. It should not be specified if a row is a list rather than a model.

`ListEditor`¶

class dip.ui.ListEditor¶

Base class: EditorFactory

The ListEditor class implements a list editor factory for list attributes. If an item of the list is a simple type then there will be a a single column. If an item of the list is a model then there may be a column for each attribute of the model.

columns = List(Instance(ListColumn, str)): The list of columns. If a string is given then it is assumed to be the name of an attribute in the row model.

editor_factory = Callable(): The factory for the view created to edit a value in any column that does not specify its own editor factory. It will default to the factory provided by the toolkit for the column type.

item_factory = Callable(): When called this will create the data for a new item in the list. If a factory isn’t provided then a value based on the default value of the type of the list’s elements is used.

toolkit_factory = 'list_editor': The name of the toolkit factory method.

configure(view)¶

Reimplemented to configure the IListEditor specific attributes.

Parameters:	view – is the view to configure.

set_default_validator(view)¶

Sets a view’s default validator.

Parameters:	view – is the view.

`MainWindow`¶

class dip.ui.MainWindow¶

Base class: SingleSubviewContainerFactory

The MainWindow class implements a main window factory, i.e. it creates views that implement the IMainWindow interface.

docks = List(Dock): The list of dock factories.

id = 'dip.main_window': The identifier of each widget created by the factory.

menu_bar = Instance(MenuBar): The factory for the menu bar.

toolkit_factory = 'main_window': The name of the toolkit factory method.

create_subviews(model, controller, view)¶

Create the sub-views for a containing view.

Parameters:	model – is the model. controller – is the controller. view – is the containing view.
Returns:	the sub-views.

finalize(view)¶

Reimplemented to finalize any menu bar and docks.

Parameters:	view – is the view created by this factory.

`Menu`¶

class dip.ui.Menu¶

Base class: ContainerFactory

The Menu class implements a factory for menus that implement or can be adapted to IMenu.

contents = List(Instance(.Menu, Str())): The contents of the view.

toolkit_factory = 'menu': The name of the toolkit factory method.

visible = False: Menu’s are hidden by default. They will be visible when they contain something that is visible.

create_subviews(model, controller, view)¶

Create the sub-views for a containing view.

Parameters:	model – is the model. controller – is the controller. view – is the containing view.
Returns:	the sub-views.

`MenuBar`¶

class dip.ui.MenuBar¶

Base class: ContainerFactory

The MenuBar class implements a factory for menu bars that implement or can be adapted to IMenuBar.

contents = List(Menu): The contents of the view.

toolkit_factory = 'menu_bar': The name of the toolkit factory method.

`MessageArea`¶

class dip.ui.MessageArea¶

Base class: ViewFactory

The MessageArea class is a factory for a message area, which will be an implementation of, or something that be adapted to, IMessageArea to be used by a controller to display messages to the user.

toolkit_factory = 'message_area': The name of the toolkit factory method.

bind_view(view, controller)¶

Reimplemented to add the message area view to a controller.

Parameters:	view – is the view. controller – is the controller.

`OptionList`¶

class dip.ui.OptionList¶

Base class: OptionSelectorFactory

The OptionList class implements a factory for selecting an option using a list based widget.

toolkit_factory = 'option_list': The name of the toolkit factory method.

`OptionSelectorFactory`¶

class dip.ui.OptionSelectorFactory¶

Base class: EditorFactory

The OptionSelectorFactory class is a base class for editors that allow an option to be selected.

allow_none = Bool(None, allow_none=True): This is set if None is allowed as a valid value. If it is not explicitly set then any corresponding value in the type’s meta-data is used.

labels = List(Str()): The optional option labels. These are used to visualise the corresponding options.

options = Instance(Str(), List()): The options. If it is a string then it is the name of the attribute in the model where the options can be found. If an option has no corresponding label then it will be adapted to the IDisplay interface and its name used (which defaults to its string representation).

configure_with_attribute_type(view, attribute_type)¶

Configure the view possibly using values from the bound attribute’s type.

Parameters:	view – is the view to configure. attribute_type – is the attribute’s type.

set_default_validator(view)¶

Sets a view’s default validator.

Parameters:	view – is the view.

`OptionValidator`¶

class dip.ui.OptionValidator¶

Base class: Model

The OptionValidator class implements an editor validator for option values that cannot be None.

configure(editor)¶

Configure an editor to use this validator.

Parameters:	editor – is the editor.

validate(controller, editor, value)¶

Validate an editor’s value.

Parameters:	controller – is the controller. editor – is the editor. value – is the value.
Returns:	a string describing why the value is invalid. An empty string is returned if the value is valid.

`PushButton`¶

class dip.ui.PushButton¶

Base class: EditorFactory

The PushButton class implements a push button editor factory for trigger attributes.

toolkit_factory = 'push_button': The name of the toolkit factory method.

`RadioButtons`¶

class dip.ui.RadioButtons¶

Base class: OptionSelectorFactory

The RadioButtons class implements a factory for selecting an option using a set of radio buttons.

toolkit_factory = 'radio_buttons': The name of the toolkit factory method.

`SingleSubviewContainerFactory`¶

class dip.ui.SingleSubviewContainerFactory¶

Base class: ContainerFactory

The SingleSubviewContainerFactory class is a base class for container factories that can only contain a single sub-view.

auto_form = Enum('non-empty', 'always', 'never'): Determines if any sub-views should automatically be placed in a Form. If it is 'non-empty' then a form will be used if there is at least one sub-view. If it is 'always' then a form will always be used, even if there are no sub-views. If it is 'never' then a form will never be used. Irrespective of the value, if there is only one sub-view and it is a ContainerFactory instance then a form will never be used.

__init__(*contents, **properties)¶

Initialise the factory.

Parameters:	contents – is the list of the view’s contents. An individual item can either be a `ViewFactory` instance or a string. Strings are are assumed to be the names of attributes within a model. Such names may include one or more periods to specify an attribute path. *properties – are keyword arguments used as property names and values that are applied to the view.

`SpinBox`¶

class dip.ui.SpinBox¶

Base class: EditorFactory

The SpinBox class implements a spin box editor factory for integer attributes.

toolkit_factory = 'spin_box': The name of the toolkit factory method.

configure_with_attribute_type(view, attribute_type)¶

Configure the view possibly using values from the bound attribute’s type.

Parameters:	view – is the view to configure. attribute_type – is the attribute’s type.

`Splitter`¶

class dip.ui.Splitter¶

Base class: ContainerFactory

The Splitter class arranges its contents in a splitter.

toolkit_factory = 'splitter': The name of the toolkit factory method.

`StorageLocationEditor`¶

class dip.ui.StorageLocationEditor¶

Base class: EditorFactory

The StorageLocationEditor class implements a storage location editor factory.

required = Bool(False): This is set if a value is required.

toolkit_factory = 'storage_location_editor': The name of the toolkit factory method.

set_default_validator(view)¶

Sets a view’s default validator.

Parameters:	view – is the view.

`StorageLocationValidator`¶

class dip.ui.StorageLocationValidator¶

Base class: Model

The StorageLocationValidator class implements an editor validator for storage locations.

format = Str(): The identifier of the format.

mode = Enum('open', 'save'): The mode of the editor. ‘open’ means an existing location will be obtained. ‘save’ means that a location that may or may not exist will be obtained.

required = Bool(False): This is set if a value is required.

configure(editor)¶

Configure an editor to use this validator.

Parameters:	editor – is the editor.

validate(controller, editor, value)¶

Validate an editor’s value.

Parameters:	controller – is the controller. editor – is the editor. value – is the value.
Returns:	a string describing why the value is invalid. An empty string is returned if the value is valid.

`Stretch`¶

class dip.ui.Stretch¶: The Stretch class represents a stretchable space that can be added to a view.

`StringValidator`¶

class dip.ui.StringValidator¶

Base class: Model

The StringValidator class implements an editor validator for required string values.

stripped = Bool(False): This specifies that the value should not have leading or trailing spaces.

configure(editor)¶

Configure an editor to use this validator.

Parameters:	editor – is the editor.

validate(controller, editor, value)¶

Validate an editor’s value.

Parameters:	controller – is the controller. editor – is the editor. value – is the value.
Returns:	a string describing why the value is invalid. An empty string is returned if the value is valid.

`TabBar`¶

class dip.ui.TabBar¶

Base class: ContainerFactory

The TabBar class is a container for a number of TabPage sub-views.

contents = List(TabPage): The contents of the view.

toolkit_factory = 'tab_bar': The name of the toolkit factory method.

`TabPage`¶

class dip.ui.TabPage¶

Base class: SingleSubviewContainerFactory

The TabPage class implements a page of a tab bar.

toolkit_factory = 'tab_page': The name of the toolkit factory method.

`TableColumn`¶

class dip.ui.TableColumn¶

Base class: Model

The TableColumn class represents the meta-data of a column of a table.

column_type = Instance(TypeFactory): The type of the column. It should not be specified if the type can be inferred from the attribute type. If it is not specified and no type can be inferred or the type is Any then Str is used.

editor_factory = Callable(): The factory for the view created to edit a value in the column. It will default to the factory provided by the toolkit for the column type.

editable = Bool(True): This is set if the values in the column are editable.

label = Str(None, allow_none=True): The label of the column.

`TableEditor`¶

class dip.ui.TableEditor¶

Base class: EditorFactory

The TableEditor class implements a table editor factory for list attributes.

columns = List(Instance(TableColumn, str)): The list of columns. If a string is given then it is used as the label (i.e. heading) of the column.

row_factory = Callable(): When called this will create the data for a new row in the table.

toolkit_factory = 'table_editor': The name of the toolkit factory method.

configure(view)¶

Reimplemented to configure the ITableEditor specific attributes.

Parameters:	view – is the view to configure.

set_default_validator(view)¶

Sets a view’s default validator.

Parameters:	view – is the view.

`TextEditor`¶

class dip.ui.TextEditor¶

Base class: EditorFactory

The TextEditor class implements a text editor editor factory for string attributes.

toolkit_factory = 'text_editor': The name of the toolkit factory method.

`ToolButton`¶

class dip.ui.ToolButton¶

Base class: EditorFactory

The ToolButton class implements a tool button editor factory for trigger attributes.

toolkit_factory = 'tool_button': The name of the toolkit factory method.

create(model, controller, parent)¶

Create a tool button instance.

Parameters:	model – is the model. controller – is the controller. parent – is the optional parent view.
Returns:	the tool button instance.

`VBox`¶

class dip.ui.VBox¶

Base class: BoxLayoutFactory

The VBox class arranges its contents vertically.

toolkit_factory = 'v_box': The name of the toolkit factory method.

`ViewFactory`¶

class dip.ui.ViewFactory¶

Base class: Model

The ViewFactory class is the base class for all factories that create views, sub-views and editors.

controller_factory = Callable(): The controller factory. This must return an object that implements or can be adapted to the IController interface.

id = Str(): The view’s identifier. If it is not specified then a sub-class may implements an appropriate default.

toolkit_factory = Str(): The name of the toolkit factory method.

__init__(**properties)¶

Initialize the factory.

Parameters:	**properties – are keyword arguments used as property names and values that are applied to the each object created by the factory.

__call__(model=None, controller=None, parent=None, top_level=True, **properties)¶

Create a view and bind it to a model and optional controller.

Parameters:

model – is the optional model which is either a Model instance or a Python mapping object.
controller – is the optional controller. If this is None then controller_factory will be called to create one.
parent – is the optional parent view.
top_level – is True if the view is to be displayed as a top-level widget.
**properties – are any remaining keyword arguments and are interpreted as attribute names and values to be set for the view.

Returns:

the view.

bind_view(view, controller)¶

Bind a view created by this factory.

Parameters:	view – is the view. controller – is the controller.

configure(view)¶

Reimplemented to configure the IView specific attributes.

Parameters:	view – is the view to configure. It should be an implementation of the `IView` interface.

create(model, controller, parent)¶

Create the view instance.

Parameters:	model – is the model. controller – is the controller. parent – is the optional parent view.
Returns:	the view.

create_view(parent)¶

Use the toolkit to create an instance of the view.

Parameters:	parent – is the optional parent view.
Returns:	the view.

finalize(view)¶

This is called when the creation of a view has been completed. This default implementation does nothing.

Parameters:	view – is the view created by this factory.

static get_natural_name(name)¶

Convert a name, typically of an attribute, to a more natural name.

Parameters:	name – is the original name.
Returns:	the more natural version.

`ViewStack`¶

class dip.ui.ViewStack¶

Base class: ContainerFactory

The ViewStack class arranges its contents as a stack where only one view is visible at a time.

toolkit_factory = 'view_stack': The name of the toolkit factory method.

`Wizard`¶

class dip.ui.Wizard¶

Base class: ContainerFactory

The Wizard class implements a wizard factory, i.e. it creates views that implement the IWizard interface.

contents = List(WizardPage): The contents of the view.

id = 'dip.wizard': The identifier of each widget created by the factory.

toolkit_factory = 'wizard': The name of the toolkit factory method.

`WizardController`¶

class dip.ui.WizardController¶

Base class: Controller

The WizardController class is a controller for handling wizards.

auto_update_model = False: This determines if the controller should automatically update the model when the user changes the value of an editor. If it is not set then the model is only updated when the current page changes or when the wizard is completed.

editors_to_validate()¶

Return the sequence of editors to validate.

Returns:	the sequence of editors.

update_view()¶: Reimplemented to disable the accept button if the view is invalid.

`WizardPage`¶

class dip.ui.WizardPage¶

Base class: SingleSubviewContainerFactory

The WizardPage class implements the page of a wizard.

toolkit_factory = 'wizard_page': The name of the toolkit factory method.