================
Action (hwx.gui)
================

GUI command used in Menus and ToolBars.

An action contains text, icons and a command callback.
The action can be inserted into menus and/or toolbars.
When the menu or toolbar button is clicked the action is called.
Actions are used in Tool Wheel. The text displayed in the Tool Wheel is
based on the text attribute which should be passed to tr() before.

Actions are modeled after Qts Action class. Refer to the Qt documentation
for more information.

----------
Properties
----------

  +-------------+-------------+-------------+
  | accel_      | command_    | enabled_    |
  +-------------+-------------+-------------+
  | exclusive_  | icon_       | ison_       |
  +-------------+-------------+-------------+
  | name_       | selectable_ | statustip_  |
  +-------------+-------------+-------------+
  | text_       | tooltip_    | visible_    |
  +-------------+-------------+-------------+
  | whatsthis_  |                           |
  +-------------+---------------------------+

--------------
Public Methods
--------------

  +------------------------------+
  | classmethod get_ (cls, name) |
  +------------------------------+
  | onCommand_ (self)            |
  +------------------------------+
  | onToggle_ (self, on)         |
  +------------------------------+

----------------
Property Details
----------------

.. _accel:
.. method:: accel

Key sequence to activate/toggle this action, like "Ctrl+q".
    

.. _command:
.. method:: command

Method called when the action button is clicked.
    

.. _enabled:
.. method:: enabled

The availability of the action.

Disabled actions are grayed out and the user cannot activate them.

.. _exclusive:
.. method:: exclusive

The group exclusive property.

- If this action is contained in a group and the group exclusive property
  is True, this action would toggle off when any other action in the group
  is toggled on.
- Setting to False makes the actions toggle independently.
- Setting to True simple does not do anything if the group is not set 
  as exclusive.

.. _icon:
.. method:: icon

File name of the icon.

- Local names are looked up from the paths specified in addResourcePath.
- When setting the icon the value can be a tuple of (icon, position)
  where position is the x,y translation of the icon.

.. _ison:
.. method:: ison

Determines if the action is on or not.
    

.. _name:
.. method:: name

Unique identifier across profiles.

This is only settable in the constructor.

.. _selectable:
.. method:: selectable

The ability to select the action.

Setting to False allows for creating a background icon.

.. _statustip:
.. method:: statustip

Text displayed in the status bar when the cursor is over the icon or text.
    

.. _text:
.. method:: text

Text label displayed in the menu/toolbar.
    

.. _tooltip:
.. method:: tooltip

Text displayed in a popup when cursor is over the icon or text.
    

.. _visible:
.. method:: visible

The visibility of the action.

Setting to False will visually remove this from the menu/toolbar.

.. _whatsthis:
.. method:: whatsthis

Text displayed when cursor is over the icon or text and user hits F1.
    

--------------
Method Details
--------------

.. _get:
.. classmethod:: get(cls, name)

Returns the named action from defined in active profile.

:param name: Action name.
:type name: str


.. _onCommand:
.. method:: onCommand(self)

Calls command callback method when an Action is clicked.

.. _onToggle:
.. method:: onToggle(self, on)

Acts when an Action is toggled.

- If is coupled to dialog it will show or hide the dialog.
- If is coupled to a context it will get in and out the context.
- If is coupled to callback it will run the callback with state or not.

:param on: Determines whether to toggle on or off.
:type on: bool