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

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


:class:`QtToolkit`
------------------
.. class:: QtToolkit

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

    The QtToolkit class implements the :term:`toolkit` that uses the Qt
    GUI library.

    .. attribute:: add_icon = Instance(QIcon)

        The icon used to add an item to a collection.

    .. attribute:: browse_icon = Instance(QIcon)

        The icon used to open a dialog to browse the file system.

    .. attribute:: down_icon = Instance(QIcon)

        The icon used to move an item down in a collection.

    .. attribute:: remove_icon = Instance(QIcon)

        The icon used to remove an item from a collection.

    .. attribute:: up_icon = Instance(QIcon)

        The icon used to move an item up in a collection.

    .. method:: QtToolkit.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:: QtToolkit.browse_button()

        Create a button to initiate browsing the file system.
        
        :return:
            the button which will be a :class:`~PyQt4.QtGui.QAbstractButton`.

    .. method:: QtToolkit.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 which will be an instance of
            :class:`~PyQt4.QtGui.QCheckBox`.  Any factory properties will be
            applied to the check box.

    .. method:: QtToolkit.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 which will be an instance of
            :class:`~PyQt4.QtGui.QComboBox`.  Any factory properties will be
            applied to the combo box.

    .. method:: QtToolkit.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 which will be an instance of
            :class:`~PyQt4.QtGui.QDialog`.

    .. method:: QtToolkit.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:: QtToolkit.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:: QtToolkit.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.  Any factory properties will be applied to an internal
            :class:`~PyQt4.QtGui.QLineEdit`.

    .. method:: QtToolkit.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 which will be an instance of
            :class:`~PyQt4.QtGui.QDoubleSpinBox`.  Any factory properties will
            be applied to the spin box.

    .. method:: QtToolkit.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 which will be an instance of
            :class:`~PyQt4.QtGui.QFormLayout`.

    .. method:: QtToolkit.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:: QtToolkit.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:: QtToolkit.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:: QtToolkit.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:: QtToolkit.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:: QtToolkit.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 which will be an instance of
            :class:`~PyQt4.QtGui.QHBoxLayout`.

    .. method:: QtToolkit.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:: QtToolkit.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 which will be an instance of
            :class:`~PyQt4.QtGui.QLineEdit`.  Any factory properties will be
            applied to the line editor.

    .. method:: QtToolkit.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 which will be an instance of
            :class:`~PyQt4.QtGui.QListWidget`.

    .. method:: QtToolkit.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:: QtToolkit.menu_bar()

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

    .. method:: QtToolkit.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:: QtToolkit.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 which will be an instance of
            :class:`~PyQt4.QtGui.QPushButton`.  Any factory properties will be
            applied to the button.

    .. method:: QtToolkit.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:: QtToolkit.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.  Any factory properties will be applied to each of the
            buttons.

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

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

    .. method:: QtToolkit.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 which will be an instance of
            :class:`~PyQt4.QtGui.QSpinBox`.  Any factory properties will be
            applied to the spin box.

    .. method:: QtToolkit.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 which will be an instance of
            :class:`~PyQt4.QtGui.QSplitter`.

    .. method:: QtToolkit.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`.

    .. method:: QtToolkit.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 which will be an instance of
            :class:`~PyQt4.QtGui.QTextEdit`.  Any factory properties will be
            applied to the text editor.

    .. method:: QtToolkit.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 which will be an instance of
            :class:`~PyQt4.QtGui.QToolButton`.  Any factory properties will be
            applied to the button.

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

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

    .. method:: QtToolkit.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 which will be an instance of
            :class:`~PyQt4.QtGui.QVBoxLayout`.

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