54. gui.menu — Menus for the pyFormex GUI.

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

54.1. Classes defined in module gui.menu

class gui.menu.BaseMenu(parent=None, *, before=None, items=None, func=None)

A generic hierarchical menu class.

The BaseMenu is a mixin class for Qt menu widgets. It has the following advantages over using plain Qt:

• all the menu data can be collected in an easy readable form and then inserted at once in a menu,

• an action item can have data stored that is passed to the action’s function,

• an item can also be a list of items, and a submenu is created automatically,

• an item can even be any type of data and it will be stored in the item.

• the menu can have a global function triggered by all the items in the menu or its submenu, and then operate on the triggering action according to the data stored in the item.

• items can be easily looked up in the menu through a normalized item text. This facilitates dynamical changes to the menu.

This class is not intended for direct use, but through the subclasses Menu and :class`MenuBar`, which pack the QtWidgets.QMenu and QtWidgets.QMenuBar. See Notes if you want to create a subclass yourself.

Parameters:

• parent (QWidget) – The parent widget, which can be a BaseMenu itself. If provided, the menu will be added to that widget.

• before (str) – The name of an item in the parent menu. If parent was provided and is a BaseMenu having an item with that name, the menu will be inserted before that item instead of at the end.

• items (list) – A list of items to insert in the menu. See insertItems().

• func (callable) – A function that will be called whenever an item in the menu is clicked. The function is passed the triggering action as an argument.

Notes

Subclasses should implement at least the following methods:

• addSeparator()

• insertSeparator(before)

• addAction(text,action)

• insertAction(before,text,action)

• addMenu(text,menu)

• insertMenu(before,text,menu)

• title(): returning the menu title

insertItems(items, *, before=None)

Insert a list of items in the menu.

Parameters:

• items (list) –

  A list of menuitem tuples. Each item is a tuple of two or three elements: (text, action, options):

  • text: the string that will be displayed in the menu. It can contain a ‘&’ before the character that will be used as a hot key for navigating the menu with the keyboard. In lookup operations the string is normalized by removing any ‘&’ characters and converting the text to lower case.

  • action: what to do when the menu item is selected. It can be any of the following:

    • None: a separator is inserted the items and it can not be selected itself.

    • list: the list should again be a list of menu items. A Menu is created from it and treated as below.

    • Menu: the menu will popup when the item is selected.

    • a Python function or instance method: the function is executed when the item is clicked. If options has a key data, its value will be passed as the single argument. Else, no argument is passed.

    • anything else will be stored as data in the action. This is useful in combination with a menuwide function func.

  • options: optional dictionary with following recognized keys:

    • ’icon’: the name of an icon to be displayed with the item text. It should be one of the icons in the pyFormex configured icon dirs.

    • ’shortcut’: an optional key combination to select the item.

    • ’tooltip’: a help text to popup when the mouse is over the item.

    • ’checkable’: if True, a item will present a check box.

    • ’checked’: if True and checkable, the item’s checkbox will initially be checked.

    • ’disabled’: if True, the item will initially be disabled.

• before (str | QAction, optional) – If provided, the items will be inserted before the specified item. It should be the text or the action of one of the items already in self before this insert operation is started.

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.

itemNames()

Return the list of normalized names of all items

menuNames()

Return the list of normalized names of the submenus

separators()

Return the list of separators

index(text)

Return the index of the named item.

Parameters:

text (str) – The text of one of the items in the menu. Case is ignored and &’s are removed.

Returns:

int – The index of the item in the menu, or -1 if there is no item with that name.

action(text)

Return the action with the specified text.

Parameters:

text (str) – The text of one of the items in the menu. Case is ignored and &’s are removed. A string like ‘—i’ returns the i-th separator.

Returns:

QAction | QSeparator – The QAction or QSeparator with the specified text, or None. Note that Daction and submenu items are also QAction instances.

See also

item

like action, but returns a Menu for submenu items.

getItem(text)

Return the item with specified text.

This is like action(), but returns the Menu for submenu items. The same is also obtained by simply indexing the menu: menu[text].

nextItem(item)

Returns the next item in the menu.

This can be used to replace the current item with another menu or to reload a menu.

Parameters:

item (QAction | text) – One of the items in the menu. To get an item from its text, use action(), not getItem().

Returns:

QAction – The next item in the Menu, or None if item was not in self.actions().

removeItem(item)

Remove an item from this menu.

report(recursive=False, prefix='')

Return a report of the menu with the items and submenus.

If recursive, also add report of the submenus. Beware: this may get huge

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

A popup/pulldown menu.

Parameters:

• title (str) – The name of the menu.

• parent (QWidget, optional) – If parent is a QMenu, the Menu will automatically be inserted in the parent. If parent is pf.GUI, the menu is inserted in the main window’s menu bar. If not provided, the menu is a standalone popup menu.

• before (see BaseMenu) –

• items (see BaseMenu) –

• func (see BaseMenu) –

• tearoff (bool) – If True, the Menu can be teared of from its parent and used as a standalone popup menu.

remove()

Close a Menu and remove it from its parent

toolbar(name)

Create a new toolbar corresponding to the menu.

class gui.menu.MenuBar(title='MenuBar', parent=None, before=None, items=None, func=None)

A menu bar allowing easy menu creation.

This can be set as the main window menubar using setMenuBar.

class gui.menu.Action(name, parent=None, icon=None, func=None, data=None)

An Action is an executable menu item.

The Action class provides some extra functionality over the default QAction. It can store an executable function and directly call it instead of using a signal. It can store any data and pass these data to the executed function. If the Action is inserted in a Menu that has its own executable function, that function can detect if the item has its own function and ignore it, or it can detect the stored data and act according to these data. An Action can be inserted in a Menu or in a Toolbar.

Parameters:

• name (str) – The name of the item. In a Menu, this is the text displayed on the item. In a Toolbar the name may or may not be displayed. The name can be used to get the item from the Menu or Toolbar.

• parent (Menu) – The menu in which to insert the action. Inserting an item in a Menu makes sure the item is kept alive and selecting it will trigger the menu’s function if it has one. The Action can be accessed as menu[name].

• icon (QICon | path_like) – An icon for display in a Toolbar. It can be a QICon instance, or (more approperiately) the path to a file storing an image.

• func (callable) – If provided, the function is recorded in the Action and will be executed when the Action is triggered. The stored data will be passed as arguments. If an Action with a func is inserted in a Menu that has it’s own executable function, it is often unwanted that both functions are executed. The menu function is passed the action as an argument and can detect that the action itself has a triggered executable from looking at action.func.

• data – Anything passed as data will be stored in the Action. These data are passed as arguments to func when executed. Without a func, data are also often used together with a Menu function. The Menu function gets the action as an argument and has access to the action’s data as action.data().

Notes

The user can identify an Action by its name or its icon. It is customary to display the name in menus, and show the icon in toolbars. This is the default in pyFormex. It is however possible to also add the icons in a menu or show the names in a toolbar, but it has to be explicitely set or configured.

execute()

Execute the connected function

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.

remove(name)

Remove an action by name

removeAll()

Remove all actions from self

names()

Return an ordered list of names of the action items.

toolbar(name)

Create a new toolbar corresponding to the menu.