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

    .. method:: Toolkit.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.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QAction`.

    .. method:: Toolkit.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.
            The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QApplication`.

    .. method:: Toolkit.check_box(parent)

        Create an editor that implements the :class:`~dip.ui.ICheckBox`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QCheckBox`.

    .. method:: Toolkit.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.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QAction`.

    .. method:: Toolkit.combo_box(parent)

        Create an editor that implements the :class:`~dip.ui.IComboBox`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QComboBox`.

    .. 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 view that implements the :class:`~dip.ui.IDialog`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapated object will be an instance of
            :class:`~PyQt4.QtGui.QDialog`.

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

        Create a view that implements the :class:`~dip.ui.IDock` interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QDockWidget`.

    .. method:: Toolkit.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.  The unadapted object will be an instance of
            :class:`~dip.toolkits.qt4.widgets.DipFilesystemLocationEditor`.
            Any factory properties will be applied to an internal
            :class:`~PyQt4.QtGui.QLineEdit`.

    .. method:: Toolkit.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:: Toolkit.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.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QDoubleSpinBox`.

    .. method:: Toolkit.form(parent)

        Create a view that implements the :class:`~dip.ui.IForm` interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapted object 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.grid(parent)

        Create a view that implements the :class:`~dip.ui.IGrid` interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QGridLayout`.

    .. method:: Toolkit.group_box(parent)

        Create a view that implements the :class:`~dip.ui.IGroupBox`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapted object will be an instance of
            :class:`~PyQt.QtGui.QGroupBox`.

    .. method:: Toolkit.h_box(parent)

        Create a view that implements the :class:`~dip.ui.IHBox` interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapted object 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 that implements the :class:`~dip.ui.ILabel`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QLabel`.

    .. method:: Toolkit.line_editor(parent)

        Create an editor that implements the :class:`~dip.ui.ILineEditor`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QLineEdit`.

    .. method:: Toolkit.list_editor(parent)

        Create an editor that implements the :class:`~dip.ui.IListEditor`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.  The unadapted object 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 view that implements the :class:`~dip.ui.IMainWindow`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QMainWindow`.

    .. method:: Toolkit.menu(parent)

        Create a view that implements the :class:`~dip.ui.IMenu` interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QMenu`.

    .. method:: Toolkit.menu_bar(parent)

        Create a view that implements the :class:`~dip.ui.IMenuBar`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QMenuBar`.

    .. method:: Toolkit.message_area(parent)

        Create a view that implements the :class:`~dip.ui.IMessageArea`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QLabel`.

    .. method:: Toolkit.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.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QAction`.

    .. method:: Toolkit.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.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QAction`.

    .. method:: Toolkit.option_list(parent)

        Create an editor that implements the :class:`~dip.ui.IOptionList`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QListWidget`.

    .. method:: Toolkit.push_button(parent)

        Create an that implements the :class:`~dip.ui.IPushButton`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.  The unadapted object 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, i.e. an object that implements the
        :class:`~dip.ui.IAction` interface, to handle quitting the application.
        
        :return:
            the action.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QAction`.

    .. method:: Toolkit.radio_buttons(parent)

        Create an editor that implements the :class:`~dip.ui.IRadioButtons`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.  The unadapted object will be an instance of
            :class:`~dip.toolkits.qt4.widgets.DipRadioButtons`.  Any factory
            properties will be applied to each of the buttons.

    .. method:: Toolkit.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.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QAction`.

    .. method:: Toolkit.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.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QAction`.

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

        Create an editor that implements the :class:`~dip.ui.ISpinBox`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QSpinBox`.

    .. method:: Toolkit.splitter(parent)

        Create a view that implements the :class:`~dip.ui.ISplitter`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QSplitter`.

    .. method:: Toolkit.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.  The unadapted object will be an instance of
            :class:`~dip.toolkits.qt4.widgets.DipStorageLocationEditor`.  Any
            factory properties will be applied to an internal
            :class:`~PyQt4.QtGui.QLineEdit`.

    .. method:: Toolkit.tab_bar(parent)

        Create a view that implements the :class:`~dip.ui.ITabBar`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QTabWidget`.

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

        Create an editor that implements the :class:`~dip.ui.ITableEditor`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.  The unadapted object 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 that implements the :class:`~dip.ui.ITextEditor`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QTextEdit`.

    .. method:: Toolkit.tool_button(parent)

        Create an editor that implements the :class:`~dip.ui.IToolButton`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the editor.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QToolButton`.

    .. method:: Toolkit.v_box(parent)

        Create a view that implements the :class:`~dip.ui.IVBox` interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QVBoxLayout`.

    .. method:: Toolkit.view_stack(parent)

        Create a view that implements the :class:`~dip.ui.IViewStack`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapted object 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, i.e. an object that implements the
        :class:`~dip.ui.IAction` interface, to handle "What's This?".
        
        :return:
            the action.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QAction`.

    .. method:: Toolkit.wizard(parent)

        Create a view that implements the :class:`~dip.ui.IWizard`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QWizard`.

    .. method:: Toolkit.wizard_page(parent)

        Create a view that implements the :class:`~dip.ui.IWizardPage`
        interface.
        
        :param parent:
            is the optional parent view.
        :return:
            the view.  The unadapted object will be an instance of
            :class:`~PyQt4.QtGui.QWizardPage`.
