:mod:`dip.toolkits`
===================
.. module:: dip.toolkits

The :mod:`dip.toolkits` module contains the :term:`toolkits<toolkit>`
included with dip.  The default toolkit uses :mod:`PyQt4`.


: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:: attribute_type_to_declarative_factory_map = Tuple()

        A map of declarative factories to attribute types.

    .. attribute:: attribute_type_to_editor_factory_map = Tuple()

        A map of editor factories to attribute types.

    .. method:: BaseToolkit.declarative_factory_for_attribute_type(attribute_type)

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

    .. method:: BaseToolkit.editor_factory_for_attribute_type(attribute_type)

        Get a callable that will create a editor to handle attributes of a
        particular type.
        
        :param attribute_type:
            is the type of the attribute.
        :return:
            the callable.


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

        Create an action, i.e. an object that implements the
        :class:`~dip.ui.IAction` interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the action.

    .. method:: IToolkit.application(argv, **properties)

        Create a singleton application, i.e. an object that implements the
        :class:`~dip.ui.IApplication` interface.
        
        :param argv:
            is the sequence of command line arguments.
        :param \*\*properties:
            are the keyword arguments used as toolkit specific property names
            and values that are used to configure the application.
        :return:
            the application.  Repeated calls must return the same application.

    .. method:: IToolkit.check_box(parent)

        Create an editor that implements the :class:`~dip.ui.ICheckBox`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.

    .. method:: IToolkit.close_action()

        Create an action, i.e. an object that implements the
        :class:`~dip.ui.IAction` interface, to handle closing an object.
        
        :return:
            the action.

    .. method:: IToolkit.combo_box(parent)

        Create an editor that implements the :class:`~dip.ui.IComboBox`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.

    .. method:: IToolkit.declarative_factory_for_attribute_type(attribute_type)

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

    .. method:: IToolkit.designer_load(ui_file_name)

        Load a file containing a user interface design.
        
        :param ui_file_name:
            is the name of the file.
        :return:
            an opaque object that will be passed to
            :meth:`~dip.toolkits.IToolkit.designer_view`.

    .. method:: IToolkit.designer_view(design, parent)

        Create a view from a previously loaded user interface design.
        
        :param design:
            is an opaque object returned by a previous call to
            :meth:`~dip.toolkits.IToolkit.designer_load`.
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: IToolkit.dialog(parent)

        Create a view that implements the :class:`~dip.ui.IDialog`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: IToolkit.displayable(view)

        Return a view that can be displayed as a top-level window.
        
        :param view:
            is the view to be displayed.
        :return:
            the view, possibly wrapped so that it can be displayed.

    .. method:: IToolkit.dock(parent)

        Create a view that implements the :class:`~dip.ui.IDock` interface..
        
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: IToolkit.editor_factory_for_attribute_type(attribute_type)

        Get a callable that will create a editor to handle attributes of a
        particular type.
        
        :param attribute_type:
            is the type of the attribute.
        :return:
            the callable.

    .. method:: IToolkit.filesystem_location_editor(parent)

        Create an editor that implements the
        :class:`~dip.ui.IFilesystemLocationEditor` interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.

    .. method:: IToolkit.find_toolkit_view(toolkit_root, id)

        Find the toolkit view with a particular identifier.
        
        :param toolkit_root:
            is the root toolkit view to begin the search.
        :param id:
            is the identifier of the view to search for.
        :return:
            the toolkit view.  An exception will be raised if the view could
            not be found.

    .. method:: IToolkit.float_spin_box(parent)

        Create an editor that implements the :class:`~dip.ui.IFloatSpinBox`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.

    .. method:: IToolkit.form(parent)

        Create a view that implements the :class:`~dip.ui.IForm` interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.

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

        Get the name of a file to open from the user.
        
        :param window_title:
            is the window title, typically used as the title of a dialog.
        :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 view.
        :return:
            the name of the file to open or an empty string if there was none.

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

        Get the name of a file to save from the user.
        
        :param window_title:
            is the window title, typically used as the title of a dialog.
        :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 view.
        :return:
            the name of the file to save or an empty string if there was none.

    .. method:: IToolkit.grid(parent)

        Create a view that implements the :class:`~dip.ui.IGrid` interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: IToolkit.group_box(parent)

        Create a view that implements the :class:`~dip.ui.IGroupBox`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: IToolkit.h_box(parent)

        Create a view that implements the :class:`~dip.ui.IHBox` interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: IToolkit.information(window_title, text, parent)

        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.

    .. method:: IToolkit.label(parent)

        Create an editor that implements the :class:`~dip.ui.ILabel`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.

    .. method:: IToolkit.line_editor(parent)

        Create an editor that implements the :class:`~dip.ui.ILineEditor`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.

    .. method:: IToolkit.list_editor(parent)

        Create an editor that implements the :class:`~dip.ui.IListEditor`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.

    .. method:: IToolkit.main_window(parent)

        Create a view that implements the :class:`~dip.ui.IMainWindow`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: IToolkit.menu(parent)

        Create a view that implements the :class:`~dip.ui.IMenu` interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: IToolkit.menu_bar(parent)

        Create a view that implements the :class:`~dip.ui.IMenuBar`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: IToolkit.message_area(parent)

        Create a view that implements the :class:`~dip.ui.IMessageArea`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: IToolkit.new_action()

        Create an action, i.e. an object that implements the
        :class:`~dip.ui.IAction` interface, to handle creating a new object.
        
        :return:
            the action.

    .. method:: IToolkit.open_action()

        Create an action, i.e. an object that implements the
        :class:`~dip.ui.IAction` interface, to handle opening an object.
        
        :return:
            the action.

    .. method:: IToolkit.option_list(parent)

        Create an editor that implements the :class:`~dip.ui.IOptionList`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.

    .. method:: IToolkit.push_button(parent)

        Create an editor that implements the :class:`~dip.ui.IPushButton`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.

    .. method:: IToolkit.question(window_title, text, parent, detail, buttons)

        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.

    .. method:: IToolkit.quit_action()

        Create an action, i.e. an object that implements the
        :class:`~dip.ui.IAction` interface, to handle quitting the application.
        
        :return:
            the action.

    .. method:: IToolkit.radio_buttons(parent)

        Create an editor that implements the :class:`~dip.ui.IRadioButtons`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.

    .. method:: IToolkit.save_action()

        Create an action, i.e. an object that implements the
        :class:`~dip.ui.IAction` interface, to handle saving an object.
        
        :return:
            the action.

    .. method:: IToolkit.save_as_action()

        Create an action, i.e. an object that implements the
        :class:`~dip.ui.IAction` interface, to handle saving an object under a
        new name.
        
        :return:
            the action.

    .. method:: IToolkit.settings(organization, application)

        Create a settings object, i.e. an object that implements the
        :class:`~dip.settings.ISettingsStorage` interface.
        
        :param organization:
            the name of the organization.
        :param application:
            the name of the application.
        :return:
            the settings object.

    .. method:: IToolkit.spin_box(parent)

        Create an editor that implements the :class:`~dip.ui.ISpinBox`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.

    .. method:: IToolkit.splitter(parent)

        Create a view that implements the :class:`~dip.ui.ISplitter`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: IToolkit.storage_location_editor(parent)

        Create an editor that implements the
        :class:`~dip.ui.IStorageLocationEditor` interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.

    .. method:: IToolkit.tab_bar(parent)

        Create a view that implements the :class:`~dip.ui.ITabBar`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: IToolkit.tab_page(parent)

        Create a view that implements the :class:`~dip.ui.ITabPage`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: IToolkit.table_editor(parent)

        Create an editor that implements the :class:`~dip.ui.ITableEditor`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.

    .. method:: IToolkit.text_editor(parent)

        Create an editor that implements the :class:`~dip.ui.ITextEditor`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.

    .. method:: IToolkit.tool_button(parent)

        Create an editor that implements the :class:`~dip.ui.IToolButton`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.

    .. method:: IToolkit.v_box(parent)

        Create a view that implements the :class:`~dip.ui.IVBox` interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the layout.

    .. method:: IToolkit.view_stack(parent)

        Create a view that implements the :class:`~dip.ui.IViewStack`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the layout.

    .. method:: IToolkit.warning(window_title, text, parent, 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.

    .. method:: IToolkit.whats_this_action()

        Create an action, i.e. an object that implements the
        :class:`~dip.ui.IAction` interface, to handle "What's This?".
        
        :return:
            the action.

    .. method:: IToolkit.wizard(parent)

        Create a view that implements the :class:`~dip.ui.IWizard`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.

    .. method:: IToolkit.wizard_page(parent)

        Create a view that implements the :class:`~dip.ui.IWizardPage`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.


:class:`Toolkit`
----------------
.. class:: Toolkit

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

    The Toolkit class is a singleton that provides access to a default
    :term:`toolkit`.

    .. attribute:: instance = Instance(IToolkit)

        The toolkit instance.