:mod:`dip.shell.actions`
========================
.. module:: dip.shell.actions

The :mod:`dip.shell.actions` module provides support for
:term:`actions<action>` including standard actions for managing the lifecycle
of a :term:`shell object`.


:class:`CloseAction`
--------------------
.. class:: CloseAction

    Base class: :class:`~dip.shell.actions.ShellAction`

    The CloseAction class is a shell action that invokes the
    :meth:`~dip.shell.IShell.perform_close` method.

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

        The identifier of the action.

    .. attribute:: text = '&Close'

        The action's text.

    .. attribute:: shortcut = QKeySequence.Close

        The action's shortcut.

    .. attribute:: visible = False

        This is set if the action is visible.

    .. method:: CloseAction.perform(tool)

        Perform the action.
        
        :param tool:
            is the tool.


:class:`NewAction`
------------------
.. class:: NewAction

    Base class: :class:`~dip.shell.actions.ShellAction`

    The NewAction class is a shell action that invokes the
    :meth:`~dip.shell.IShell.perform_new` method.

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

        The identifier of the action.

    .. attribute:: text = '&New'

        The action's text.

    .. attribute:: shortcut = QKeySequence.New

        The action's shortcut.

    .. attribute:: needs_tool = False

        The action does not require an active tool.

    .. attribute:: visible = False

        This is set if the action is visible.

    .. method:: NewAction.perform(tool)

        Perform the action.
        
        :param tool:
            is the tool.


:class:`OpenAction`
-------------------
.. class:: OpenAction

    Base class: :class:`~dip.shell.actions.ShellAction`

    The OpenAction class is a shell action that invokes the
    :meth:`~dip.shell.IShell.perform_open` method.

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

        The identifier of the action.

    .. attribute:: text = '&Open...'

        The action's text.

    .. attribute:: shortcut = QKeySequence.Open

        The action's shortcut.

    .. attribute:: needs_tool = False

        The action does not require an active tool.

    .. attribute:: visible = False

        This is set if the action is visible.

    .. method:: OpenAction.perform(tool)

        Perform the action.
        
        :param tool:
            is the tool.


:class:`QuitAction`
-------------------
.. class:: QuitAction

    Base class: :class:`~dip.shell.actions.ShellAction`

    The QuitAction class is a shell action that invokes the
    :meth:`~dip.shell.IShell.perform_quit` method.

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

        The identifier of the action.

    .. attribute:: text = '&Quit'

        The action's text.

    .. attribute:: shortcut = QKeySequence.Quit

        The action's shortcut.

    .. attribute:: needs_tool = False

        The action does not require an active tool.

    .. method:: QuitAction.perform(tool)

        Perform the action.
        
        :param tool:
            is the tool.


:class:`SaveAction`
-------------------
.. class:: SaveAction

    Base class: :class:`~dip.shell.actions.ShellAction`

    The SaveAction class is a shell action that invokes the
    :meth:`~dip.shell.IShell.perform_save` method.

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

        The identifier of the action.

    .. attribute:: text = '&Save'

        The action's text.

    .. attribute:: shortcut = QKeySequence.Save

        The action's shortcut.

    .. attribute:: visible = False

        This is set if the action is visible.

    .. method:: SaveAction.perform(tool)

        Perform the action.
        
        :param tool:
            is the tool.


:class:`SaveAsAction`
---------------------
.. class:: SaveAsAction

    Base class: :class:`~dip.shell.actions.ShellAction`

    The SaveAsAction class is a shell action that invokes the
    :meth:`~dip.shell.IShell.perform_save_as` method.

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

        The identifier of the action.

    .. attribute:: text = 'Save &As...'

        The action's text.

    .. attribute:: shortcut = QKeySequence.SaveAs

        The action's shortcut.

    .. attribute:: visible = False

        This is set if the action is visible.

    .. method:: SaveAsAction.perform(tool)

        Perform the action.
        
        :param tool:
            is the tool.


:class:`ShellAction`
--------------------
.. class:: ShellAction

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

    The ShellAction class is an :term:`action` intended to be used by a
    :term:`shell`.  The action can automatically disable and enable itself
    depending on the shell's current active tool.  The class has been designed
    so that it doesn't normally need to be sub-classed.

    .. method:: ShellAction.perform(tool)

        Perform the action (probably) on a tool.  This will not be called
        if :meth:`~dip.shell.IShellAction.validate` returns ``False``.
        
        :param tool:
            is the tool.

    .. method:: ShellAction.validate(tool)

        Check if the action can be performed on a tool.
        
        :param tool:
            is the tool.
        :return:
            ``True`` if the action can be performed.


:class:`WhatsThisAction`
------------------------
.. class:: WhatsThisAction

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

    The WhatsThisAction class is an action that can be contributed to the
    'dip.shell.actions' extension point to invoke "What's This?" help.

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

        The identifier of the action.
