:mod:`dip.shell.shells.qmainwindow`
===================================
.. module:: dip.shell.shells.qmainwindow

This module contains the implementation of the QMainWindow based user
interface shell.


:class:`QMainWindowShell`
-------------------------
.. class:: QMainWindowShell

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

    The QMainWindowShell class is an implementation of a user interface
    shell using :class:`~PyQt4.QtGui.QMainWindow`.  It places tools in the
    central widget according to the
    :attr:`~dip.shell.shells.qmainwindow.QMainWindowShell.tab_policy` and
    unmanaged tools in dock widgets.

    .. attribute:: id = 'dip.shell'

        The shell's identifier.

    .. attribute:: menu_bar = Instance(QMenuBar)

        The :class:`~PyQt4.QtGui.QMenuBar` that is added to the
        :class:`~PyQt4.QtGui.QMainWindow`.  If it is ``None`` then no menu bar is
        added.

    .. attribute:: menus = List()

        The list of menus to be added to the menu bar, typically by using
        :class:`~dip.ui.MenuBar`.

    .. attribute:: tab_policy = Enum('on_demand', 'always', 'never')

        This specifies when tabs should be used.  ``'on_demand'`` means that tabs
        are displayed when there is more than one tool.  ``'always'`` means that
        tabs are always displayed, even when there is only one tool.
        ``'never'`` means that tabs are never displayed and only one tool can be
        used at a time.

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

        Initialize the QMainWindow shell. 

    .. method:: QMainWindowShell.add_tool(tool)

        Add a :term:`tool` to the shell.
        
        :param tool:
            is the tool to add.

    .. method:: QMainWindowShell.perform_close(tool)

        Close a tool asking the user for help where necessary.
        
        :param tool:
            is the tool to close.

    .. method:: QMainWindowShell.perform_new()

        Create a tool for a new shell object asking the user for help where
        necessary.

    .. method:: QMainWindowShell.perform_open()

        Create a tool for a shell object read from storage asking the user
        for help where necessary.

    .. method:: QMainWindowShell.perform_quit()

        Confirm that the user wants to quit given the state of any shell
        objects.

    .. method:: QMainWindowShell.perform_save(tool)

        Write a shell object to storage at its current location asking the
        user for help where necessary.
        
        :param tool:
            is the tool operating on the shell object to write.

    .. method:: QMainWindowShell.perform_save_as(tool)

        Write a shell object to storage at a new location asking the user
        for help where necessary.
        
        :param tool:
            is the tool operating on the shell object to write.
