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

The :mod:`dip.ui` module contains a collection of classes that allow a
PyQt user interface, or just a part of a user interface, to be defined
declaratively.

A user interface is declared as a hierachy of :term:`views<view>` that are
containers for :term`editor` factories and other views.  A particular view will
arrange its editors or sub-views in a certain way.  An editor allows a
particular attribute of a :term:`model` to be displayed and possibly updated.

Editors are testable, i.e. they can be controlled programmatically to simulate
the actions of a user so that user interfaces can be automatically tested to
ensure that the underlying model is changes as expected.

Views may also include ordinary Qt widgets and layouts and designs created with
Qt Designer.  Views may also be treated as ordinary Qt widgets and layouts in a
larger user interface.

It is not the intention to enable any user interface to be defined
declaratively, or to provide the same level of control provided by PyQt
itself.  The purpose of this module is to allow "boring" user interfaces (e.g.
those used for data entry) to be created very easily, or to provide an initial
user interface that will be replaced by something more specific at a later
stage of an application's development.


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

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

    The Action class implements an :term:`action` implemented, by default,
    as a :class:`~PyQt4.QtGui.QAction`.

    .. attribute:: parent = Instance(QObject)

        The optional parent.

    .. attribute:: triggered = Callable()

        The callable invoked when the action is triggered.


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

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

    The ActionCollection class represents a collection of
    :term:`actions<action>` or sub-collections.

    .. attribute:: members = List(Instance(IAction, str))

        The members of the collection.  A string is the identifier of an action
        and is a placeholder for it.

    .. attribute:: title = Str()

        The optional text to be used in any visualisation of the collection.  A
        collection without a title may be visualised differently to one with a
        title.


:class:`AddButton`
------------------
.. class:: AddButton

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

    The AddButton class implements a factory for a button for adding to a
    collection editor.

    .. attribute:: id_suffix = '.add'

        The suffix to add to the identifier to distinguish it from other linked
        views.

    .. method:: AddButton.create_view(controller, toolkit, parent)

        Create the view.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.
        :param parent:
            is the optional parent widget.
        :return:
            the view which will be an instance of
            :class:`~PyQt4.QtGui.QAbstractButton`.

    .. method:: AddButton.link(view, editor)

        This is reimplemented to link the button view to the collection
        editor.
        
        :param view:
            is the view.
        :param editor:
            is the editor.


:class:`BaseEditorAdapter`
--------------------------
.. class:: BaseEditorAdapter

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

    The BaseEditorAdapter class is a base class for adapters than implement
    the :class:`~dip.ui.IEditor` interface for Qt widgets.

    .. attribute:: change_signal = Any()

        The Qt signal that is emitted when the user changes the editor's value.

    .. method:: BaseEditorAdapter.configure()

        Configure the view.  This is called when everything else has been
        set up.

    .. method:: BaseEditorAdapter.remove_label()

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


:class:`BaseMenu`
-----------------
.. class:: BaseMenu

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

    The BaseMenu class is a base class for action containers, i.e. those
    that implement :class:`~PyQt4.QtGui.QMenuBar` or
    :class:`~PyQt4.QtGui.QMenu`.

    .. classmethod:: BaseMenu.add(item, widget, toolkit, within='', before='')

        An :class:`~dip.ui.IAction` or a :class:`~PyQt4.QtGui.QMenu` is
        added to a menu bar, menu or a sub-menu.
        
        If an existing item has the same identifier as the item being added
        then the existing item will be replaced with the new item.
        
        :param item:
            is the :class:`~dip.ui.IAction` or :class:`~PyQt4.QtGui.QMenu` to
            insert.
        :param widget:
            is the menu bar or menu.
        :param toolkit:
            is the toolkit.
        :param within:
            is the identifier of the action collection or menu that the item
            will be added to.  If it is empty then the item will be added to
            the widget itself.
        :param before:
            is the identifier of the existing item that the item is inserted
            immediately before.  An exception is raised if there is no such
            existing item.  If the identifier is empty then the item will be
            added at the end of the containing widget.


:class:`BaseToolkit`
--------------------
.. class:: BaseToolkit

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

    The BaseToolkit class is a base class for :term:`toolkits<toolkit>`
    that implements the default mapping of :mod:`dip.model` types to the
    :term:`editors<editor>` used to handle them.

    .. attribute:: Bool_editor_factory = Subclass(EditorFactory)

        The editor factory to handle the Bool type.

    .. attribute:: Bool_delegate_factory = Subclass(EditorFactory)

        The delegate editor factory to handle the Bool type.

    .. attribute:: Enum_editor_factory = Subclass(EditorFactory)

        The editor factory to handle the Enum type.

    .. attribute:: Enum_delegate_factory = Subclass(EditorFactory)

        The delegate editor factory to handle the Enum type.

    .. attribute:: Float_editor_factory = Subclass(EditorFactory)

        The editor factory to handle the Float type.

    .. attribute:: Float_delegate_factory = Subclass(EditorFactory)

        The delegate editor factory to handle the Float type.

    .. attribute:: Int_editor_factory = Subclass(EditorFactory)

        The editor factory to handle the Int type.

    .. attribute:: Int_delegate_factory = Subclass(EditorFactory)

        The delegate editor factory to handle the Int type.

    .. attribute:: List_editor_factory = Subclass(EditorFactory)

        The editor factory to handle the List type.

    .. attribute:: Str_editor_factory = Subclass(EditorFactory)

        The editor factory to handle the Str type.

    .. attribute:: Str_delegate_factory = Subclass(EditorFactory)

        The delegate editor factory to handle the Str type.

    .. attribute:: Trigger_editor_factory = Subclass(EditorFactory)

        The editor factory to handle the Trigger type.

    .. method:: BaseToolkit.delegate_for_attribute(attribute_type)

        Return an :class:`~dip.ui.EditorFactory` type object that will
        create a delegate factory to handle attributes of a particular type.
        
        :param attribute_type:
            is the type of the attribute.
        :return:
            the type object.

    .. method:: BaseToolkit.editor_for_attribute(attribute_type)

        Return an :class:`~dip.ui.EditorFactory` type object that will
        create an editor factory to handle attributes of a particular type.
        
        :param attribute_type:
            is the type of the attribute.
        :return:
            the type object.


:class:`BaseValidator`
----------------------
.. class:: BaseValidator

    Base class: :class:`~PyQt4.QtGui.QValidator`

    The BaseValidator class is a base class for a
    :class:`~PyQt4.QtGui.QValidator` that supplies a reason why the input is
    invalid.  The reason is saved in the ``dip_invalid_reason`` attribute after
    :meth:`~PyQt4.QtGui.QValidator.validate` method is called.

    .. method:: BaseValidator.__init__(parent=None)

        Initialise the validator.
        
        :param parent:
            is the optional parent object.


:class:`BaseViewAdapter`
------------------------
.. class:: BaseViewAdapter

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

    The BaseViewAdapter class is a base class for adapters than implement
    the :class:`~dip.ui.IView` interface for Qt layouts and widgets.

    .. method:: BaseViewAdapter.configure()

        Configure the view.  This is called when everything else has been
        set up.  This default implementation applies the factory properties to
        the adaptee.


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

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

    .. 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, toolkit, controller=None)

        Bind a view to a model.
        
        :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 toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.
        :param controller:
            is the optional controller.  A new :class:`~dip.ui.Controller`
            instance will be created if necessary.


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

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

    The BoxLayoutFactory class is the base class for all factories that
    create views that are implemented as :class:`~PyQt4.QtGui.QBoxLayout`
    instances.

    .. 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:: view_interface = ICheckBoxEditor

        The specific interface that the view implements.

    .. method:: CheckBox.create_editor(attribute_type, toolkit, parent)

        Create the editor.
        
        :param attribute_type:
            the type of the attribute the factory is being asked to handle.  It
            should be a :class:`~dip.model.Bool`.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.
        :param parent:
            is the optional parent widget.
        :return:
            the editor.


:class:`CollectionButtons`
--------------------------
.. class:: CollectionButtons

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

    The CollectionButtons class contains the standard buttons used to
    manipulate a collection editor.  Use the buttons separately if you want to
    lay them out differently.

    .. method:: CollectionButtons.__init__(linked_to, **properties)

        Initialise the item.
        
        :param linked_to:
            is the identifier of the editor that each button is linked to.
        :param \*\*properties:
            are keyword arguments used as property names and values that are
            applied to the view.


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

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

    The ComboBox class implements a combo box editor factory for enum
    attributes.

    .. attribute:: view_interface = IComboBoxEditor

        The specific interface that the view implements.

    .. method:: ComboBox.create_editor(attribute_type, toolkit, parent)

        Create the editor.
        
        :param attribute_type:
            the type of the attribute the factory is being asked to handle.  It
            should be an :class:`~dip.model.Enum`.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.
        :param parent:
            is the optional parent widget.
        :return:
            the editor.


:class:`CompositeViewFactory`
-----------------------------
.. class:: CompositeViewFactory

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

    The CompositeViewFactory 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:: view_interface = ICompositeView

        The specific interface that the view implements.

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

        Initialise the view.
        
        :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:: CompositeViewFactory.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:: CompositeViewFactory.create_subviews(controller, toolkit, parent)

        Return a list of :class:`~PyQt4.QtGui.QLayout` and
        :class:`~PyQt4.QtGui.QWidget` instances that implement the sub-views.
        A sub-class may include additional contents of different types, but
        these must be able to be handled by the view that the factory creates.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.
        :param parent:
            is the optional parent widget.
        :return:
            the list of :class:`~PyQt4.QtGui.QLayout` and
            :class:`~PyQt4.QtGui.QWidget` instances.

    .. method:: CompositeViewFactory.finalize(item)

        Reimplemented to finalize all sub-views.
        
        :param item:
            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 get an instance attribute allowing for names in
        the form 'id_editor' where 'id' is the identifier of the editor.

    .. method:: Controller.add_editor(editor)

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

    .. method:: Controller.editor_changed(editor)

        This is called by an editor when the user has changed its value.
        
        :param editor:
            is the editor.

    .. method:: Controller.find_editor(id)

        Find the editor with a specific identifier.
        
        :param id:
            is the identifier of the editor.
        :return:
            the editor or ``None`` if the view has no such editor.

    .. method:: Controller.update_model()

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

    .. method:: Controller.validate()

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

    .. method:: Controller.validate_view()

        Validate the data in the view.  This implementation considers the
        view to be valid if all its editors have valid values.
        
        :return:
            a string which will be empty if the view is valid, otherwise it
            will explain why the view is invalid.


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

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

    The Designer class allows any user interface created with Qt Designer
    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 the Qt Designer .ui 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_subview(controller, toolkit, attribute_type)

        Create the editor for the user interface.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation.
        :param parent:
            is the optional parent widget.
        :param attribute_type:
            is ``None`` in this context.
        :return:
            the editor that is the root of the user interface defined in the
            .ui file.

    .. method:: Designer.create_view(controller, toolkit, parent)

        Create the editor for the user interface.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation.
        :param parent:
            is the optional parent widget.
        :return:
            the editor that is the root of the user interface defined in the
            .ui file.


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

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

    The Dialog class implements a :class:`~PyQt4.QtGui.QDialog` based
    dialog.

    .. attribute:: buttons = Instance(QDialogButtonBox.StandardButtons)

        The buttons to display.

    .. method:: Dialog.create_controller()

        Create an implementation of :class:`~dip.ui.IController`.
        
        :return:
            the controller.

    .. method:: Dialog.create_view(controller, toolkit, parent)

        Create the view.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.
        :param parent:
            is the optional parent widget.
        :return:
            the :class:`~PyQt4.QtGui.QLayout` or :class:`~PyQt4.QtGui.QWidget`
            that is the root of the view's implementation.


:class:`DirectoryValidator`
---------------------------
.. class:: DirectoryValidator

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

    The DirectoryValidator class is a validator that checks that the input
    is the name of an existing directory.

    .. method:: DirectoryValidator.validate(input, pos)

        Validate the input.
        
        :param input:
            is the input to validate.
        :param pos:
            is the current position within the input.
        :return:
            a 3-tuple of the state, possibly modified input and possibly
            modified position.


:class:`DownButton`
-------------------
.. class:: DownButton

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

    The DownButton class implements a factory for a button for moving an
    item down a collection editor.

    .. attribute:: id_suffix = '.down'

        The suffix to add to the identifier to distinguish it from other linked
        views.

    .. method:: DownButton.create_view(controller, toolkit, parent)

        Create the view.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.
        :param parent:
            is the optional parent widget.
        :return:
            the view which will be an instance of
            :class:`~PyQt4.QtGui.QAbstractButton`.

    .. method:: DownButton.link(view, editor)

        This is reimplemented to link the button view to the collection
        editor.
        
        :param view:
            is the view.
        :param editor:
            is the editor.


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

    .. attribute:: bind_to = Str()

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

    .. attribute:: default_metadata_properties = List(Str(), default=['statusTip', 'toolTip', 'whatsThis'])

        The default list of Qt properties that should be set for the editor with
        the values taken from the model attribute's meta-data.

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

        The list of extra Qt properties that should be set for the editor with
        the values taken from the model attribute's meta-data.

    .. 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 the
        ``label`` 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:: read_only = Bool(False)

        This is set if the attribute is read-only.

    .. 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(view, controller, toolkit, attribute_type)

        Reimplemented to bind an editor view to a model attribute and add
        it to a controller.
        
        :param view:
            is the view.
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.
        :param attribute_type:
            is the type of the attribute of a model the view is being bound to.

    .. method:: EditorFactory.configure_editor(editor, attribute_type)

        Configure an editor using the factory's properties and any
        additional properties supplied when the factory was created.
        
        :param editor:
            is the editor.  Note that this isn't necessarily the
            :class:`~dip.ui.IEditor` implementation but may be an internal
            widget that the properties are to be applied to.
        :param attribute_type:
            is the type of the attribute in the model the editor is bound to.

    .. method:: EditorFactory.create_editor(attribute_type, toolkit, parent)

        Create the :class:`~PyQt4.QtGui.QLayout` or
        :class:`~PyQt4.QtGui.QWidget` that implements the editor
        and can be adapted to :class:`~dip.ui.IEditor`.
        
        This must be reimplemented by a sub-class.
        
        :param attribute_type:
            is the type of the attribute in the model that the editor is bound
            to.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.
        :param parent:
            is the optional parent widget.
        :return:
            the :class:`~PyQt4.QtGui.QLayout` or :class:`~PyQt4.QtGui.QWidget`
            that is the root of the editor's implementation.

    .. method:: EditorFactory.create_view(controller, toolkit, parent)

        Create the view.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.
        :param parent:
            is the optional parent widget.
        :return:
            the view.

    .. classmethod:: EditorFactory.editor_as_delegate(delegate_type, toolkit)

        Create an editor factory to be used as a delegate for a type.
        
        :param delegate_type:
            is the type of the value that the delegate will edit.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation that provides the
            mapping between types and delegates.
        :return:
            the editor factory.

    .. method:: EditorFactory.get_attribute_label(attribute_type)

        Get the label for an attribute.  This will first try the factory
        itself, then the type's meta-data and finally the type's name.
        
        :param attribute_type:
            is the attribute type.
        :return:
            the label.

    .. classmethod:: EditorFactory.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.

    .. method:: EditorFactory.set_delegate(item_view, delegate_type, toolkit, column_nr=0)

        Create a delegate and set it for a column of a
        :class:`~PyQt4.QtGui.QAbstractItemView`.
        
        :param item_view:
            is the :class:`~PyQt4.QtGui.QAbstractItemView`.
        :param delegate_type:
            is the type of the value that the delegate will edit.
        :param column_nr:
            is the number of the column.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.


:class:`FileSelector`
---------------------
.. class:: FileSelector

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

    The FileSelector class implements a file (and directory) selector
    editor factory.

    .. attribute:: filter = Str()

        The filter string in the format used by
        :class:`~PyQt4.QtGui.QFileDialog`.

    .. attribute:: mode = Enum('open_file', 'save_file', 'directory')

        The mode of the file selector.  '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:: validator = Callable()

        The validator factory.  This is called and passed a parent
        :class:`~PyQt4.QtCore.QObject` and should return a
        :class:`~PyQt4.QtGui.QValidator` instance.  If
        :attr:`~dip.ui.FileSelector.mode` is 'open_file' then the default is
        :class:`~dip.ui.FileValidator`.  If it is 'directory' then the default is
        :class:`~dip.ui.DirectoryValidator`.

    .. attribute:: view_interface = IFileSelectorEditor

        The specific interface that the view implements.

    .. method:: FileSelector.create_editor(attribute_type, toolkit, parent)

        Create the editor.
        
        :param attribute_type:
            the type of the attribute the factory is being asked to handle.  It
            should be a :class:`~dip.model.Str`.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.
        :param parent:
            is the optional parent widget.
        :return:
            the editor.


:class:`FileValidator`
----------------------
.. class:: FileValidator

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

    The FileValidator class is a validator that checks that the input is
    the name of an existing file.

    .. method:: FileValidator.validate(input, pos)

        Validate the input.
        
        :param input:
            is the input to validate.
        :param pos:
            is the current position within the input.
        :return:
            a 3-tuple of the state, possibly modified input and possibly
            modified position.


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

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

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

    .. attribute:: extra_metadata_properties = ['maximum', 'minimum']

        Extra properties set from the attribute's metadata.

    .. attribute:: view_interface = IFloatSpinBoxEditor

        The specific interface that the view implements.

    .. method:: FloatSpinBox.create_editor(attribute_type, toolkit, parent)

        Create the editor.
        
        :param attribute_type:
            the type of the attribute the factory is being asked to handle.  It
            should be a :class:`~dip.model.Float`.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.
        :param parent:
            is the optional parent widget.
        :return:
            the editor.


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

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

    The Form class arranges its contents as a form. 

    .. method:: Form.create_layout(items, toolkit)

        Create a layout for a form sub-view.
        
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            horizontal box layout.
        :param attribute_type:
            is ``None`` in this context.
        :return:
            the :class:`~PyQt4.QtGui.QLayout` instance that is the view's
            implementation.


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

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

    The GroupBox class arranges its contents in a group box. 

    .. method:: GroupBox.create_view(controller, toolkit, parent)

        Create the view.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.
        :param parent:
            is the optional parent widget.  It is ignored in this context.
        :return:
            the :class:`~PyQt4.QtGui.QLayout` or :class:`~PyQt4.QtGui.QWidget`
            that is the root of the view's implementation.


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

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

    The HBox class arranges its contents horizontally. 

    .. method:: HBox.create_layout(items, toolkit)

        Create a layout for a horizontal sub-view.
        
        :param items:
            is a sequence of :class:`~PyQt4.QtGui.QLayout`,
            :class:`~PyQt4.QtGui.QWidget` and :class:`~dip.ui.Stretch`
            instances.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            layout.
        :return:
            the layout.


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

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

    The IAction interface defines the API for an :term:`action` that can be
    identified and positioned relative to another.

    .. attribute:: before = Str()

        The identifier of the action before which this action will be placed.

    .. attribute:: id = Str()

        The identifier of the action.

    .. attribute:: within = Str()

        The identifier of action in which this action will be placed.


:class:`ICheckBoxEditor`
------------------------
.. class:: ICheckBoxEditor

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

    The ICheckBoxEditor interface defines the API to be implemented by an
    editor created by :class:`~dip.ui.CheckBox`.  It is used as a marker to
    ensure the correct adapter is chosen.


: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 created by an
    :class:`~dip.ui.EditorFactory` that handles a collection type (e.g. a
    list).

    .. attribute:: item_count = Int()

        The number of items in the collection.  This can only be read.

    .. attribute:: selection = List(QModelIndex)

        The current selection.

    .. method:: ICollectionEditor.add(value=None, edit=True)

        Add a new item to the collection.
        
        :param value:
            is the value of the item.  If it is ``None`` then an appropriate
            value will be created automatically.
        :param edit:
            is set if an editor should be open automatically for the new item.

    .. method:: ICollectionEditor.item_invalid_reason(index, invalid_reason)

        Update the invalid reason for an item in the collection.
        
        :param index:
            is the :class:`~PyQt4.QtCore.QModelIndex` of the item.
        :param index:
            is the invalid reason.  It will be an empty string if the item is
            valid.

    .. method:: ICollectionEditor.move_down(index)

        Move an item down.
        
        :param index:
            is the :class:`~PyQt4.QtCore.QModelIndex` of the item.

    .. method:: ICollectionEditor.move_up(index)

        Move an item up.
        
        :param index:
            is the :class:`~PyQt4.QtCore.QModelIndex` of the item.

    .. method:: ICollectionEditor.remove(indexes)

        Remove a number of items from the collection.
        
        :param indexes:
            is the list of :class:`~PyQt4.QtCore.QModelIndex` defining the
            items to be removed.


:class:`IComboBoxEditor`
------------------------
.. class:: IComboBoxEditor

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

    The IComboBoxEditor interface defines the API to be implemented by an
    editor created by :class:`~dip.ui.ComboBox`.  It is used as a marker to
    ensure the correct adapter is chosen.


:class:`ICompositeView`
-----------------------
.. class:: ICompositeView

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

    The ICompositeView interface defines the API to be implemented
    (typically using adaptation) by a :class:`~PyQt4.QtGui.QLayout` or
    :class:`~PyQt.QtGui.QWidget` created by a
    :class:`~dip.ui.CompositeViewFactory`.

    .. method:: ICompositeView.subviews()

        Return a sequence of sub-views, i.e. instances of
        :class:`~PyQt4.QtGui.QLayout` or :class:`~PyQt4.QtGui.QWidget` that
        implement or have been adapted to :class:`~dip.ui.IView`.
        
        :return:
            the sequence of 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:: 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).

    .. 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(QLayout, QWidget)

        The view.

    .. method:: IController.__getattr__(name)

        Reimplemented to get an instance attribute allowing for names in
        the form 'attr_editor' where 'attr' is the name of a model attribute.

    .. method:: IController.add_editor(editor)

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

    .. method:: IController.editor_changed(editor)

        This is called by an editor when the user has changed its value.
        
        :param editor:
            is the editor.

    .. method:: IController.find_editor(id)

        Find the editor with a specific identifier.
        
        :param id:
            is the identifier of the editor.
        :return:
            the editor or ``None`` if the view has no such editor.

    .. method:: IController.update_model()

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

    .. method:: IController.validate()

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

    .. method:: IController.validate_view()

        Validate the data in the view.
        
        :return:
            a string which will be empty if the view is valid, otherwise it
            will explain why the view is invalid.


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

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

    The IEditor interface defines the API to be implemented (typically
    using adaptation) by a :class:`~PyQt.QtGui.QWidget` created by an
    :class:`~dip.ui.EditorFactory`.

    .. attribute:: enabled = Bool(True)

        This is set if the editor is enabled.

    .. attribute:: invalid_reason = Str()

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

    .. attribute:: label = Str()

        The editor's label.  This is typically used in a form layout and in error
        messages.

    .. 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:: attribute_type = Instance(TypeFactory)

        The type of the attribute in the model.

    .. 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:`IFileSelectorEditor`
----------------------------
.. class:: IFileSelectorEditor

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

    The IFileSelectorEditor interface defines the API to be implemented by
    an editor created by :class:`~dip.ui.FileSelector`.  It is used as a marker
    to ensure the correct adapter is chosen.


:class:`IFloatSpinBoxEditor`
----------------------------
.. class:: IFloatSpinBoxEditor

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

    The IFloatSpinBoxEditor interface defines the API to be implemented by
    an editor created by :class:`~dip.ui.FloatSpinBox`.  It is used as a marker
    to ensure the correct adapter is chosen.


:class:`ILineEditEditor`
------------------------
.. class:: ILineEditEditor

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

    The ILineEditEditor interface defines the API to be implemented by an
    editor created by :class:`~dip.ui.LineEdit`.  It is used as a marker to
    ensure the correct adapter is chosen.


:class:`IListWidgetEditor`
--------------------------
.. class:: IListWidgetEditor

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

    The IListWidgetEditor interface defines the API to be implemented by an
    editor created by :class:`~dip.ui.ListWidget`.  It is used as a marker to
    ensure the correct adapter is chosen.


: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 and created by a
    :class:`~dip.ui.MessageArea`.

    .. attribute:: text = Str()

        The text displayed in the message area.


:class:`IPushButtonEditor`
--------------------------
.. class:: IPushButtonEditor

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

    The IPushButtonEditor interface defines the API to be implemented by an
    editor created by :class:`~dip.ui.PushButton`.  It is used as a marker to
    ensure the correct adapter is chosen.


:class:`IQActionAction`
-----------------------
.. class:: IQActionAction

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

    The IQActionAction interface defines the API for an :term:`action` that
    is implemented as a :class:`~PyQt4.QtGui.QAction`.

    .. attribute:: action = Instance(QAction)

        The :class:`~PyQt4.QtGui.QAction` that is the actual action.

    .. attribute:: shortcut = Instance(QKeySequence, QKeySequence.StandardKey, str)

        The action's shortcut.

    .. attribute:: statusTip = Str()

        The action's status tip.  The naming convention is to maintain
        compatibility with the standard QAction property.

    .. attribute:: text = Str()

        The action's text.

    .. attribute:: toolTip = Str()

        The action's tool tip.  The naming convention is to maintain
        compatibility with the standard QAction property.


:class:`IRadioButtonsEditor`
----------------------------
.. class:: IRadioButtonsEditor

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

    The IRadioButtonsEditor interface defines the API to be implemented by
    an editor created by :class:`~dip.ui.RadioButtons`.  It is used as a marker
    to ensure the correct adapter is chosen.


:class:`ISpinBoxEditor`
-----------------------
.. class:: ISpinBoxEditor

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

    The ISpinBoxEditor interface defines the API to be implemented by an
    editor created by :class:`~dip.ui.SpinBox`.  It is used as a marker to
    ensure the correct adapter is chosen.


:class:`ITableWidgetEditor`
---------------------------
.. class:: ITableWidgetEditor

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

    The ITableWidgetEditor interface defines the API to be implemented by
    an editor created by :class:`~dip.ui.TableWidget`.  It is used as a marker
    to ensure the correct adapter is chosen.


:class:`ITextEditEditor`
------------------------
.. class:: ITextEditEditor

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

    The ITextEditEditor interface defines the API to be implemented by an
    editor created by :class:`~dip.ui.TextEdit`.  It is used as a marker to
    ensure the correct adapter is chosen.


:class:`IToolButtonEditor`
--------------------------
.. class:: IToolButtonEditor

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

    The IToolButtonEditor interface defines the API to be implemented by an
    editor created by :class:`~dip.ui.ToolButton`.  It is used as a marker to
    ensure the correct adapter is chosen.


:class:`IToolkit`
-----------------
.. class:: IToolkit

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

    The IToolkit interface defines the API to be implemented by a
    :term:`toolkit`.

    .. method:: IToolkit.add_button(factory, parent)

        Create a button to add an item to a collection.
        
        :param factory:
            is the factory creating the button.
        :param parent:
            is the optional parent widget.
        :return:
            the button which will be a :class:`~PyQt4.QtGui.QAbstractButton`.

    .. method:: IToolkit.check_box(factory, attribute_type, parent)

        Create an editor based on a check box.
        
        :param factory:
            is the factory creating the editor.
        :param attribute_type:
            is the attribute type.
        :param parent:
            is the parent widget.
        :return:
            the editor.

    .. method:: IToolkit.combo_box(factory, attribute_type, parent)

        Create an editor based on a combo box.
        
        :param factory:
            is the factory creating the editor.
        :param attribute_type:
            is the attribute type.
        :param parent:
            is the parent widget.
        :return:
            the editor.

    .. method:: IToolkit.delegate_for_attribute(attribute_type)

        Return an :class:`~dip.ui.EditorFactory` type object that will
        create a delegate factory to handle attributes of a particular type.
        
        :param attribute_type:
            is the type of the attribute.
        :return:
            the type object.

    .. method:: IToolkit.dialog(factory, content, parent)

        Create a dialog view.
        
        :param factory:
            is the factory creating the view.
        :param content:
            is the content of the dialog and is either a
            :class:`~PyQt4.QtGui.QLayout` or a :class:`~PyQt4.QtGui.QWidget`.
        :param parent:
            is the optional parent widget.
        :return:
            the view.

    .. method:: IToolkit.down_button(factory, parent)

        Create a button to move an item in a collection down.
        
        :param factory:
            is the factory creating the button.
        :param parent:
            is the optional parent widget.
        :return:
            the button which will be a :class:`~PyQt4.QtGui.QAbstractButton`.

    .. method:: IToolkit.editor_for_attribute(attribute_type)

        Return an :class:`~dip.ui.EditorFactory` type object that will
        create an editor factory to handle attributes of a particular type.
        
        :param attribute_type:
            is the type of the attribute.
        :return:
            the type object.

    .. method:: IToolkit.editor_for_widget(widget_type)

        Return an :class:`~dip.ui.EditorFactory` type object that will
        create an editor factory that creates editors of a particular type.
        
        :param widget_type:
            is the type of the widget.
        :return:
            the type object.

    .. method:: IToolkit.file_selector(factory, attribute_type, parent)

        Create an editor that implements a file/directory selector.
        
        :param factory:
            is the factory creating the editor.
        :param attribute_type:
            is the attribute type.
        :param parent:
            is the parent widget.
        :return:
            the editor.

    .. method:: IToolkit.float_spin_box(factory, attribute_type, parent)

        Create an editor for floats based on a spin box.
        
        :param factory:
            is the factory creating the editor.
        :param attribute_type:
            is the attribute type.
        :param parent:
            is the parent widget.
        :return:
            the editor.

    .. method:: IToolkit.form(factory, items)

        Create a view to contain a number of items arranged as a form.
        
        :param factory:
            is the optional factory creating the view.
        :param items:
            is a sequence of 2-tuple label and field pairs.  A label may be
            ``None``.  A field may be a :class:`~PyQt4.QtGui.QLayout` or a
            :class:`~PyQt4.QtGui.QWidget`.
        :return:
            the view.

    .. method:: IToolkit.get_directory(directory='', parent=None)

        Get the name of an existing directory from the user.
        
        :param directory:
            is the name of an optional initial directory.
        :param parent:
            is the optional parent widget.
        :return:
            the name of the directory or an empty string if there was none.

    .. method:: IToolkit.get_open_file(directory='', filter='', parent=None)

        Get the name of a file to open from the user.
        
        :param directory:
            is the name of an optional initial directory or file.
        :param filter:
            is the optional file filter.
        :param parent:
            is the optional parent widget.
        :return:
            the name of the file to open or an empty string if there was none.

    .. method:: IToolkit.get_open_files(directory='', filter='', parent=None)

        Get a list of names of files to open from the user.
        
        :param directory:
            is the name of an optional initial directory or file.
        :param filter:
            is the optional file filter.
        :param parent:
            is the optional parent widget.
        :return:
            the list of names.

    .. method:: IToolkit.get_save_file(directory='', filter='', parent=None)

        Get the name of a file to save from the user.
        
        :param directory:
            is the name of an optional initial directory or file.
        :param filter:
            is the optional file filter.
        :param parent:
            is the optional parent widget.
        :return:
            the name of the file to save or an empty string if there was none.

    .. method:: IToolkit.group_box(factory, content, parent)

        Create a group box view.
        
        :param factory:
            is the factory creating the view.
        :param content:
            is the content of the view and is either a
            :class:`~PyQt4.QtGui.QLayout` or a :class:`~PyQt4.QtGui.QWidget`.
        :param parent:
            is the optional parent widget.
        :return:
            the view.

    .. method:: IToolkit.h_box(factory, items)

        Create a view to contain a number of items arranged horizontally.
        
        :param factory:
            is the factory creating the view.
        :param items:
            is a sequence of :class:`~PyQt4.QtGui.QLayout`,
            :class:`~PyQt4.QtGui.QWidget` and :class:`~dip.ui.Stretch`
            instances.
        :return:
            the view.

    .. method:: IToolkit.information(title, text, parent=None)

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

    .. method:: IToolkit.line_edit(factory, attribute_type, parent)

        Create an editor based on a line editor.
        
        :param factory:
            is the factory creating the editor.
        :param attribute_type:
            is the attribute type.
        :param parent:
            is the parent widget.
        :return:
            the editor.

    .. method:: IToolkit.list_widget(factory, attribute_type, parent)

        Create an editor for a list.
        
        :param factory:
            is the factory creating the editor.
        :param attribute_type:
            is the attribute type.
        :param parent:
            is the parent widget.
        :return:
            the editor.

    .. method:: IToolkit.menu(title, parent)

        Create a menu.
        
        :param title:
            is the menu's title.
        :param parent:
            is the menu's parent.
        :return:
            the menu which will be an instance of :class:`~PyQt4.QtGui.QMenu`.

    .. method:: IToolkit.menu_bar()

        Create a menu bar.
        
        :return:
            the menu bar which will be an instance of
            :class:`~PyQt4.QtGui.QMenuBar`.

    .. method:: IToolkit.message_area(factory, parent)

        Create a message area.
        
        :param factory:
            is the factory creating the message area.
        :param parent:
            is the optional parent widget.
        :return:
            the message area which will be an instance of
            :class:`~PyQt4.QtGui.QLabel`.

    .. method:: IToolkit.push_button(factory, attribute_type, parent)

        Create an editor based on a push button.
        
        :param factory:
            is the factory creating the editor.
        :param attribute_type:
            is the attribute type.
        :param parent:
            is the parent widget.
        :return:
            the editor.

    .. method:: IToolkit.question(title, text, parent=None, default_no=True)

        Ask the user a question with a yes or no answer.
        
        :param title:
            is the title, typically used as the title of a dialog.
        :param text:
            is the text of the question.
        :param parent:
            is the optional parent widget.
        :param default_no:
            is ``True`` if the default answer to the question is "no".
        :return:
            ``True`` if the answer was "yes".

    .. method:: IToolkit.radio_buttons(factory, attribute_type, parent)

        Create an editor that implements a set of radio buttons.
        
        :param factory:
            is the factory creating the editor.
        :param attribute_type:
            is the attribute type.
        :param parent:
            is the parent widget.
        :return:
            the editor.

    .. method:: IToolkit.remove_button(factory, parent)

        Create a button to add an item to a collection.
        
        :param factory:
            is the factory creating the button.
        :param parent:
            is the optional parent widget.
        :return:
            the button which will be a :class:`~PyQt4.QtGui.QAbstractButton`.

    .. method:: IToolkit.spin_box(factory, attribute_type, parent)

        Create an editor based on a spin box.
        
        :param factory:
            is the factory creating the editor.
        :param attribute_type:
            is the attribute type.
        :param parent:
            is the parent widget.
        :return:
            the editor.

    .. method:: IToolkit.splitter(factory, items)

        Create a splitter view to contain a number of items.
        
        :param factory:
            is the factory creating the view.
        :param items:
            is a sequence of :class:`~PyQt4.QtGui.QLayout` or
            :class:`~PyQt4.QtGui.QWidget` instances.
        :return:
            the view.

    .. method:: IToolkit.table_widget(factory, attribute_type, parent)

        Create an editor for a table.
        
        :param factory:
            is the factory creating the editor.
        :param attribute_type:
            is the attribute type.
        :param parent:
            is the parent widget.
        :return:
            the editor which will be an instance of
            :class:`~PyQt4.QtGui.QTableWidget`.  The properties will be applied
            to the editor itself.

    .. method:: IToolkit.text_edit(factory, attribute_type, parent)

        Create an editor based on a text editor.
        
        :param factory:
            is the factory creating the editor.
        :param attribute_type:
            is the attribute type.
        :param parent:
            is the parent widget.
        :return:
            the editor.

    .. method:: IToolkit.tool_button(factory, attribute_type, parent)

        Create an editor based on a tool button.
        
        :param factory:
            is the factory creating the editor.
        :param attribute_type:
            is the attribute type.
        :param parent:
            is the parent widget.
        :return:
            the editor.

    .. method:: IToolkit.up_button(factory, parent)

        Create a button to move an item in a collection up.
        
        :param factory:
            is the factory creating the button.
        :param parent:
            is the optional parent widget.
        :return:
            the button which will be a :class:`~PyQt4.QtGui.QAbstractButton`.

    .. method:: IToolkit.v_box(factory, items)

        Create a view to contain a number of items arranged vertically.
        
        :param factory:
            is the factory creating the view.
        :param items:
            is a sequence of :class:`~PyQt4.QtGui.QLayout`,
            :class:`~PyQt4.QtGui.QWidget` and :class:`~dip.ui.Stretch`
            instances.
        :return:
            the view.

    .. method:: IToolkit.warning(title, text, parent=None, detail='')

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

    .. method:: IToolkit.wizard(factory, pages, parent)

        Create a wizard view.
        
        :param factory:
            is the factory creating the view.
        :param pages:
            is the list of wizard pages.
        :param parent:
            is the optional parent widget.
        :return:
            the view.

    .. method:: IToolkit.wizard_page(factory, content, parent)

        Create a wizard page view.
        
        :param factory:
            is the factory creating the view.
        :param content:
            is the content of the view and is either a
            :class:`~PyQt4.QtGui.QLayout` or a :class:`~PyQt4.QtGui.QWidget`.
        :param parent:
            is the optional parent widget.
        :return:
            the view.


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

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

    The IView interface defines the API to be implemented (typically
    using adaptation) by a :class:`~PyQt4.QtGui.QLayout` or
    :class:`~PyQt.QtGui.QWidget` created by a :class:`~dip.ui.ViewFactory`.

    .. attribute:: controller = Instance(dip.ui.IController)

        The controller.

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

        The factory that created this view.

    .. attribute:: toolkit = Instance(IToolkit)

        The toolkit that created this view.

    .. method:: IView.configure()

        Configure the view.  This is called when everything else has been
        set up.


:class:`LayoutFactory`
----------------------
.. class:: LayoutFactory

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

    The LayoutFactory class is the base class for all factories that create
    views that are implemented as :class:`~PyQt4.QtGui.QLayout` instances.

    .. method:: LayoutFactory.create_layout(items, toolkit)

        Create the specific :class:`~PyQt4.QtGui.QLayout` instance.
        
        This must be reimplemented by a sub-class
        
        :param items:
            is a sequence of :class:`~PyQt4.QtGui.QLayout`,
            :class:`~PyQt4.QtGui.QWidget` and :class:`~dip.ui.Stretch`
            instances.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            layout.
        :return:
            the layout.

    .. method:: LayoutFactory.create_view(controller, toolkit, parent)

        Reimplemented to ensure the view is a
        :class:`~PyQt4.QtGui.QWidget`.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.
        :param parent:
            is the optional parent widget.
        :return:
            the :class:`~PyQt4.QtGui.QWidget` that is the root of the view's
            implementation.


:class:`LineEdit`
-----------------
.. class:: LineEdit

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

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

    .. attribute:: required = Enum('meta-data', '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.  'meta-data' means
        that the behavior is determined by any corresponding attribute in the
        meta-data of the model type that the factory is bound to.  '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 'meta-data' is specified,
        but there is no corresponding meta-data then 'no' is assumed.

    .. attribute:: validator = Any()

        The validator which is either a string or a callable.  If it is a string
        then it is assumed to be a Qt regular expression and a
        :class:`~PyQt4.QtGui.QRegExpValidator` is created automatically.
        Otherwise it is called and passed a parent :class:`~PyQt4.QtCore.QObject`
        and should return a :class:`~PyQt4.QtGui.QValidator` instance.

    .. attribute:: view_interface = ILineEditEditor

        The specific interface that the view implements.

    .. method:: LineEdit.create_editor(attribute_type, toolkit, parent)

        Create the editor.
        
        :param attribute_type:
            the type of the attribute the factory is being asked to handle.  It
            should be a :class:`~dip.model.Str`.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.
        :param parent:
            is the optional parent widget.
        :return:
            the editor.


:class:`LinkedViewFactory`
--------------------------
.. class:: LinkedViewFactory

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

    The LinkedViewFactory class is a base class for factories for views
    that are linked to editors and, in some way, supplement the behaviour of
    the editor being linked to.

    .. attribute:: id_suffix = Str()

        The suffix to add to the identifier to distinguish it from other views
        linked to the same editor.

    .. attribute:: linked_to = Str()

        The identifier of the editor that this view is linked to.

    .. method:: LinkedViewFactory.__init__(linked_to, **properties)

        Initialise the factory.
        
        :param linked_to:
            the identifier of the editor that the view is linked to.
        :param \*\*properties:
            are keyword arguments used as property names and values that are
            applied to the view.

    .. method:: LinkedViewFactory.finalize(item)

        This is reimplemented to disable the view created by this factory
        if the linked editor is read-only.
        
        :param item:
            is the view.

    .. method:: LinkedViewFactory.link(view, editor)

        This is normally reimplemented to link the view created by this
        factory to an editor once everything else has been set up.
        
        :param view:
            is the view.
        :param editor:
            is the editor.


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

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

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

    .. attribute:: column_type = Instance(TypeFactory)

        The type of the column.  It is ignored unless a list element is an
        :class:`~dip.model.Any` value.

    .. attribute:: editor_factory = Instance(EditorFactory)

        The factory for the editor created to edit a value in the column.  It
        will default to the editor factory provided by the toolkit for the type
        of the value.


:class:`ListWidget`
-------------------
.. class:: ListWidget

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

    The ListWidget class implements a list widget editor factory for list
    attributes.

    .. attribute:: column = Instance(ListColumn)

        The column.

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

    .. attribute:: view_interface = IListWidgetEditor

        The specific interface that the view implements.

    .. method:: ListWidget.configure_delegate(editor, attribute_type, toolkit)

        Configure the delegate for an editor created by the factory.
        
        :param editor:
            is the editor.
        :param attribute_type:
            is the list's type.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.

    .. method:: ListWidget.configure_widget_item(widget_item, attribute_type)

        Configure a new widget item.
        
        :param widget_item:
            is the widget item, usually a :class:`~PyQt4.QtGui.QListWidgetItem`
            instance.
        :param attribute_type:
            is the list's type.

    .. method:: ListWidget.create_editor(attribute_type, toolkit, parent)

        Create the editor.
        
        :param attribute_type:
            the type of the attribute the factory is being asked to handle.  It
            should be a :class:`~dip.model.List`.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.
        :param parent:
            is the optional parent widget.
        :return:
            the editor.

    .. method:: ListWidget.create_item(attribute_type)

        Create a new item for the list.
        
        :param attribute_type:
            is the list's type.
        :return:
            the new item.


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

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

    The Menu class is a container for a list of actions that is
    implemented as a :class:`~PyQt4.QtGui.QMenu`.

    .. method:: Menu.__init__(collection, **properties)

        Initialise the menu from an action collection.
        
        :param collection:
            is the action collection.
        :param \*\*properties:
            are keyword arguments used as property names and values that are
            applied to a menu.

    .. method:: Menu.__call__(toolkit, *actions, parent=None)

        Create the menu adding any actions that have appropriate
        identifiers.
        
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implmentation used to create the
            menu.
        :param \*actions:
            the list of actions to be added.
        :param parent:
            the optional parent of the menu.
        :return:
            the :class:`~PyQt4.QtGui.QMenu` instance.


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

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

    The MenuBar class is a container for a list of menus that is
    implemented as a :class:`~PyQt4.QtGui.QMenuBar`.

    .. method:: MenuBar.__init__(*menus, **properties)

        Initialise the menu bar.
        
        :param \*menus:
            is the list of menus.  A menu may be an instance of either
            :class:`~dip.ui.Menu` or :class:`~dip.ui.ActionCollection`.
        :param \*\*properties:
            are keyword arguments used as property names and values that are
            applied to a menu bar.

    .. method:: MenuBar.__call__(toolkit, *actions)

        Create the menu bar adding any actions that have appropriate
        identifiers.
        
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            menu bar.
        :param \*actions:
            the list of actions to be added.
        :return:
            the :class:`~PyQt4.QtGui.QMenuBar` instance.


: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:: view_interface = IMessageArea

        The specific interface that the view implements.

    .. method:: MessageArea.bind(view, controller, toolkit)

        Reimplemented to add the message area view to a controller.
        
        :param view:
            is the view.
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.

    .. method:: MessageArea.create_view(controller, toolkit, parent)

        Create the view.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.
        :param parent:
            is the optional parent widget.
        :return:
            the view.


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

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

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

    .. attribute:: extra_metadata_properties = ['icon']

        Extra properties set from the attribute's metadata.

    .. attribute:: view_interface = IPushButtonEditor

        The specific interface that the view implements.

    .. method:: PushButton.create_editor(attribute_type, toolkit, parent)

        Create the editor.
        
        :param attribute_type:
            the type of the attribute the factory is being asked to handle.  It
            should be a :class:`~dip.model.Trigger`.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.
        :param parent:
            is the optional parent widget.
        :return:
            the editor.


:class:`QObjectFactory`
-----------------------
.. class:: QObjectFactory

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

    The QObjectFactory class is the base class for all factories that
    can create a :class:`~PyQt4.QtCore.QObject` whose properties can be
    configured and that support the concept of an identifier.

    .. attribute:: id = Str()

        The identifier of the item that is created.  If it is not specified then
        a sub-class may implement an appropriate default.  The item's object
        name will default to the identifier.

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

        Initialize the item.
        
        :param \*\*properties:
            are keyword arguments used as property names and values that are
            applied to the :class:`~PyQt4.QtCore.QObject` instances created by
            the factory.

    .. method:: QObjectFactory.__call__()

        Create the :class:`~PyQt4.QtCore.QObject` instance.  This should be
        reimplemented by a sub-class
        
        :return:
            the object.

    .. method:: QObjectFactory.configure_properties(item, properties=None)

        Configure an item's properties.
        
        :param item:
            is the item whose properties are being set.
        :param properties:
            is the dictionary of property names and values.  If it is ``None``
            then the properties supplied when the factory was created.

    .. method:: QObjectFactory.finalize(item)

        This is called once all similar items have been created.  This
        default implementation will set the item's object name to the factory's
        identifier if it doesn't already have a name.
        
        :param item:
            is the item that was created by this factory.


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

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

    The RadioButtons class implements a radio buttons editor factory for
    enum attributes.

    .. attribute:: frame = Enum('full', 'flat', 'none')

        The style of any frame.  'full' is a surrounding frame with the label
        embeded.  'flat' is a partial frame with the label embedded.  'none' is
        no frame.

    .. attribute:: orientation = Instance(Qt.Orientation, default=Qt.Vertical)

        The orientation of the radio buttons.

    .. attribute:: view_interface = IRadioButtonsEditor

        The specific interface that the view implements.

    .. method:: RadioButtons.create_editor(attribute_type, toolkit, parent)

        Create the editor.
        
        :param attribute_type:
            the type of the attribute the factory is being asked to handle.  It
            should be an :class:`~dip.model.Enum`.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.
        :param parent:
            is the optional parent widget.
        :return:
            the editor.


:class:`RemoveButton`
---------------------
.. class:: RemoveButton

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

    The RemoveButton class implements a factory for a button for removing
    from a collection editor.

    .. attribute:: id_suffix = '.remove'

        The suffix to add to the identifier to distinguish it from other linked
        views.

    .. method:: RemoveButton.create_view(controller, toolkit, parent)

        Create the view.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.
        :param parent:
            is the optional parent widget.
        :return:
            the view which will be an instance of
            :class:`~PyQt4.QtGui.QAbstractButton`.

    .. method:: RemoveButton.link(view, editor)

        This is reimplemented to link the button view to the collection
        editor.
        
        :param view:
            is the view.
        :param editor:
            is the editor.


:class:`SingleSubviewFactory`
-----------------------------
.. class:: SingleSubviewFactory

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

    The SingleSubviewFactory class is a base class for composite views that
    can only have a single sub-view.

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

        Initialise the view.
        
        :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:: extra_metadata_properties = ['maximum', 'minimum']

        Extra properties set from the attribute's metadata.

    .. attribute:: view_interface = ISpinBoxEditor

        The specific interface that the view implements.

    .. method:: SpinBox.create_editor(attribute_type, toolkit, parent)

        Create the editor.
        
        :param attribute_type:
            the type of the attribute the factory is being asked to handle.  It
            should be an :class:`~dip.model.Int`.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.
        :param parent:
            is the optional parent widget.
        :return:
            the editor.


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

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

    The Splitter class arranges its contents in a splitter. 

    .. method:: Splitter.create_view(controller, toolkit, parent)

        Create a splitter view.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            splitter.
        :param parent:
            is the optional parent widget.
        :return:
            the :class:`~PyQt4.QtGui.QWidget` instance that is the view's
            implementation.


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

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

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

    .. attribute:: stretch = Int(0)

        The stretch factor.


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

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

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

    .. 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 is ignored unless a row is a list of
        :class:`~dip.model.Any` values.

    .. attribute:: editable = Bool(True)

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

    .. attribute:: editor_factory = Instance(EditorFactory)

        The factory for the editor created to edit a value in the column.  It
        will default to the editor factory provided by the toolkit for the type
        of the value.

    .. attribute:: label = Str()

        The label of the column.  It will default to a value derived from the
        name of the attribute that the column is bound to.


:class:`TableWidget`
--------------------
.. class:: TableWidget

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

    The TableWidget class implements a table widget editor factory for list
    attributes.

    .. attribute:: columns = List(Instance(TableColumn, 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:: row_factory = Callable()

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

    .. attribute:: view_interface = ITableWidgetEditor

        The specific interface that the view implements.

    .. method:: TableWidget.configure_delegate(editor, attribute_type, column, column_nr, toolkit)

        Configure the delegate for a column of an editor created by the
        factory.
        
        :param editor:
            is the editor.
        :param attribute_type:
            is the list's type.
        :param column:
            is the :class:`~dip.ui.TableColumn` instance for the column.
        :param column_nr:
            is the number of the column
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.

    .. method:: TableWidget.configure_widget_item(widget_item, attribute_type, column)

        Configure a new widget item.
        
        :param widget_item:
            is the widget item, usually a
            :class:`~PyQt4.QtGui.QTableWidgetItem` instance.
        :param attribute_type:
            is the list's type.

    .. method:: TableWidget.create_editor(attribute_type, toolkit, parent)

        Create the editor.
        
        :param attribute_type:
            the type of the attribute the factory is being asked to handle.  It
            should be a :class:`~dip.model.List`.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.
        :param parent:
            is the optional parent widget.
        :return:
            the editor.

    .. method:: TableWidget.create_row(attribute_type, columns)

        Create a new row for the table.
        
        :param attribute_type:
            is the list's type.
        :param columns:
            is the list of :class:`~dip.ui.TableColumn` instances for the
            columns.
        :return:
            the new row.

    .. method:: TableWidget.table_columns(attribute_type, nr_columns)

        Return the list of :class:`~dip.ui.TableColumn` instances
        describing the columns of the table.
        
        :param attribute_type:
            is the type of the attribute the editor is bound to.
        :param nr_columns:
            is the number of columns that the editor has.  It is 0 if this is
            determined by the value returned by this method.
        :return:
            the list of columns.


:class:`TextEdit`
-----------------
.. class:: TextEdit

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

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

    .. attribute:: view_interface = ITextEditEditor

        The specific interface that the view implements.

    .. method:: TextEdit.create_editor(attribute_type, toolkit, parent)

        Create the editor.
        
        :param attribute_type:
            the type of the attribute the factory is being asked to handle.  It
            should be a :class:`~dip.model.Str`.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.
        :param parent:
            is the optional parent widget.
        :return:
            the editor.


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

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

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

    .. attribute:: extra_metadata_properties = ['icon']

        Extra properties set from the attribute's metadata.

    .. attribute:: view_interface = IToolButtonEditor

        The specific interface that the view implements.

    .. method:: ToolButton.create_editor(attribute_type, toolkit, parent)

        Create the editor.
        
        :param attribute_type:
            the type of the attribute the factory is being asked to handle.  It
            should be a :class:`~dip.model.Trigger`.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            editor.
        :param parent:
            is the optional parent widget.
        :return:
            the editor.


:class:`UpButton`
-----------------
.. class:: UpButton

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

    The UpButton class implements a factory for a button for moving an item
    up a collection editor.

    .. attribute:: id_suffix = '.up'

        The suffix to add to the identifier to distinguish it from other linked
        editors.

    .. method:: UpButton.create_view(controller, toolkit, parent)

        Create the view.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.
        :param parent:
            is the optional parent widget.
        :return:
            the view which will be an instance of
            :class:`~PyQt4.QtGui.QAbstractButton`.

    .. method:: UpButton.link(view, editor)

        This is reimplemented to link the button view to the collection
        editor.
        
        :param view:
            is the view.
        :param editor:
            is the editor.


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

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

    The VBox class arranges its contents vertically. 

    .. method:: VBox.create_layout(items, toolkit)

        Create a layout for a vertical sub-view.
        
        :param items:
            is a sequence of :class:`~PyQt4.QtGui.QLayout`,
            :class:`~PyQt4.QtGui.QWidget` and :class:`~dip.ui.Stretch`
            instances.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            layout.
        :return:
            the layout.


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

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

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

    .. attribute:: view_interface = Subclass(IView, default=IView)

        The specific interface that the view implements.

    .. method:: ViewFactory.__call__(model, toolkit, controller=None, parent=None)

        Create a view for a model.  This will always be a
        :class:`~PyQt4.QtGui.QWidget`.
        
        :param model:
            is the model which is either a :class:`~dip.model.Model` instance
            or a Python mapping object.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.
        :param controller:
            is the optional controller.  If this is ``None`` then
            :meth:`~dip.ui.ViewFactory.create_controller` will be called to
            create one.
        :param parent:
            is the optional parent widget.  It is typically only used for
            dialog based views.
        :return:
            the :class:`~PyQt4.QtGui.QWidget` that is the root of the view's
            implementation.

    .. method:: ViewFactory.bind(view, controller, toolkit)

        Bind a view created by this factory.
        
        :param view:
            is the view.
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.

    .. method:: ViewFactory.create_controller()

        Create an implementation of :class:`~dip.ui.IController`.
        
        :return:
            the controller.

    .. method:: ViewFactory.create_view(controller, toolkit, parent)

        Create the view.
        
        This must be reimplemented by a sub-class.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            view.
        :param parent:
            is the optional parent widget.
        :return:
            the :class:`~PyQt4.QtGui.QLayout` or :class:`~PyQt4.QtGui.QWidget`
            that is the root of the view's implementation.


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

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

    The Wizard class implements a :class:`~PyQt4.QtGui.QWizard` based
    wizard.

    .. method:: Wizard.create_controller()

        Create an implementation of :class:`~dip.ui.IController`.
        
        :return:
            the controller.

    .. method:: Wizard.create_view(controller, toolkit, parent)

        Create the view for a model.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            dialog.
        :param parent:
            is the optional parent widget.
        :return:
            the :class:`~PyQt4.QtGui.QWizard` instance that is the view's
            implementation.


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

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

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

    .. method:: WizardController.validate_page(page_nr)

        Validate the data in a page.  This implementation considers the
        page to be valid if all its editors have valid values.
        
        :param page_nr:
            is the number of the page.  This is the index of the page in the
            wizard and is not the same as the identifier allocated by Qt.
        :return:
            a string which will be empty if the page is valid, otherwise it
            will explain why the page is invalid.

    .. method:: WizardController.validate_view()

        Validate the data in the view.  This implementation considers the
        view to be valid if all its editors have valid values.
        
        :return:
            a string which will be empty if the view is valid, otherwise it
            will explain why the view is invalid.


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

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

    The WizardPage class implements a :class:`~PyQt4.QtGui.QWizardPage`
    based wizard page.

    .. method:: WizardPage.create_view(controller, toolkit, parent)

        Create the view for a model.
        
        :param controller:
            is the controller.
        :param toolkit:
            is the :class:`~dip.ui.IToolkit` implementation used to create the
            dialog.
        :param parent:
            is the optional parent widget.
        :return:
            the :class:`~PyQt4.QtGui.QLayout` or :class:`~PyQt4.QtGui.QWidget`
            that is the root of the view's implementation.
