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

This module contains the implementation of the Qt4 :term:`toolkit`. 


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

    Base class: :class:`~dip.toolkits.BaseToolkit`

    The Toolkit class implements the :term:`toolkit` that uses the Qt4
    GUI library.

    .. attribute:: view_type_to_declarative_factory_map = Tuple()

        A map of declarative factories to view types.

    .. method:: Toolkit.action(parent)

        Create an action.
        
        :param parent:
            is the optional parent view.
        :return:
            the action which will be a :class:`~PyQt4.QtGui.QAction`.

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

        Create a singleton application.
        
        :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:: Toolkit.call_after(callable, after)

        Call a callable after a delay.
        
        :param callable:
            is the callable.
        :param after:
           is the delay in milliseconds.  If it is zero then the callable is
           called in the next iteration of the event loop.

    .. method:: Toolkit.check_box(parent)

        Create an editor based on a check box.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor which will be an instance of
            :class:`~PyQt4.QtGui.QCheckBox`.

    .. method:: Toolkit.close_action()

        Create an action to handle closing an object.
        
        :return:
            the action.

    .. method:: Toolkit.combo_box(parent)

        Create an editor based on a combo box.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor which will be an instance of
            :class:`~PyQt4.QtGui.QComboBox`.

    .. method:: Toolkit.declarative_factory_for_view(view)

        Get an :class:`~dip.ui.EditorFactory` type object that will create
        a factory that creates views of a particular type.
        
        :param view:
            is the view.
        :return:
            the :class:`~dip.ui.EditorFactory` sub-class.

    .. method:: Toolkit.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:: Toolkit.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:: Toolkit.dialog(parent)

        Create a dialog view.
        
        :param parent:
            is the optional parent view.
        :return:
            the view which will be an instance of
            :class:`~PyQt4.QtGui.QDialog`.

    .. method:: Toolkit.displayable(view)

        Return a :term:`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:: Toolkit.dock(parent)

        Create a dock view.
        
        :param parent:
            is the optional parent view.
        :return:
            the view which will be an instance of
            :class:`~PyQt4.QtGui.QDockWidget`.

    .. method:: Toolkit.filesystem_location_editor(parent)

        Create an editor that implements a filesystem file/directory
        location editor.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.  Any factory properties will be applied to an internal
            :class:`~PyQt4.QtGui.QLineEdit`.

    .. method:: Toolkit.find_view(root, id)

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

    .. method:: Toolkit.float_spin_box(parent)

        Create an editor for floats based on a spin box.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor which will be an instance of
            :class:`~PyQt4.QtGui.QDoubleSpinBox`.

    .. method:: Toolkit.form(parent)

        Create a layout to contain a number of items arranged as a form.
        
        :param parent:
            is the optional parent view.
        :return:
            the layout which will be an instance of
            :class:`~PyQt4.QtGui.QFormLayout`.

    .. method:: Toolkit.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:: Toolkit.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:: Toolkit.group_box(parent)

        Create a group box view.
        
        :param parent:
            is the optional parent view.
        :return:
            the view which will be an instance of
            :class:`~PyQt.QtGui.QGroupBox`.

    .. method:: Toolkit.h_box(parent)

        Create a layout to contain a number of items arranged horizontally.
        
        :param parent:
            is the optional parent view.
        :return:
            the layout which will be an instance of
            :class:`~PyQt4.QtGui.QHBoxLayout`.

    .. method:: Toolkit.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:: Toolkit.label(parent)

        Create an editor for displaying a string.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor which will be an instance of
            :class:`~PyQt4.QtGui.QLabel`.

    .. method:: Toolkit.line_editor(parent)

        Create an editor based on a line editor.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor which will be an instance of
            :class:`~PyQt4.QtGui.QLineEdit`.

    .. method:: Toolkit.list_editor(parent)

        Create an editor for a list.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor which will be an instance of
            :class:`~dip.toolkits.qt4.widgets.DipListEditor`.  Any factory
            properties will be applied to an internal
            :class:`~PyQt4.QtGui.QTreeWidget`.

    .. method:: Toolkit.main_window(parent)

        Create a main window view.
        
        :param parent:
            is the optional parent view.
        :return:
            the view which will be an instance of
            :class:`~PyQt4.QtGui.QMainWindow`.

    .. method:: Toolkit.menu(parent)

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

    .. method:: Toolkit.menu_bar(parent)

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

    .. method:: Toolkit.message_area(parent)

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

    .. method:: Toolkit.new_action()

        Create an action to handle creating a new object.
        
        :return:
            the action.

    .. method:: Toolkit.open_action()

        Create an action to handle opening an object.
        
        :return:
            the action.

    .. method:: Toolkit.option_list(parent)

        Create an editor used to select from a sequence of options.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor which will be an instance of
            :class:`~PyQt4.QtGui.QListWidget`.

    .. method:: Toolkit.push_button(parent)

        Create an editor based on a push button.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor which will be an instance of
            :class:`~PyQt4.QtGui.QPushButton`.

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

        Create an action to handle quitting the application.
        
        :return:
            the action.

    .. method:: Toolkit.radio_buttons(parent)

        Create an editor that implements a set of radio buttons.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.  Any factory properties will be applied to each of the
            buttons.

    .. method:: Toolkit.save_action()

        Create an action to handle saving an object.
        
        :return:
            the action.

    .. method:: Toolkit.save_as_action()

        Create an action to handle saving an object under a new name.
        
        :return:
            the action.

    .. method:: Toolkit.spin_box(parent)

        Create an editor based on a spin box.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor which will be an instance of
            :class:`~PyQt4.QtGui.QSpinBox`.

    .. method:: Toolkit.splitter(parent)

        Create a splitter view to contain a number of items.
        
        :param parent:
            is the optional parent view.
        :return:
            the view which will be an instance of
            :class:`~PyQt4.QtGui.QSplitter`.

    .. method:: Toolkit.storage_location_editor(parent)

        Create an editor that implements a storage location editor.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.  Any factory properties will be applied to an internal
            :class:`~PyQt4.QtGui.QLineEdit`.

    .. method:: Toolkit.tab_bar(parent)

        Create a tab bar view.
        
        :param parent:
            is the optional parent view.
        :return:
            the view which will be an instance of
            :class:`~PyQt4.QtGui.QTabWidget`.

    .. method:: Toolkit.table_editor(parent)

        Create an editor for a table.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor which will be an instance of
            :class:`~dip.toolkits.qt4.widgets.DipTableEditor`.  Any factory
            properties will be applied to an internal
            :class:`~PyQt4.QtGui.QTableWidget`.

    .. method:: Toolkit.text_editor(parent)

        Create an editor based on a text editor.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor which will be an instance of
            :class:`~PyQt4.QtGui.QTextEdit`.

    .. method:: Toolkit.tool_button(parent)

        Create an editor based on a tool button.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor which will be an instance of
            :class:`~PyQt4.QtGui.QToolButton`.

    .. method:: Toolkit.v_box(parent)

        Create a layout to contain a number of items arranged vertically.
        
        :param parent:
            is the optional parent view.
        :return:
            the layout which will be an instance of
            :class:`~PyQt4.QtGui.QVBoxLayout`.

    .. method:: Toolkit.view_stack(parent)

        Create a layout to contain a stack of items such that only one is
        visible at a time.
        
        :param parent:
            is the optional parent view.
        :return:
            the layout which will be an instance of
            :class:`~PyQt4.QtGui.QStackedLayout`.

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

        Create an action to handle "What's This?".
        
        :return:
            the action.

    .. method:: Toolkit.wizard(parent)

        Create a wizard view.
        
        :param parent:
            is the optional parent view.
        :return:
            the view which will be an instance of
            :class:`~PyQt4.QtGui.QWizard`.

    .. method:: Toolkit.wizard_page(parent)

        Create a wizard page view.
        
        :param parent:
            is the optional parent view.
        :return:
            the view which will be an instance of
            :class:`~PyQt4.QtGui.QWizardPage`.
