===================
PopupMenu (hwx.gui)
===================

A PopupMenu Widget.

The PopupMenu is a specialized control that has the abilty of being selected.
You can add items and commands to the popup menu.

Inherits:
  - :ref:`Widget (hwx.gui)`

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

  +-------------+
  | numOfItems_ |
  +-------------+

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

  +------------------------------------------------------------------------------------------------------------------------------------------+
  | addChildren_ (self, children)                                                                                                            |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | clear_ (self)                                                                                                                            |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | destroy_ (self)                                                                                                                          |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | enableGlobalActions_ (self, enable)                                                                                                      |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | getMousePosition_ (self)                                                                                                                 |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | getRelativeMousePosition_ (self)                                                                                                         |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | hide_ (self)                                                                                                                             |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | insertItem_ (self, text, menu=None, icon=None, command=None, enabled=True, visible=True, accel=None, checked=None, advancedTooltip=None) |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | insertMenu_ (self, text)                                                                                                                 |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | insertSeparator_ (self)                                                                                                                  |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | insertWidget_ (self, widget)                                                                                                             |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | popup_ (self, event=None)                                                                                                                |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | saveAsPng_ (self, fname)                                                                                                                 |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | setF1HelpTopic_ (self, helptopic)                                                                                                        |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | setItemEnabled_ (self, index, enabled=True)                                                                                              |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | setProperties_ (self, kwds)                                                                                                              |
  +------------------------------------------------------------------------------------------------------------------------------------------+
  | show_ (self)                                                                                                                             |
  +------------------------------------------------------------------------------------------------------------------------------------------+

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

.. _numOfItems:
.. property:: numOfItems

Returns the number of items in the popup menu.

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

.. _addChildren:
.. method:: addChildren(self, children)

Add child widgets/layouts into this widget.

Widget children get layed out using a VBoxLayout.

Typically, you'll pass the parent/children into the constructor instead of
calling this function directly.

:param children:
:type children: list[Widget] | Layout


.. _clear:
.. method:: clear(self)

Remove all items.

.. _destroy:
.. method:: destroy(self)

Deletes this and all its children.

.. _enableGlobalActions:
.. method:: enableGlobalActions(self, enable)

Sets the state of Global Actions.

Disable the global actions to get key events.

:param enable: Determines whether to enable or disable global actions.
:type enable: bool


.. _getMousePosition:
.. method:: getMousePosition(self)

Returns the mouse position.

.. _getRelativeMousePosition:
.. method:: getRelativeMousePosition(self)

Returns the mouse position relative to this widget.

.. _hide:
.. method:: hide(self)

Hides the widget.

.. _insertItem:
.. method:: insertItem(self, text, menu=None, icon=None, command=None, enabled=True, visible=True, accel=None, checked=None, advancedTooltip=None)

Inserts item and command into menu.

:param text: The item text to be displayed.
:type text: str
:param menu: The menu object to insert.
:type menu: PopupMenu
:param icon: The icon file to be inserted on the left side of text.
:type icon: str
:param command: The callback method to be executed when item is clicked.
:type command: callback
:param enabled: Determines whether to enable the inserted item.
:type enabled: bool
:param visible: Determines whether the inserted item is visible.
:type visible: bool
:param accel: Keyboard accelerator to execute the command (e.g. 'Del')
:type accel: str
:param checked: Determines if the item is checkable.
             True or False makes it checkable.
:type checked: bool
:param advancedTooltip: UUID to display advanced tooltips.
:type advancedTooltip: str

:returns: The index where the item has been inserted.
:rtype: int


.. _insertMenu:
.. method:: insertMenu(self, text)

Adds and returns a cascading menu.

.. _insertSeparator:
.. method:: insertSeparator(self)

Inserts a separator in the Pop menu.

.. _insertWidget:
.. method:: insertWidget(self, widget)

Inserts a widget into the menu

.. _popup:
.. method:: popup(self, event=None)

Shows the Popup menu.

:param event: The event to get the mouse position.
:type event: MouseEvent


.. _saveAsPng:
.. method:: saveAsPng(self, fname)

Saves the widget as a .png file.

:param fname: The file name for the .png
:type fname: str

:returns: True if it was saved succesfully, False otherwise.
:rtype: bool


.. _setF1HelpTopic:
.. method:: setF1HelpTopic(self, helptopic)

Popup web-browser helps when the user hits F1 when over this.

:param helptopic: Topic name user needs help in.
:type helptopic: str


.. _setItemEnabled:
.. method:: setItemEnabled(self, index, enabled=True)

Enables or Disables the menu item at the specified index.

.. _setProperties:
.. method:: setProperties(self, kwds)

Internal method called from constructors.

.. _show:
.. method:: show(self)

Shows the widget.