`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. 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.
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 call_after(callable, after=0)¶

Call a callable after a delay.

Parameters:	callable – is the callable. after – is the delay in milliseconds. If it is zero then the callable is called in the next iteration of the event loop.

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.

view_interface = ICheckBox: The specific interface implemented by the view.

`ComboBox`¶

class dip.ui.ComboBox¶

Base class: OptionSelectorFactory

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

view_interface = IComboBox: The specific interface implemented by the view.

`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` 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.

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

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

validate_view()¶

Validate the data in the view. This implementation considers the view to be valid if all its editors have valid values.

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

`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.

buttons = List(DialogButton, default=['ok', 'cancel']): The dialog buttons.

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

view_interface = IDialog: The specific interface implemented by the view.

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.

`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 (and the controller determines that the view is valid).

validate()¶: 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.

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

view_interface = IDock: The specific interface implemented by the view.

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

configure(view)¶

Reimplemented to configure the IDock specific attributes.

Parameters:	view – is the view to configure.

`EditorFactory`¶

class dip.ui.EditorFactory¶

Base class: ViewFactory

The EditorFactory class is a factory for views that implement the IEditor interface. The 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.

label = Str(None, allow_none=True): 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.

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

__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_using_metadata(widget, metadata)¶

Configure the view possibly using values from the bound attribute’s meta-data.

Parameters:	widget – is the widget to configure. metadata – is the attribute’s metadata,

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.

`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.

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.

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

view_interface = IFilesystemLocationEditor: The specific interface implemented by the view.

configure(view)¶

Reimplemented to configure the IFilesystemLocationEditor specific attributes.

Parameters:	editor – is the view to configure.

`FloatSpinBox`¶

class dip.ui.FloatSpinBox¶

Base class: EditorFactory

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

maximum = Float(None, allow_none=True): The maximum value. If not given then any corresponding value of the type’s meta-data is used instead.

minimum = Float(None, allow_none=True): The minimum value. If not given then any corresponding value of the type’s meta-data is used instead.

view_interface = IFloatSpinBox: The specific interface implemented by the view.

configure_using_metadata(view, metadata)¶

Configure the view possibly using values from the bound attribute’s meta-data.

Parameters:	view – is the view to configure. metadata – is the attribute’s metadata,

`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.

view_interface = IForm: The specific interface implemented by 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.

`GroupBox`¶

class dip.ui.GroupBox¶

Base class: SingleSubviewContainerFactory

The GroupBox class arranges its contents in a group box.

view_interface = IGroupBox: The specific interface implemented by the view.

`HBox`¶

class dip.ui.HBox¶

Base class: BoxLayoutFactory

The HBox class arranges its contents horizontally.

view_interface = IHBox: The specific interface implemented by the view.

`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).

item_invalid_reason(invalid_reason)¶

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

Parameters:	index – 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 (and the controller determines that the view is valid).

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.

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

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

validate_view()¶

Validate the data in the view.

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): 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.

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

label = Str(): The editor’s label. This is typically used in a form layout and in error messages.

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.

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.

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

`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.

`IGroupBox`¶

class dip.ui.IGroupBox¶

Base class: ISingleViewContainer

The IGroupBox interface defines the API to be implemented by a 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.

required = Enum('no', 'yes', 'stripped'): This specifies whether or not a value is required. It is applied after any validator has determined that the value is valid. ‘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.

validator = Callable(): The validator factory. It is called to create a validator and will be passed a single argument which is the view that will use the validator. FIXME: Consider a toolkit method that will create a toolkit specific FIXME: validator based on a Python regexp (not a toolkit regexp).

`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(): The visibility of the menu.

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.

allow_none = Bool(True): This is set if None is allowed as a valid value.

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(): 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.

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

`ITabBar`¶

class dip.ui.ITabBar¶

Base class: IContainer

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

current_view = Instance(IView): The current view.

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

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

`ITabPage`¶

class dip.ui.ITabPage¶

Base class: Interface

The ITabPage interface defines the additional data required by a view in the context of a tab page.

title = Str(): The title of the page.

tooltip = Str(): The tooltip of the page.

`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.

`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(): This is set if the view is enabled.

status_tip = Str(): The status tip.

tool_tip = Str(): The tool tip.

visible = Bool(): 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.

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(dip.ui.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.

`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.

view_interface = ILabel: The specific interface implemented by the view.

`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 applied after any validator has determined that the value is valid. ‘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 not given then any corresponding value of the type’s meta-data is used instead.

validator = Callable(): The validator factory. It is called to create a validator and will be passed a single argument which is the view that will use the validator. If not given then any corresponding value of the type’s meta-data is used instead.

view_interface = ILineEditor: The specific interface implemented by the view.

configure_using_metadata(view, metadata)¶

Configure the view possibly using values from the bound attribute’s meta-data.

Parameters:	view – is the view to configure. metadata – is the attribute’s metadata,

`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.

view_interface = IListEditor: The specific interface implemented by the view.

configure(view)¶

Reimplemented to configure the IListEditor specific attributes.

Parameters:	view – is the view to configure.

`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.

view_interface = IMainWindow: The specific interface implemented by the view.

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(dip.ui.Menu, Str())): The contents of the view.

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

view_interface = IMenu: The specific interface implemented by the view.

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

configure(view)¶

Reimplemented to configure the IMenu specific attributes.

Parameters:	view – is the view to configure.

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.

view_interface = IMenuBar: The specific interface implemented by the view.

`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.

view_interface = IMessageArea: The specific interface implemented by the view.

bind_view(view, controller)¶

Reimplemented to add the message area view to a controller.

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

`ObjectFactory`¶

class dip.ui.ObjectFactory¶

Base class: Model

The ObjectFactory class is the base class for all factories that can create an object that implements or can be adapted to the IObject interface.

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

__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.

configure(object)¶

Configure an object created by this factory.

Parameters:	object – is the object to configure.

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.

static object_for_interface(interface, parent)¶

Use the default toolkit to create an object that implements a particular interface.

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

`OptionList`¶

class dip.ui.OptionList¶

Base class: OptionSelectorFactory

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

view_interface = IOptionList: The specific interface implemented by the view.

`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. The default value is taken from the bound attribute’s type.

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

options = List(): The options. 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).

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

configure(view)¶

Reimplemented to configure the IOptionSelector specific attributes.

Parameters:	view – is the view to configure.

`PushButton`¶

class dip.ui.PushButton¶

Base class: EditorFactory

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

view_interface = IPushButton: The specific interface implemented by the view.

`RadioButtons`¶

class dip.ui.RadioButtons¶

Base class: OptionSelectorFactory

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

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

view_interface = IRadioButtons: The specific interface implemented by the view.

configure(view)¶

Reimplemented to configure the IRadioButtons specific attributes.

Parameters:	view – is the view to configure.

`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.

maximum = Int(None, allow_none=True): The maximum value. If not given then any corresponding value of the type’s meta-data is used instead.

minimum = Int(None, allow_none=True): The minimum value. If not given then any corresponding value of the type’s meta-data is used instead.

view_interface = ISpinBox: The specific interface implemented by the view.

configure_using_metadata(view, metadata)¶

Configure the view possibly using values from the bound attribute’s meta-data.

Parameters:	view – is the view to configure. metadata – is the attribute’s metadata,

`Splitter`¶

class dip.ui.Splitter¶

Base class: ContainerFactory

The Splitter class arranges its contents in a splitter.

view_interface = ISplitter: The specific interface implemented by the view.

`StorageLocationEditor`¶

class dip.ui.StorageLocationEditor¶

Base class: EditorFactory

The StorageLocationEditor class implements a storage location editor factory.

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.

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

view_interface = IStorageLocationEditor: The specific interface implemented by the view.

configure(view)¶

Reimplemented to configure the IStorageLocationEditor specific attributes.

Parameters:	view – is the view to configure.

`Stretch`¶

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

`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.

tabs_visible = Bool(None, allow_none=True): This is set if the tabs are visible.

view_interface = ITabBar: The specific interface implemented by the view.

configure(view)¶

Reimplemented to configure the ITabBar specific attributes.

Parameters:	view – is the view to configure.

`TabPage`¶

class dip.ui.TabPage¶

Base class: ViewMetadata

The TabPage class implements a page of a tab bar.

title = Str(None, allow_none=True): The title of the page.

tooltip = Str(None, allow_none=True): The tooltip of the page.

configure(view)¶

Reimplemented to configure the ITabPage specific attributes.

Parameters:	view – is the view.

`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.

view_interface = ITableEditor: The specific interface implemented by the view.

configure(view)¶

Reimplemented to configure the ITableEditor specific attributes.

Parameters:	view – is the view to configure.

`TextEditor`¶

class dip.ui.TextEditor¶

Base class: EditorFactory

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

view_interface = ITextEditor: The specific interface implemented by the view.

`ToolButton`¶

class dip.ui.ToolButton¶

Base class: EditorFactory

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

view_interface = IToolButton: The specific interface implemented by the view.

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.

view_interface = IVBox: The specific interface implemented by the view.

`ViewFactory`¶

class dip.ui.ViewFactory¶

Base class: ObjectFactory

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.

enabled = Bool(None, allow_none=True): This is set if the widget is enabled.

status_tip = Str(None, allow_none=True): The status tip.

tool_tip = Str(None, allow_none=True): The tool tip.

view_interface = Subclass(IView, default=IView): The specific interface implemented by the view.

visible = Bool(None, allow_none=True): This is set if the widget is visible.

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

window_title = Str(None, allow_none=True): The window title.

__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.

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.

finalize(view)¶

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

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

`ViewMetadata`¶

class dip.ui.ViewMetadata¶

Base class: SingleSubviewContainerFactory

The ViewMetadata class behaves like a container for a single view that simply adds additional data to the view, typically using an interface.

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.

`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.

view_interface = IViewStack: The specific interface implemented by the view.

`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.

view_interface = IWizard: The specific interface implemented by the view.

`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 (and the controller determines that the view is valid).

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

validate_page(page)¶

Validate a page of the view.

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

validate_view()¶

Validate the data in the view. This implementation considers the view to be valid if all the editors in the current page have valid values.

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

`WizardPage`¶

class dip.ui.WizardPage¶

Base class: SingleSubviewContainerFactory

The WizardPage class implements the page of a wizard.

subtitle = Str(None, allow_none=True): The sub-title of the page.

title = Str(None, allow_none=True): The title of the page.

view_interface = IWizardPage: The specific interface implemented by the view.

configure(view)¶

Reimplemented to configure the IWizardPage specific attributes.

Parameters:	view – is the view.

Navigation

Previous topic

Next topic

This Page

Quick search

Navigation