:mod:`dip.ui`
=============
.. module:: dip.ui

The :mod:`dip.ui` module implements a :term:`toolkit` independent API for
defining a user interface declaratively.


:class:`Action`
---------------
.. class:: Action

    Base class: :class:`~dip.model.ValueTypeFactory`

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

    .. method:: Action.__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.
        
        :param bind_to:
            is the name of the attribute that actions are bound to.  This may
            be an :term:`attribute path`.  This should not be specified when an
            attribute type is being defined.
        :param id:
            is the action's identifier.  It is ignored if the action is being
            bound to an attribute.
        :param checkable:
            is set if the action is checkable.
        :param checked:
            is set if the action is checked.
        :param enabled:
            is set if the action is enabled.
        :param shortcut:
            is the shortcut.
        :param status_tip:
            is the status tip.
        :param 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.
        :param tool_tip:
            is the tool tip.
        :param visible:
            is set if the action is visible.
        :param whats_this:
            is the "What's This?" help.
        :param within:
            is the identifier of an optional collection of actions that this
            action will be placed within.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Action.__call__(model)

        Create the action.  This behaviour is similar to a view factory.
        
        :param model:
            is the model.
        :return:
            the action.

    .. method:: Action.bind(model, value, rebind=False)

        This is called when a model attribute is being bound or rebound.
        
        :param model:
            is the model.
        :param value:
            is the attribute's new value.
        :param rebind:
            is set if the attribute already has a value.

    .. method:: Action.clone()

        Create a clone of this instance.
        
        :return:
            the cloned instance.

    .. method:: Action.copy()

        Create a copy of this instance.
        
        :return:
            the copied instance.

    .. method:: Action.create()

        Create the action.
        
        :return:
            the action.

    .. classmethod:: Action.different(value1, value2)

        Reimplemented to compare two instances to see if they are
        different.
        
        :param value1:
            is the first value.
        :param value2:
            is the second value.
        :return:
            ``True`` if the values are different.

    .. method:: Action.get_default_value()

        Get the type's default value.  This will always be a new
        implementation of IAction.

    .. method:: Action.triggered(triggered_func)

        This is used to decorate a method that will be invoked when the
        action is triggered.

    .. method:: Action.validate(value)

        Validate an instance according to the constraints.  An exception
        is raised if the instance is invalid.
        
        :param value:
            the instance to validate.
        :return:
            the validated instance.


:class:`ActionCollection`
-------------------------
.. class:: ActionCollection

    Base class: :class:`~dip.model.ValueTypeFactory`

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

    .. method:: ActionCollection.__init__(*action_ids, id=None, text='', within='', **metadata)

        Initialise the object.
        
        :param \*action_ids:
            is the list of the identifiers of actions contained in the
            collection.
        :param 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.
        :param 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).
        :param within:
            is the identifier of an optional action collection that this
            collection will be placed within.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: ActionCollection.__call__(model)

        Create the action collection.  This behaviour is similar to a view
        factory.
        
        :param model:
            is the model.
        :return:
            the action collection.

    .. method:: ActionCollection.copy()

        Create a copy of this instance.
        
        :return:
            the copied instance.

    .. classmethod:: ActionCollection.different(value1, value2)

        Reimplemented to compare two instances to see if they are
        different.
        
        :param value1:
            is the first value.
        :param value2:
            is the second value.
        :return:
            ``True`` if the values are different.

    .. method:: ActionCollection.get_default_value()

        Get the type's default value.  This will always be a new
        implementation of IActionCollection.

    .. method:: ActionCollection.validate(value)

        Validate an instance according to the constraints.  An exception
        is raised if the instance is invalid.
        
        :param value:
            the instance to validate.
        :return:
            the validated instance.


:class:`Application`
--------------------
.. class:: Application

    The Application class creates a singleton application that implements,
    or can be adapted to the :class:`~dip.ui.IApplication` interface.

    .. staticmethod:: Application.__new__(argv=None, **properties)

        Create the application.
        
        :param argv:
            is the sequence of command line arguments.  By default
            :attr:`sys.argv` is used.
        :param \*\*properties:
            are the keyword arguments used as toolkit specific property names
            and values that are used to configure the application.
        :return:
            the application.

    .. staticmethod:: Application.information(window_title, text, parent=None)

        Display a informational message to the user.
        
        :param window_title:
            is the window title, typically used as the title of a dialog.
        :param text:
            is the text of the message.
        :param parent:
            is the optional parent view.

    .. staticmethod:: Application.question(window_title, text, parent=None, detail='', buttons=('no', 'yes'))

        Ask the user a question.
        
        :param window_title:
            is the window title, typically used as the title of a dialog.
        :param text:
            is the text of the question.
        :param parent:
            is the optional parent view.
        :param detail:
            is the optional additional detail.
        :param 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.
        :return:
            The button that was pressed.

    .. staticmethod:: Application.warning(window_title, text, parent=None, detail='')

        Display a warning message to the user.
        
        :param window_title:
            is the window title, typically used as the title of a dialog.
        :param text:
            is the text of the warning.
        :param parent:
            is the optional parent view.
        :param detail:
            is the optional additional detail.


:class:`Bindings`
-----------------
.. class:: Bindings

    Base class: :class:`~dip.model.Model`

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

    .. attribute:: controller_factory = Callable()

        The controller factory.  This must return an object that implements or
        can be adapted to the :class:`~dip.ui.IController` interface.

    .. method:: Bindings.__init__(**bindings)

        Initialise the bindings.
        
        :param \*\*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 :class:`~dip.ui.EditorFactory` instance will be
            automatically created for it.

    .. method:: Bindings.bind(view, model, controller=None)

        Bind a view to a model and optional controller.
        
        :param view:
            is the view.
        :param model:
            is the model which is either a :class:`~dip.model.Model` instance
            or a Python mapping object.
        :param controller:
            is the optional controller.  If this is ``None`` then
            :attr:`~dip.ui.Bindings.controller_factory` will be called to
            create one.


:class:`BoxLayoutFactory`
-------------------------
.. class:: BoxLayoutFactory

    Base class: :class:`~dip.ui.ContainerFactory`

    The BoxLayoutFactory class is the base class for all factories that
    create views that can contain :class:`~dip.ui.Stretch`.

    .. method:: BoxLayoutFactory.create_additional_content(content)

        Create additional content to be added to the list of sub-views.
        
        :param content:
            the content from which additional content can be created.
        :return:
            the additional content.


:class:`CheckBox`
-----------------
.. class:: CheckBox

    Base class: :class:`~dip.ui.EditorFactory`

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

    .. attribute:: toolkit_factory = 'check_box'

        The name of the toolkit factory method.


:class:`CollectionValidator`
----------------------------
.. class:: CollectionValidator

    Base class: :class:`~dip.model.Model`

    The CollectionValidator class implements an editor validator for
    collections.

    .. method:: CollectionValidator.configure(editor)

        Configure an editor to use this validator.
        
        :param editor:
            is the editor.

    .. method:: CollectionValidator.validate(controller, editor, value)

        Validate an editor's value.
        
        :param controller:
            is the controller.
        :param editor:
            is the editor.
        :param value:
            is the value.
        :return:
            a string describing why the value is invalid.  An empty string is
            returned if the value is valid.


:class:`ComboBox`
-----------------
.. class:: ComboBox

    Base class: :class:`~dip.ui.OptionSelectorFactory`

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

    .. attribute:: toolkit_factory = 'combo_box'

        The name of the toolkit factory method.


:class:`ContainerFactory`
-------------------------
.. class:: ContainerFactory

    Base class: :class:`~dip.ui.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.

    .. attribute:: 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
        :class:`~dip.ui.IAction` or :class:`~dip.ui.ActionCollection` interfaces.

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

    .. attribute:: contents = List()

        The contents of the view.

    .. method:: ContainerFactory.__init__(*contents, **properties)

        Initialise the factory.
        
        :param \*contents:
            is the list of the view's contents.  An individual item can either
            be a :class:`~dip.ui.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
            :term:`attribute path`.
        :param \*\*properties:
            are keyword arguments used as property names and values that are
            applied to the view.

    .. method:: ContainerFactory.configure_subviews(view, subviews)

        Configure a sequence of sub-views before adding them to the
        containing view.
        
        :param view:
            is the containing view.
        :param subviews:
            is the sequence of sub-views.

    .. method:: ContainerFactory.create(model, controller, parent)

        Create a view instance.
        
        :param model:
            is the model.
        :param controller:
            is the controller.
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: ContainerFactory.create_additional_content(content)

        Create additional content to be added to the list of sub-views.
        This default implementation will always raise an exception.
        
        :param content:
            the content from which additional content can be created.
        :return:
            the additional content.

    .. method:: ContainerFactory.create_subviews(model, controller, view)

        Create the sub-views for a containing view.
        
        :param model:
            is the model.
        :param controller:
            is the controller.
        :param view:
            is the containing view.
        :return:
            the sub-views.

    .. method:: ContainerFactory.finalize(view)

        Reimplemented to finalize the sub-views.
        
        :param view:
            is the view created by this factory.


:class:`Controller`
-------------------
.. class:: Controller

    Base class: :class:`~dip.model.Model`

    The Controller class is the default implementation of a
    :term:`controller`.

    .. method:: Controller.__getattr__(name)

        Reimplemented to support convenient access to actions and editors
        using a name derived from an identifier.
        
        :param 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.
        :return:
            the attribute.  An AttributeError will be raised if there was no
            such attribute, action or editor.

    .. method:: Controller.add_action(action)

        Add an action to the controller.
        
        :param action:
            is the action.

    .. method:: Controller.add_editor(editor)

        Add an editor to the controller.
        
        :param editor:
            is the editor.

    .. method:: Controller.editors_to_validate()

        Return the sequence of editors to validate.
        
        :return:
            the sequence of editors.

    .. method:: Controller.find_action(id, tail=False)

        Find the action with a particular identifier.
        
        :param id:
            is the identifier of the action.
        :param tail:
            if this is set then only the last part of a dotted action
            identifier is compared.
        :return:
            the action or ``None`` if there was no such action.

    .. method:: Controller.find_editor(id, tail=False)

        Find the editor with a particular identifier.
        
        :param id:
            is the identifier of the editor.
        :param tail:
            if this is set then only the last part of a dotted editor
            identifier is compared.
        :return:
            the editor or ``None`` if there was no such editor.

    .. method:: Controller.is_valid(editor=None)

        Return the validity of an editor's (or all editors) current value.
        
        :param editor:
            is the editor.  If this is ``None`` then the validity of all
            editors is returned.
        :return:
            ``True`` if the editor (or all editors) is valid.

    .. method:: Controller.update_model()

        Update the all the attributes of a model that have a corresponding
        editor.

    .. method:: Controller.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.

    .. method:: Controller.validate()

        Validate the view and update the explanation as to why it is (or
        isn't) invalid.

    .. method:: Controller.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.
        
        :return:
            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.


:class:`Designer`
-----------------
.. class:: Designer

    Base class: :class:`~dip.ui.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.

    .. attribute:: bindings = Instance(Bindings)

        The bindings that connect the GUI to the model.

    .. attribute:: ui_file_name = Str()

        The name of toolkit specific design file.

    .. method:: Designer.__init__(ui_file_name, **properties)

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

    .. method:: Designer.create(model, controller, parent)

        Create a view instance.
        
        :param model:
            is the model.
        :param controller:
            is the controller.
        :param parent:
            is the optional parent view.
        :return:
            the view that is the root of the user interface defined in the .ui
            file.


:class:`Dialog`
---------------
.. class:: Dialog

    Base class: :class:`~dip.ui.SingleSubviewContainerFactory`

    The Dialog class implements a dialog factory, i.e. it creates views
    that implement the :class:`~dip.ui.IDialog` interface.

    .. attribute:: auto_form = 'always'

        The contents should always be automatically wrapped in a
        :class:`~dip.ui.Form`.

    .. attribute:: id = 'dip.dialog'

        The identifier of each widget created by the factory.

    .. attribute:: toolkit_factory = 'dialog'

        The name of the toolkit factory method.


:class:`DialogController`
-------------------------
.. class:: DialogController

    Base class: :class:`~dip.ui.Controller`

    The DialogController class is a :term:`controller` for handling
    dialogs.

    .. attribute:: auto_update_model = False

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

    .. method:: DialogController.update_view()

        Reimplemented to disable the accept button if the view is invalid.
                


:class:`Dock`
-------------
.. class:: Dock

    Base class: :class:`~dip.ui.SingleSubviewContainerFactory`

    The Dock class implements a dock of a main window. 

    .. attribute:: toolkit_factory = 'dock'

        The name of the toolkit factory method.


:class:`EditorFactory`
----------------------
.. class:: EditorFactory

    Base class: :class:`~dip.ui.ViewFactory`

    The EditorFactory class is a factory for views that implement the
    :class:`~dip.ui.IEditor` interface.  The :attr:`~dip.ui.IEditor.label`,
    :attr:`~dip.ui.IEditor.validator`, :attr:`~dip.ui.IView.status_tip`,
    :attr:`~dip.ui.IView.tool_tip` and :attr:`~dip.ui.IView.whats_this`
    attributes will default to any values defined in the type's meta-data.

    .. attribute:: bind_to = Str()

        The name of the attribute that the editor is bound to.  This may be an
        :term:`attribute path`.

    .. method:: EditorFactory.__init__(bind_to='', **properties)

        Initialise the factory.
        
        :param 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.
        :param \*\*properties:
            are keyword arguments used as property names and values that are
            applied to the editor.

    .. method:: EditorFactory.bind_editor(editor, model, name, controller)

        Bind an editor to a model attribute and add it to a controller.
        
        :param editor:
            is the editor.
        :param model:
            is the model.
        :param name:
            is the name of the attribute.  It may be an :term:`attribute path`.
        :param controller:
            is the controller.

    .. method:: EditorFactory.configure(view)

        Reimplemented to configure the IEditor specific attributes.
        
        :param view:
            is the view to configure.

    .. method:: EditorFactory.configure_with_attribute_type(view, attribute_type)

        Configure the view possibly using values from the bound attribute's
        type.
        
        :param view:
            is the view to configure.
        :param attribute_type:
            is the attribute's type.

    .. method:: EditorFactory.create(model, controller, parent)

        Create a view instance.
        
        :param model:
            is the model.
        :param controller:
            is the controller.
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: EditorFactory.set_default_validator(view)

        Sets a view's default validator.  This implementation does nothing.
        
        :param view:
            is the view.


:class:`FilesystemLocationEditor`
---------------------------------
.. class:: FilesystemLocationEditor

    Base class: :class:`~dip.ui.EditorFactory`

    The FilesystemLocationEditor class implements a filesystem location
    editor factory.  Note that :class:`~dip.ui.StorageLocationEditor` should
    normally be used instead.

    .. attribute:: required = Bool(False)

        This is set if a value is required.

    .. attribute:: toolkit_factory = 'filesystem_location_editor'

        The name of the toolkit factory method.

    .. method:: FilesystemLocationEditor.set_default_validator(view)

        Sets a view's default validator.
        
        :param view:
            is the view.


:class:`FilesystemLocationValidator`
------------------------------------
.. class:: FilesystemLocationValidator

    Base class: :class:`~dip.model.Model`

    The FilesystemLocationValidator class implements an editor validator
    for filesystem locations.

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

    .. attribute:: required = Bool(False)

        This is set if a value is required.

    .. method:: FilesystemLocationValidator.configure(editor)

        Configure an editor to use this validator.
        
        :param editor:
            is the editor.

    .. method:: FilesystemLocationValidator.validate(controller, editor, value)

        Validate an editor's value.
        
        :param controller:
            is the controller.
        :param editor:
            is the editor.
        :param value:
            is the value.
        :return:
            a string describing why the value is invalid.  An empty string is
            returned if the value is valid.


:class:`FloatSpinBox`
---------------------
.. class:: FloatSpinBox

    Base class: :class:`~dip.ui.EditorFactory`

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

    .. attribute:: toolkit_factory = 'float_spin_box'

        The name of the toolkit factory method.

    .. method:: FloatSpinBox.configure_with_attribute_type(view, attribute_type)

        Configure the view possibly using values from the bound attribute's
        type.
        
        :param view:
            is the view to configure.
        :param attribute_type:
            is the attribute's type.


:class:`Form`
-------------
.. class:: Form

    Base class: :class:`~dip.ui.ContainerFactory`

    The Form class arranges its contents as a form. 

    .. attribute:: auto_populate = True

        If there are no explicit contents then automatically populate the form
        with the model's attribute types.

    .. attribute:: toolkit_factory = 'form'

        The name of the toolkit factory method.

    .. method:: Form.configure_subviews(view, subviews)

        Configure a sequence of sub-views before adding them to the
        containing view.
        
        :param view:
            is the containing view.
        :param subviews:
            is the sequence of sub-views.


:class:`Grid`
-------------
.. class:: Grid

    Base class: :class:`~dip.ui.ContainerFactory`

    The Grid class arranges its contents in a grid. 

    .. attribute:: toolkit_factory = 'grid'

        The name of the toolkit factory method.


:class:`GroupBox`
-----------------
.. class:: GroupBox

    Base class: :class:`~dip.ui.SingleSubviewContainerFactory`

    The GroupBox class arranges its contents in a group box. 

    .. attribute:: toolkit_factory = 'group_box'

        The name of the toolkit factory method.


:class:`HBox`
-------------
.. class:: HBox

    Base class: :class:`~dip.ui.BoxLayoutFactory`

    The HBox class arranges its contents horizontally. 

    .. attribute:: toolkit_factory = 'h_box'

        The name of the toolkit factory method.


:class:`IAction`
----------------
.. class:: IAction

    Base class: :class:`~dip.ui.IObject`

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

    .. attribute:: checkable = Bool()

        This is set if the action is checkable.

    .. attribute:: checked = Bool(False)

        This is set if the action is checked.

    .. attribute:: enabled = Bool()

        This is set if the action is enabled.

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

    .. attribute:: shortcut = Str()

        The shortcut.

    .. attribute:: status_tip = Str()

        The status tip.

    .. attribute:: text = Str()

        The text of the action.

    .. attribute:: tool_tip = Str()

        The tool tip.

    .. attribute:: trigger = Trigger()

        This is set when the action is triggered.

    .. attribute:: visible = Bool()

        This is set if the widget is visible.

    .. attribute:: whats_this = Str()

        The "What's This?" help.

    .. attribute:: when_triggered = Callable()

        This is called when the action is triggered.  It is passed the action as
        its only argument.

    .. attribute:: within = Str()

        The identifier of an optional collection of actions that this action will
        be placed within.


:class:`IActionBinding`
-----------------------
.. class:: IActionBinding

    Base class: :class:`~dip.model.Interface`

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

    .. attribute:: attribute_is_type = Bool()

        This is set if attribute in the model is a type rather than a callable.

    .. attribute:: attribute_name = Str()

        The name of the attribute in the model.  This is not an
        :term:`attribute path`.

    .. attribute:: model = Instance(Model)

        The model containing the attribute.


:class:`IActionCollection`
--------------------------
.. class:: IActionCollection

    Base class: :class:`~dip.ui.IObject`

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

    .. attribute:: actions = List(Instance(IAction, Str()))

        The actions contained in the collection.

    .. attribute:: text = Str()

        The text of the action collection.

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


:class:`IApplication`
---------------------
.. class:: IApplication

    Base class: :class:`~dip.model.Interface`

    The IApplication interface defines the API to be implemented by an
    application created by :class:`~dip.ui.Application`.

    .. attribute:: active_view = Instance(IView)

        The active view (i.e. the one with the focus).

    .. method:: IApplication.execute()

        Execute the application, i.e. enter its event loop.  It will return
        when the event loop terminates.
        
        :return:
            An integer exit code.

    .. method:: IApplication.quit()

        Quit the application, i.e. force its event loop to terminate. 


:class:`IBox`
-------------
.. class:: IBox

    Base class: :class:`~dip.ui.IContainer`

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

    .. attribute:: views = Tuple(Instance(IView, Stretch))

        The contained sub-views.


:class:`ICheckBox`
------------------
.. class:: ICheckBox

    Base class: :class:`~dip.ui.IEditor`

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


:class:`ICollectionEditor`
--------------------------
.. class:: ICollectionEditor

    Base class: :class:`~dip.ui.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).

    .. method:: ICollectionEditor.retrieve_invalid_reason()

        Retrieve the invalid reason for an item in the collection.
        
        :return:
            is the invalid reason.  It will be an empty string if all items are
            valid.

    .. method:: ICollectionEditor.save_invalid_reason(invalid_reason)

        Save the invalid reason for the current item in the collection.
        
        :param invalid_reason:
            is the invalid reason.  It will be an empty string if the item is
            valid.


:class:`IComboBox`
------------------
.. class:: IComboBox

    Base class: :class:`~dip.ui.IOptionSelector`

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


:class:`IContainer`
-------------------
.. class:: IContainer

    Base class: :class:`~dip.ui.IView`

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

    .. attribute:: actions = List(Instance(IAction, IActionCollection))

        The list of actions.

    .. attribute:: views = Tuple(IView)

        The contained sub-views.


:class:`IController`
--------------------
.. class:: IController

    Base class: :class:`~dip.model.Interface`

    The IController interface defines the API to be implemented by a
    :term:`view's<view>` :term:`controller`.

    .. attribute:: actions = List(IAction)

        The list of actions.

    .. attribute:: auto_update_model = Bool(True)

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

    .. attribute:: editors = List(IEditor)

        The list of editors being controlled.

    .. attribute:: invalid_reason = Str()

        This explains why the view is invalid.  It will be an empty string if
        the view is valid.

    .. attribute:: message_areas = List(IMessageArea)

        The message areas for giving feedback to the user.

    .. attribute:: model = Instance(Model)

        The model.

    .. attribute:: view = Instance(IView)

        The view.

    .. method:: IController.__getattr__(name)

        Reimplemented to support convenient access to actions and editors
        using a name derived from an identifier.
        
        :param 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).
        :return:
            the attribute.  An AttributeError will be raised if there was no
            such attribute, action or editor.

    .. method:: IController.add_action(action)

        Add an action to the controller.
        
        :param action:
            is the action.

    .. method:: IController.add_editor(editor)

        Add an editor to the controller.
        
        :param editor:
            is the editor.

    .. method:: IController.find_action(id)

        Find the action with a particular identifier.
        
        :param id:
            is the identifier of the action.
        :return:
            the action or ``None`` if there was no such action.

    .. method:: IController.find_editor(id)

        Find the editor with a particular identifier.
        
        :param id:
            is the identifier of the editor.
        :return:
            the editor or ``None`` if there was no such editor.

    .. method:: IController.is_valid(editor=None)

        Return the validity of an editor's (or all editors) current value.
        
        :param editor:
            is the editor.  If this is ``None`` then the validity of all
            editors is returned.
        :return:
            ``True`` if the editor (or all editors) is valid.

    .. method:: IController.update_model()

        Update the all the attributes of a model that have a corresponding
        editor.

    .. method:: IController.update_view()

        This is called after the view has been validated giving the
        controller an opportunity to update the state of the view.

    .. method:: IController.validate()

        Validate the view and update the explanation as to why it is (or
        isn't) invalid.

    .. method:: IController.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.
        
        :return:
            a string which will be empty if the view is valid, otherwise it
            will explain why the view is invalid.


:class:`IDialog`
----------------
.. class:: IDialog

    Base class: :class:`~dip.ui.ISingleViewContainer`

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

    .. attribute:: acceptable = Bool(True)

        This is set, typically by a :term:`controller`, when the contents of the
        dialog are acceptable.

    .. attribute:: accepted = Trigger()

        This is pulled when the user accepts the dialog.

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

        The dialog buttons.

    .. method:: IDialog.execute()

        Execute the dialog as a modal dialog.
        
        :return:
            ``True`` if the user accepted the dialog.


:class:`IDialogController`
--------------------------
.. class:: IDialogController

    Base class: :class:`~dip.ui.IController`

    The IDialogController interface defines the API to be implemented by a
    dialog's :term:`controller`.

    .. attribute:: view = Instance(IDialog)

        The view.


:class:`IDisplay`
-----------------
.. class:: IDisplay

    Base class: :class:`~dip.model.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.

    .. attribute:: name = Str()

        The name to be displayed to the user.  This should uniquely identify the
        object to the user.

    .. attribute:: short_name = Str()

        The optional short name.


:class:`IDock`
--------------
.. class:: IDock

    Base class: :class:`~dip.ui.ISingleViewContainer`

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

    .. attribute:: action = Instance(IAction)

        The action that will toggle the dock's visibility.

    .. attribute:: area = Enum('left', 'right', 'top', 'bottom')

        The dock area that the dock is initially placed in.

    .. attribute:: within = Str()

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


:class:`IEditor`
----------------
.. class:: IEditor

    Base class: :class:`~dip.ui.IView`

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

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

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

    .. attribute:: read_only = Bool(False)

        This is set if the editor is read-only.

    .. attribute:: validator = Instance(IValidator)

        The editor's validator.

    .. attribute:: value = Any()

        The value of the editor.

    .. method:: IEditor.remove_label()

        Remove an editor's label.  This will only be called if the label
        policy is 'optional'.


:class:`IEditorBinding`
-----------------------
.. class:: IEditorBinding

    Base class: :class:`~dip.ui.IViewBinding`

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

    .. attribute:: attribute_name = Str()

        The name of the attribute in the model.  This is not an
        :term:`attribute path`.

    .. attribute:: attribute_type = Instance(TypeFactory)

        The type of the attribute in the model.

    .. attribute:: model = Instance(Model)

        The model containing the attribute.


:class:`IFilesystemLocationEditor`
----------------------------------
.. class:: IFilesystemLocationEditor

    Base class: :class:`~dip.ui.IEditor`

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

    .. attribute:: filter = Str()

        The filter as defined by :attr:`~dip.io.IFilterHints.filter`.

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


:class:`IFloatSpinBox`
----------------------
.. class:: IFloatSpinBox

    Base class: :class:`~dip.ui.IEditor`

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

    .. attribute:: maximum = Float()

        The maximum value.

    .. attribute:: minimum = Float()

        The minimum value.


:class:`IForm`
--------------
.. class:: IForm

    Base class: :class:`~dip.ui.IContainer`

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

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


:class:`IGrid`
--------------
.. class:: IGrid

    Base class: :class:`~dip.ui.IContainer`

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

    .. attribute:: nr_columns = Int()

        The number of columns in the grid.

    .. attribute:: nr_rows = Int()

        The number of rows in the grid.


:class:`IGroupBox`
------------------
.. class:: IGroupBox

    Base class: :class:`~dip.ui.ISingleViewContainer`

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

    .. attribute:: title = Str()

        The title of the group box.


:class:`IHBox`
--------------
.. class:: IHBox

    Base class: :class:`~dip.ui.IBox`

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


:class:`ILabel`
---------------
.. class:: ILabel

    Base class: :class:`~dip.ui.IEditor`

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


:class:`ILineEditor`
--------------------
.. class:: ILineEditor

    Base class: :class:`~dip.ui.IEditor`

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


:class:`IListEditor`
--------------------
.. class:: IListEditor

    Base class: :class:`~dip.ui.ICollectionEditor`

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

    .. attribute:: columns = List(ListColumn)

        The list of columns.

    .. attribute:: item_factory = Callable()

        When called this will create the data for a new item in the list.


:class:`IMainWindow`
--------------------
.. class:: IMainWindow

    Base class: :class:`~dip.ui.ISingleViewContainer`

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

    .. attribute:: docks = List(IDock)

        The list of docks.

    .. attribute:: menu_bar = Instance(IMenuBar)

        The menu bar.


:class:`IMenu`
--------------
.. class:: IMenu

    Base class: :class:`~dip.ui.IContainer`

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

    .. attribute:: title = Str()

        The menu's title.

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

    .. attribute:: views = List(Instance(IAction, 'dip.ui.IMenu', Str()))

        The menu's contents.  An empty string means a separator.

    .. method:: IMenu.add_action(action)

        Try and add an action or action collection to the menu.
        
        :param action:
            is the action.
        :return:
            ``True`` if the action was added.  ``False`` is returned if the
            menu couldn't accommodate the action's desired positioning.


:class:`IMenuBar`
-----------------
.. class:: IMenuBar

    Base class: :class:`~dip.ui.IContainer`

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

    .. method:: IMenuBar.add_action(action)

        Try and add an action or action collection to the menu bar.
        
        :param action:
            is the action.
        :return:
            ``True`` if the action was added.  ``False`` is returned if the
            menu bar couldn't accommodate the action's desired positioning.


:class:`IMessageArea`
---------------------
.. class:: IMessageArea

    Base class: :class:`~dip.ui.IView`

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

    .. attribute:: text = Str()

        The text displayed in the message area.


:class:`IObject`
----------------
.. class:: IObject

    Base class: :class:`~dip.model.Interface`

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

    .. attribute:: id = Str()

        The object's identifier.

    .. method:: IObject.configure(properties)

        Configure the object using a mapping of toolkit specific property
        names and values.
        
        :param properties:
            is the mapping of the properties.


:class:`IOptionList`
--------------------
.. class:: IOptionList

    Base class: :class:`~dip.ui.IOptionSelector`

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


:class:`IOptionSelector`
------------------------
.. class:: IOptionSelector

    Base class: :class:`~dip.ui.IEditor`

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

    .. attribute:: labels = Tuple(Str())

        The optional option labels.  These are used to visualise the
        corresponding options.

    .. attribute:: options = Tuple()

        The options.  If an option has no corresponding label then it will be
        adapted to the :class:`~dip.ui.IDisplay` interface and its
        :attr:`~dip.ui.IDisplay.name` used (which will default to its string
        representation).

    .. attribute:: sorted = Bool(False)

        This is set of the options should be sorted.


:class:`IPushButton`
--------------------
.. class:: IPushButton

    Base class: :class:`~dip.ui.IEditor`

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


:class:`IRadioButtons`
----------------------
.. class:: IRadioButtons

    Base class: :class:`~dip.ui.IOptionSelector`

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

    .. attribute:: vertical = Bool(True)

        The orientation of the radio buttons.


:class:`ISingleViewContainer`
-----------------------------
.. class:: ISingleViewContainer

    Base class: :class:`~dip.ui.IContainer`

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

    .. attribute:: view = Instance(IView)

        The contained sub-view.


:class:`ISpinBox`
-----------------
.. class:: ISpinBox

    Base class: :class:`~dip.ui.IEditor`

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

    .. attribute:: maximum = Int()

        The maximum value.

    .. attribute:: minimum = Int()

        The minimum value.


:class:`ISplitter`
------------------
.. class:: ISplitter

    Base class: :class:`~dip.ui.IContainer`

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


:class:`IStorageLocationEditor`
-------------------------------
.. class:: IStorageLocationEditor

    Base class: :class:`~dip.ui.IEditor`

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

    .. attribute:: filter_hints = Str()

        The filter hints as defined by :attr:`~dip.io.IFilterHints.filter`.

    .. attribute:: format = Str()

        The identifier of the format.

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


:class:`ITabBar`
----------------
.. class:: ITabBar

    Base class: :class:`~dip.ui.IContainer`

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

    .. attribute:: current_page = Instance(ITabPage)

        The current page.

    .. attribute:: tabs_visible = Bool()

        This is set if the tabs are visible.

    .. attribute:: views = List(ITabPage)

        The tab bar's pages.  Note that, unlike most other containers, the
        sequence of views is mutable.


:class:`ITabPage`
-----------------
.. class:: ITabPage

    Base class: :class:`~dip.ui.ISingleViewContainer`

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

    .. attribute:: title = Str()

        The page's title.


:class:`ITableEditor`
---------------------
.. class:: ITableEditor

    Base class: :class:`~dip.ui.ICollectionEditor`

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

    .. attribute:: columns = List(TableColumn)

        The list of columns.

    .. attribute:: row_factory = Callable()

        When called this will create the data for a new row in the table.


:class:`ITextEditor`
--------------------
.. class:: ITextEditor

    Base class: :class:`~dip.ui.IEditor`

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


:class:`IToolButton`
--------------------
.. class:: IToolButton

    Base class: :class:`~dip.ui.IEditor`

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

    .. attribute:: action = Instance(IAction)

        The tool button's action.


:class:`IVBox`
--------------
.. class:: IVBox

    Base class: :class:`~dip.ui.IBox`

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


:class:`IValidator`
-------------------
.. class:: IValidator

    Base class: :class:`~dip.model.Interface`

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

    .. method:: IValidator.configure(editor)

        Configure an editor to use this validator.
        
        :param editor:
            is the editor.

    .. method:: IValidator.validate(controller, editor, value)

        Validate an editor's value.
        
        :param controller:
            is the controller.
        :param editor:
            is the editor.
        :param value:
            is the value.
        :return:
            a string describing why the value is invalid.  An empty string is
            returned if the value is valid.


:class:`IView`
--------------
.. class:: IView

    Base class: :class:`~dip.ui.IObject`

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

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

    .. attribute:: enabled = Bool(True)

        This is set if the view is enabled.

    .. attribute:: ready = Trigger()

        This is triggered when the view is about to be made visible for the first
        time.

    .. attribute:: status_tip = Str()

        The status tip.

    .. attribute:: tool_tip = Str()

        The tool tip.

    .. attribute:: visible = Bool(True)

        This is set if the view is visible.

    .. attribute:: whats_this = Str()

        The "What's This?" help.

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

    .. method:: IView.all_views()

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

    .. method:: IView.set_focus()

        Give the focus to the view. 


:class:`IViewBinding`
---------------------
.. class:: IViewBinding

    Base class: :class:`~dip.model.Interface`

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

    .. attribute:: controller = Instance(IController)

        The controller.

    .. attribute:: factory = Instance(.ViewFactory)

        The factory that created the view.


:class:`IViewStack`
-------------------
.. class:: IViewStack

    Base class: :class:`~dip.ui.IContainer`

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

    .. attribute:: current_view = Instance(IView)

        The current view.

    .. attribute:: views = List(IView)

        The contained sub-views.  Note that, unlike most other containers, the
        sequence of views is mutable.


:class:`IWizard`
----------------
.. class:: IWizard

    Base class: :class:`~dip.ui.IContainer`

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

    .. attribute:: current_page = Instance(IWizardPage)

        The current page.

    .. attribute:: finished = Trigger()

        This is pulled when the user finishes the wizard.

    .. attribute:: views = Tuple(IWizardPage)

        The wizard's pages.

    .. method:: IWizard.execute()

        Execute the wizard.
        
        :return:
            ``True`` if the user accepted the wizard.


:class:`IWizardController`
--------------------------
.. class:: IWizardController

    Base class: :class:`~dip.ui.IController`

    The IWizardController interface defines the API to be implemented by a
    wizard's :term:`controller`.

    .. attribute:: current_page = Instance(IWizardPage)

        The current page.

    .. attribute:: view = Instance(IWizard)

        The view.


:class:`IWizardPage`
--------------------
.. class:: IWizardPage

    Base class: :class:`~dip.ui.ISingleViewContainer`

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

    .. attribute:: acceptable = Bool(True)

        This is set, typically by a :term:`controller`, when the contents of the
        page are acceptable.

    .. attribute:: subtitle = Str()

        The page's sub-title.

    .. attribute:: title = Str()

        The page's title.


:class:`Label`
--------------
.. class:: Label

    Base class: :class:`~dip.ui.EditorFactory`

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

    .. attribute:: toolkit_factory = 'label'

        The name of the toolkit factory method.


:class:`LineEditor`
-------------------
.. class:: LineEditor

    Base class: :class:`~dip.ui.EditorFactory`

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

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

    .. attribute:: toolkit_factory = 'line_editor'

        The name of the toolkit factory method.

    .. method:: LineEditor.set_default_validator(view)

        Sets a view's default validator.
        
        :param view:
            is the view.


:class:`ListColumn`
-------------------
.. class:: ListColumn

    Base class: :class:`~dip.model.Model`

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

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

    .. attribute:: 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 :class:`~dip.model.Any` then
        :class:`~dip.model.Str` is used.

    .. attribute:: editor_factory = Callable()

        The factory for the view created to edit a value in the column.  It will
        default to the list editor's :attr:`~dip.ui.ListEdit.editor_factory`.

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

    .. method:: ListColumn.__init__(bind_to='')

        Initialise the column.
        
        :param 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.


:class:`ListEditor`
-------------------
.. class:: ListEditor

    Base class: :class:`~dip.ui.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.

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

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

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

    .. attribute:: toolkit_factory = 'list_editor'

        The name of the toolkit factory method.

    .. method:: ListEditor.configure(view)

        Reimplemented to configure the IListEditor specific attributes.
        
        :param view:
            is the view to configure.

    .. method:: ListEditor.set_default_validator(view)

        Sets a view's default validator.
        
        :param view:
            is the view.


:class:`MainWindow`
-------------------
.. class:: MainWindow

    Base class: :class:`~dip.ui.SingleSubviewContainerFactory`

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

    .. attribute:: docks = List(Dock)

        The list of dock factories.

    .. attribute:: id = 'dip.main_window'

        The identifier of each widget created by the factory.

    .. attribute:: menu_bar = Instance(MenuBar)

        The factory for the menu bar.

    .. attribute:: toolkit_factory = 'main_window'

        The name of the toolkit factory method.

    .. method:: MainWindow.create_subviews(model, controller, view)

        Create the sub-views for a containing view.
        
        :param model:
            is the model.
        :param controller:
            is the controller.
        :param view:
            is the containing view.
        :return:
            the sub-views.

    .. method:: MainWindow.finalize(view)

        Reimplemented to finalize any menu bar and docks.
        
        :param view:
            is the view created by this factory.


:class:`Menu`
-------------
.. class:: Menu

    Base class: :class:`~dip.ui.ContainerFactory`

    The Menu class implements a factory for menus that implement or can be
    adapted to :class:`~dip.ui.IMenu`.

    .. attribute:: contents = List(Instance(.Menu, Str()))

        The contents of the view.

    .. attribute:: toolkit_factory = 'menu'

        The name of the toolkit factory method.

    .. attribute:: visible = False

        Menu's are hidden by default.  They will be visible when they contain
        something that is visible.

    .. method:: Menu.create_subviews(model, controller, view)

        Create the sub-views for a containing view.
        
        :param model:
            is the model.
        :param controller:
            is the controller.
        :param view:
            is the containing view.
        :return:
            the sub-views.


:class:`MenuBar`
----------------
.. class:: MenuBar

    Base class: :class:`~dip.ui.ContainerFactory`

    The MenuBar class implements a factory for menu bars that implement or
    can be adapted to :class:`~dip.ui.IMenuBar`.

    .. attribute:: contents = List(Menu)

        The contents of the view.

    .. attribute:: toolkit_factory = 'menu_bar'

        The name of the toolkit factory method.


:class:`MessageArea`
--------------------
.. class:: MessageArea

    Base class: :class:`~dip.ui.ViewFactory`

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

    .. attribute:: toolkit_factory = 'message_area'

        The name of the toolkit factory method.

    .. method:: MessageArea.bind_view(view, controller)

        Reimplemented to add the message area view to a controller.
        
        :param view:
            is the view.
        :param controller:
            is the controller.


:class:`OptionList`
-------------------
.. class:: OptionList

    Base class: :class:`~dip.ui.OptionSelectorFactory`

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

    .. attribute:: toolkit_factory = 'option_list'

        The name of the toolkit factory method.


:class:`OptionSelectorFactory`
------------------------------
.. class:: OptionSelectorFactory

    Base class: :class:`~dip.ui.EditorFactory`

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

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

    .. attribute:: labels = List(Str())

        The optional option labels.  These are used to visualise the
        corresponding options.

    .. attribute:: 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
        :class:`~dip.ui.IDisplay` interface and its :attr:`~dip.ui.IDisplay.name`
        used (which defaults to its string representation).

    .. method:: OptionSelectorFactory.configure_with_attribute_type(view, attribute_type)

        Configure the view possibly using values from the bound attribute's
        type.
        
        :param view:
            is the view to configure.
        :param attribute_type:
            is the attribute's type.

    .. method:: OptionSelectorFactory.set_default_validator(view)

        Sets a view's default validator.
        
        :param view:
            is the view.


:class:`OptionValidator`
------------------------
.. class:: OptionValidator

    Base class: :class:`~dip.model.Model`

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

    .. method:: OptionValidator.configure(editor)

        Configure an editor to use this validator.
        
        :param editor:
            is the editor.

    .. method:: OptionValidator.validate(controller, editor, value)

        Validate an editor's value.
        
        :param controller:
            is the controller.
        :param editor:
            is the editor.
        :param value:
            is the value.
        :return:
            a string describing why the value is invalid.  An empty string is
            returned if the value is valid.


:class:`PushButton`
-------------------
.. class:: PushButton

    Base class: :class:`~dip.ui.EditorFactory`

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

    .. attribute:: toolkit_factory = 'push_button'

        The name of the toolkit factory method.


:class:`RadioButtons`
---------------------
.. class:: RadioButtons

    Base class: :class:`~dip.ui.OptionSelectorFactory`

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

    .. attribute:: toolkit_factory = 'radio_buttons'

        The name of the toolkit factory method.


:class:`SingleSubviewContainerFactory`
--------------------------------------
.. class:: SingleSubviewContainerFactory

    Base class: :class:`~dip.ui.ContainerFactory`

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

    .. attribute:: auto_form = Enum('non-empty', 'always', 'never')

        Determines if any sub-views should automatically be placed in a
        :class:`~dip.ui.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
        :class:`~dip.ui.ContainerFactory` instance then a form will never be
        used.

    .. method:: SingleSubviewContainerFactory.__init__(*contents, **properties)

        Initialise the factory.
        
        :param \*contents:
            is the list of the view's contents.  An individual item can either
            be a :class:`~dip.ui.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
            :term:`attribute path`.
        :param \*\*properties:
            are keyword arguments used as property names and values that are
            applied to the view.


:class:`SpinBox`
----------------
.. class:: SpinBox

    Base class: :class:`~dip.ui.EditorFactory`

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

    .. attribute:: toolkit_factory = 'spin_box'

        The name of the toolkit factory method.

    .. method:: SpinBox.configure_with_attribute_type(view, attribute_type)

        Configure the view possibly using values from the bound attribute's
        type.
        
        :param view:
            is the view to configure.
        :param attribute_type:
            is the attribute's type.


:class:`Splitter`
-----------------
.. class:: Splitter

    Base class: :class:`~dip.ui.ContainerFactory`

    The Splitter class arranges its contents in a splitter. 

    .. attribute:: toolkit_factory = 'splitter'

        The name of the toolkit factory method.


:class:`StorageLocationEditor`
------------------------------
.. class:: StorageLocationEditor

    Base class: :class:`~dip.ui.EditorFactory`

    The StorageLocationEditor class implements a storage location editor
    factory.

    .. attribute:: required = Bool(False)

        This is set if a value is required.

    .. attribute:: toolkit_factory = 'storage_location_editor'

        The name of the toolkit factory method.

    .. method:: StorageLocationEditor.set_default_validator(view)

        Sets a view's default validator.
        
        :param view:
            is the view.


:class:`StorageLocationValidator`
---------------------------------
.. class:: StorageLocationValidator

    Base class: :class:`~dip.model.Model`

    The StorageLocationValidator class implements an editor validator for
    storage locations.

    .. attribute:: format = Str()

        The identifier of the format.

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

    .. attribute:: required = Bool(False)

        This is set if a value is required.

    .. method:: StorageLocationValidator.configure(editor)

        Configure an editor to use this validator.
        
        :param editor:
            is the editor.

    .. method:: StorageLocationValidator.validate(controller, editor, value)

        Validate an editor's value.
        
        :param controller:
            is the controller.
        :param editor:
            is the editor.
        :param value:
            is the value.
        :return:
            a string describing why the value is invalid.  An empty string is
            returned if the value is valid.


:class:`Stretch`
----------------
.. class:: Stretch

    The Stretch class represents a stretchable space that can be added to
    a view.


:class:`StringValidator`
------------------------
.. class:: StringValidator

    Base class: :class:`~dip.model.Model`

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

    .. attribute:: stripped = Bool(False)

        This specifies that the value should not have leading or trailing spaces.

    .. method:: StringValidator.configure(editor)

        Configure an editor to use this validator.
        
        :param editor:
            is the editor.

    .. method:: StringValidator.validate(controller, editor, value)

        Validate an editor's value.
        
        :param controller:
            is the controller.
        :param editor:
            is the editor.
        :param value:
            is the value.
        :return:
            a string describing why the value is invalid.  An empty string is
            returned if the value is valid.


:class:`TabBar`
---------------
.. class:: TabBar

    Base class: :class:`~dip.ui.ContainerFactory`

    The TabBar class is a container for a number of
    :class:`~dip.ui.TabPage` sub-views.

    .. attribute:: contents = List(TabPage)

        The contents of the view.

    .. attribute:: toolkit_factory = 'tab_bar'

        The name of the toolkit factory method.


:class:`TabPage`
----------------
.. class:: TabPage

    Base class: :class:`~dip.ui.SingleSubviewContainerFactory`

    The TabPage class implements a page of a tab bar. 

    .. attribute:: toolkit_factory = 'tab_page'

        The name of the toolkit factory method.


:class:`TableColumn`
--------------------
.. class:: TableColumn

    Base class: :class:`~dip.model.Model`

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

    .. attribute:: 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 :class:`~dip.model.Any` then
        :class:`~dip.model.Str` is used.

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

    .. attribute:: editable = Bool(True)

        This is set if the values in the column are editable.

    .. attribute:: label = Str(None, allow_none=True)

        The label of the column.


:class:`TableEditor`
--------------------
.. class:: TableEditor

    Base class: :class:`~dip.ui.EditorFactory`

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

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

    .. attribute:: row_factory = Callable()

        When called this will create the data for a new row in the table.

    .. attribute:: toolkit_factory = 'table_editor'

        The name of the toolkit factory method.

    .. method:: TableEditor.configure(view)

        Reimplemented to configure the ITableEditor specific attributes.
        
        :param view:
            is the view to configure.

    .. method:: TableEditor.set_default_validator(view)

        Sets a view's default validator.
        
        :param view:
            is the view.


:class:`TextEditor`
-------------------
.. class:: TextEditor

    Base class: :class:`~dip.ui.EditorFactory`

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

    .. attribute:: toolkit_factory = 'text_editor'

        The name of the toolkit factory method.


:class:`ToolButton`
-------------------
.. class:: ToolButton

    Base class: :class:`~dip.ui.EditorFactory`

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

    .. attribute:: toolkit_factory = 'tool_button'

        The name of the toolkit factory method.

    .. method:: ToolButton.create(model, controller, parent)

        Create a tool button instance.
        
        :param model:
            is the model.
        :param controller:
            is the controller.
        :param parent:
            is the optional parent view.
        :return:
            the tool button instance.


:class:`VBox`
-------------
.. class:: VBox

    Base class: :class:`~dip.ui.BoxLayoutFactory`

    The VBox class arranges its contents vertically. 

    .. attribute:: toolkit_factory = 'v_box'

        The name of the toolkit factory method.


:class:`ViewFactory`
--------------------
.. class:: ViewFactory

    Base class: :class:`~dip.model.Model`

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

    .. attribute:: controller_factory = Callable()

        The controller factory.  This must return an object that implements or
        can be adapted to the :class:`~dip.ui.IController` interface.

    .. attribute:: id = Str()

        The view's identifier.  If it is not specified then a sub-class may
        implements an appropriate default.

    .. attribute:: toolkit_factory = Str()

        The name of the toolkit factory method.

    .. method:: ViewFactory.__init__(**properties)

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

    .. method:: ViewFactory.__call__(model=None, controller=None, parent=None, top_level=True, **properties)

        Create a view and bind it to a model and optional controller.
        
        :param model:
            is the optional model which is either a :class:`~dip.model.Model`
            instance or a Python mapping object.
        :param controller:
            is the optional controller.  If this is ``None`` then
            :attr:`~dip.ui.ViewFactory.controller_factory` will be called to
            create one.
        :param parent:
            is the optional parent view.
        :param top_level:
            is ``True`` if the view is to be displayed as a top-level widget.
        :param \*\*properties:
            are any remaining keyword arguments and are interpreted as
            attribute names and values to be set for the view.
        :return:
            the view.

    .. method:: ViewFactory.bind_view(view, controller)

        Bind a view created by this factory.
        
        :param view:
            is the view.
        :param controller:
            is the controller.

    .. method:: ViewFactory.configure(view)

        Reimplemented to configure the IView specific attributes.
        
        :param view:
            is the view to configure.  It should be an implementation of the
            :class:`~dip.ui.IView` interface.

    .. method:: ViewFactory.create(model, controller, parent)

        Create the view instance.
        
        :param model:
            is the model.
        :param controller:
            is the controller.
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: ViewFactory.create_view(parent)

        Use the toolkit to create an instance of the view.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: ViewFactory.finalize(view)

        This is called when the creation of a view has been completed.
        This default implementation does nothing.
        
        :param view:
            is the view created by this factory.

    .. staticmethod:: ViewFactory.get_natural_name(name)

        Convert a name, typically of an attribute, to a more natural name.
        
        :param name:
            is the original name.
        :return:
            the more natural version.


:class:`ViewStack`
------------------
.. class:: ViewStack

    Base class: :class:`~dip.ui.ContainerFactory`

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

    .. attribute:: toolkit_factory = 'view_stack'

        The name of the toolkit factory method.


:class:`Wizard`
---------------
.. class:: Wizard

    Base class: :class:`~dip.ui.ContainerFactory`

    The Wizard class implements a wizard factory, i.e. it creates views
    that implement the :class:`~dip.ui.IWizard` interface.

    .. attribute:: contents = List(WizardPage)

        The contents of the view.

    .. attribute:: id = 'dip.wizard'

        The identifier of each widget created by the factory.

    .. attribute:: toolkit_factory = 'wizard'

        The name of the toolkit factory method.


:class:`WizardController`
-------------------------
.. class:: WizardController

    Base class: :class:`~dip.ui.Controller`

    The WizardController class is a :term:`controller` for handling
    wizards.

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

    .. method:: WizardController.editors_to_validate()

        Return the sequence of editors to validate.
        
        :return:
            the sequence of editors.

    .. method:: WizardController.update_view()

        Reimplemented to disable the accept button if the view is invalid.
                


:class:`WizardPage`
-------------------
.. class:: WizardPage

    Base class: :class:`~dip.ui.SingleSubviewContainerFactory`

    The WizardPage class implements the page of a wizard. 

    .. attribute:: toolkit_factory = 'wizard_page'

        The name of the toolkit factory method.
