# 27. `gui.menu` — Menus for the pyFormex GUI.

This modules implements specialized classes and functions for building the pyFormex GUI menu system.

## 27.1. Classes defined in module gui.menu

class `gui.menu.``BaseMenu`(title='AMenu', parent=None, before=None, items=None)

  A general menu class.

  A hierarchical menu that keeps a list of its item names and actions. The item names are normalized by removing all ‘&’ characters and converting the result to lower case. It thus becomes easy to search for an existing item in a menu.

  This class is not intended for direct use, but through subclasses. Subclasses should implement at least the following methods:

  - addSeparator()
  - insertSeperator(before)
  - addAction(text,action)
  - insertAction(before,text,action)
  - addMenu(text,menu)
  - insertMenu(before,text,menu)

  QtWidgets.Menu and QtWidgets.MenuBar provide these methods.

  `actionList`()

    Return a list with the current actions.

  `actionsLike`(clas)

    Return a list with the current actions of given class.

  `subMenus`()

    Return a list with the submenus

  `index`(text)

    Return the index of the specified item in the actionlist.

    If the requested item is not in the actionlist, -1 is returned.

  `action`(text)

    Return the action with specified text.

    First, a normal action is tried. If none is found, a separator is tried.

    See also `item()`.

  `item`(text)

    Return the item with specified text.

    For a normal action or a separator, an action is returned. For a menu action, a menu is returned.

  `nextitem`(text)

    Returns the name of the next item.

    This can be used to replace the current item with another menu. If the item is the last, None is returned.

  `removeItem`(item)

    Remove an item from this menu.

  `insert_sep`(before=None)

    Create and insert a separator

  `insert_menu`(menu, before=None)

    Insert an existing menu.

  `insert_action`(action, before=None)

    Insert an action.

  `create_insert_action`(name, val, before=None)

    Create and insert an action.

  `insertItems`(items, before=None, debug=False)

    Insert a list of items in the menu.

    Parameters:

    - items: a list of menuitem tuples. Each item is a tuple of two or three elements: (text, action, options):
      - text: the text that will be displayed in the menu item. It is stored in a normalized way: all lower case and with ‘&’ removed.
      - action: can be any of the following:
        - a Python function or instance method : it will be called when the item is selected,
        - a string with the name of a function/method,
        - a list of Menu Items: a popup Menu will be created that will appear when the item is selected,
        - an existing Menu,
        - None : this will create a separator item with no action.
      - options: optional dictionary with following honoured fields:
        - icon: the name of an icon to be displayed with the item text. This name should be that of one of the icons in the pyFormex configured icon dirs.
        - shortcut: is an optional key combination to select the item.
        - tooltip: a text that is displayed as popup help.
    - before: if specified, should be the text or the action of one of the items in the Menu (not the items list!): the new list of items will be inserted before the specified item.

class `gui.menu.``Menu`(title='UserMenu', parent=None, before=None, tearoff=False, items=None)

  A popup/pulldown menu.

class `gui.menu.``MenuBar`(title='TopMenuBar')

  A menu bar allowing easy menu creation.

class `gui.menu.``DAction`(name, icon=None, data=None, signal=None)

  A DAction is a QAction that emits a signal with a string parameter.

  When triggered, this action sends a signal (default ‘CLICKED’) with a custom string as parameter. The connected slot can then act depending on this parameter.

  `activated`(ok)

    Signal

class `gui.menu.``ActionList`(actions=[], function=None, menu=None, toolbar=None, icons=None, text=None)

  Menu and toolbar with named actions.

  An action list is a list of strings, each connected to some action. The actions can be presented in a menu and/or a toolbar. On activating one of the menu or toolbar buttons, a given signal is emitted with the button string as parameter. A fixed function can be connected to this signal to act dependent on the string value.

  `add`(name, icon=None, text=None)

    Add a new name to the actions list and create a matching DAction.

    If the actions list has an associated menu or toolbar, a matching button will be inserted in each of these. If an icon is specified, it will be used on the menu and toolbar. The icon is either a filename or a QIcon object. If text is specified, it is displayed instead of the action’s name.

  `names`()

    Return an ordered list of names of the action items.

  `toolbar`(name)

    Create a new toolbar corresponding to the menu.