8.6.4.2. pymodaq_gui.managers.action_manager module

class pymodaq_gui.managers.action_manager.ActionManager(toolbar=None, menu=None)[source]

Bases: object

MixIn Class to be used by all UserInterface to manage their QActions and the action they are connected to

Parameters:

toolbar (Optional[QToolBar]) – The toolbar to use as default
menu (Optional[QMenu]) – The menu to use as default

Attributes:

actions: Get all the actions (and widgets added to a toolbar) managed here
actions_names: Get all the action names
menu: Get the default menu
menus: Get all menus
menus_names: Get all menu names
toolbar: Get the default toolbar
toolbars: Get all toolbars
toolbars_names: Get all toolbar names

Methods

`add_action`([short_name, name, icon_name, ...])	Create a new action and add it to toolbar and menu
`add_action_group`(short_name[, name, ...])	Add several related actions to a toolbar under a single button, to avoid overloading the toolbar with one slot per action.
`add_menu`(short_name[, title, parent_menu, ...])	Create and add a menu to a parent menu
`add_toolbar`(short_name[, title, parent, ...])	Create and add a toolbar
`add_widget`(short_name, klass, *args[, tip, ...])	Create and add a widget to a toolbar
`affect_to`(action_name, obj)	Affect action to an object either a toolbar or a menu
`apply_qt_theme`(name)	Apply a qt_themes theme to the whole application and persist it as the default
`apply_toolbar_style`(name)	Persist the toolbar button style and apply it to all toolbars
`connect_action`(name[, slot, connect, ...])	Connect (or disconnect) the action referenced by name to the given slot
`delete_actions`()	Schedule the deletion of all the QActions referenced in this manager, and of its toolbars and menus that have no parent
`get_action`(name)	Getter of a given action
`get_menu`(name)	Getter of a given menu
`get_toolbar`(name)	Getter of a given toolbar
`has_action`(action_name)	Check if an action has been defined :param action_name: The action name as defined in setup_actions :type action_name: `str`
`has_menu`(menu_name)	Check if a menu has been defined
`has_toolbar`(toolbar_name)	Check if a toolbar has been defined
`reference_menu`(short_name, menu)	Add an existing menu to the list of managed menus
`reference_toolbar`(short_name, toolbar)	Add an existing toolbar to the list of managed toolbars
`refresh_icons`()	Rebuild the icons of all managed actions and menus with the current theme colours.
`remove_action`([toolbar, action])	Remove an action from a toolbar and forget it
`set_action_text`(action_name, text)	Convenience method to set the displayed text on an action
`set_menu`(menu)	Set the default menu
`set_toolbar`(toolbar)	Set the default toolbar
`setup_actions`()	Method where to create actions to be subclassed.
`setup_theme_menu`(parent_menu)	Add a 'Theme' submenu choosing the qt_themes theme of the whole application
`setup_toolbar_style_menu`(parent_menu)	Add a 'Toolbar style' submenu choosing how the toolbar buttons of all windows are drawn

is_action_checked
is_action_enabled
is_action_visible
set_action_checked
set_action_enabled
set_action_visible

add_action(short_name='', name='', icon_name='', tip='', checkable=False, checked=False, toolbar=None, menu=None, visible=True, shortcut=None, auto_toolbar=True, auto_menu=False, enabled=True, icon_checked=None, icon_color=None, icon_checked_color=None, flip_h=False, flip_v=False, before=None, action=None, fill=None, rotate=0, follow_theme=True)[source]

Create a new action and add it to toolbar and menu

Parameters:

short_name (str) – the name as referenced in the dict self.actions
name (str) – Displayed name if should be displayed in
icon_name (Union[str, Path, QIcon]) – str/Path: the png file name/path to produce the icon QtGui.QIcon: the instance of a QIcon element ThemeIcon enum: the value of QtGui.QIcon.ThemeIcon (requires Qt>=6.7)
tip (str) – a tooltip to be displayed when hovering above the action
checkable (bool) – set the checkable state of the action
checked (bool) – set the current state of the action
toolbar (Union[str, QToolBar, None]) –
a toolbar where action should be added. Can be:
- None: adds to the default toolbar (self._toolbar)
- str: toolbar name as registered via add_toolbar()
- QToolbar: direct QToolbar instance
Actions can also be added later see affect_to
menu (Union[str, QMenu, None]) –
Where to add the action. Can be:
- None: adds to the default menu (self._menu)
- str: menu name as registered via add_menu()
- QMenu: direct QMenu instance
Actions can also be added later see affect_to
visible (bool) – display or not the action in the toolbar/menu
shortcut (Union[str, Key, QKeySequence, None]) – Using this shortcut will trigger the action
auto_toolbar (bool) – if True add this action to the defined toolbar
auto_menu (bool) – if True add this action to the defined menu
enabled (bool) – set the enabled state of this action
icon_checked (Union[str, Path, QIcon, None]) – str/Path: the png file name/path to produce the icon QtGui.QIcon: the instance of a QIcon element ThemeIcon enum: the value of QtGui.QIcon.ThemeIcon (requires Qt>=6.7) Optional, if set, will be the icon when the action is checked
icon_color (Union[QColor, bytes, str, None]) – color to be applied (if possible) to the unchecked icon. Give theme colours by name (ThemeColor.GREEN or ‘green’) so they follow theme changes
icon_checked_color (Union[QColor, bytes, str, None]) – color to be applied to the checked icon (if any), same as icon_color
flip_h (bool) – mirror the icon horizontally (left ↔ right)
flip_v (bool) – mirror the icon vertically (top ↔ bottom)
rotate (int, optional) – rotate the icon by the given value in degree
before (Union[str, QAction, WidgetActionProxy, None]) – if set, the action is inserted before this action in the toolbar/menu; accepts a short_name str, a QAction instance, or a WidgetActionProxy
action (Optional[QAction]) – An existing action to register instead of creating a new one
fill (Optional[bool]) – Fill or not the icon, if None left to the user configuration
rotate – Rotate the icon by this value in degree
follow_theme (bool) – True (default): colours given as theme colours (ThemeColor, their names, or values resolved from the theme) follow theme changes. False: the colours are resolved once, here, and kept as they are

Returns:

The created action, also referenced as short_name

Return type:

QAction

See also

affect_to

add_action_group(short_name, name='', icon_name='', tip='', checkable=False, checked=False, icon_checked=None, icon_color=None, icon_checked_color=None, toolbar=None, secondary_actions=(), visible=True, enabled=True, follow_theme=True)[source]

Add several related actions to a toolbar under a single button, to avoid overloading the toolbar with one slot per action.

The button shows and triggers a primary action directly (a regular action, created and registered exactly like add_action(), so connect_action(), is_action_checked(), set_action_checked() … all keep working on its short_name unchanged). A small dropdown arrow next to it reveals the secondary actions, each created the same way as add_action() would from its spec dict, but added only to the dropdown, never to a toolbar directly.

If there are no secondary actions, the button behaves like a plain toolbar action (no dropdown arrow).

Parameters:

short_name (str) – the name of the primary action, as referenced in self._actions
name (str)
icon_name (Union[str, Path, QIcon])
tip (str)
checkable (bool)
checked (bool)
icon_checked (Union[str, Path, QIcon, None])
icon_color (Union[QColor, bytes, str, None])

:param : :type icon_checked_color: Union[QColor, bytes, str, None] :param icon_checked_color: forwarded to add_action() for the primary action :type follow_theme: bool :param follow_theme: forwarded to add_action() for the primary action :param toolbar: the toolbar the button is added to (defaults to the default toolbar) :type toolbar: Union[str, QToolBar, None] :param secondary_actions: one spec per dropdown entry, using the same keys as add_action()

(at least short_name); order is preserved in the dropdown menu

Parameters:

visible (bool) – forwarded to the primary action
enabled (bool) – forwarded to the primary action

Returns:

the created button, already added to the toolbar

Return type:

QToolButton

See also

add_action

add_menu(short_name, title='', parent_menu=None, icon_name='', auto_menu=True, menu=None, before=None)[source]

Create and add a menu to a parent menu

Parameters:

short_name (str) – the name as referenced in the dict self._menus
title (str) – Displayed title of the menu. When menu is also provided and title is non-empty, the title overrides the instance’s own title.
parent_menu (QMenuBar | QMenu | str | None) – the parent menu or menubar where this menu should be added. If None, uses the default menu
icon_name (Union[str, Path, QIcon]) – str/Path: the png file name/path to produce the icon QtGui.QIcon: the instance of a QIcon element ThemeIcon enum: the value of QtGui.QIcon.ThemeIcon (requires Qt>=6.7)
auto_menu (bool) – if True add this menu to the defined parent menu
menu (Optional[QMenu]) – an existing QMenu instance to register instead of creating a new one.
before (Union[QMenu, str, None]) – if specified, the new menu will be inserted before this menu (by instance or short_name); if None the menu is appended at the end

Returns:

The created (or provided) menu

Return type:

QMenu

See also

add_action, get_menu

add_toolbar(short_name, title='', parent=None, toolbar=None, area=<ToolBarArea.TopToolBarArea: 4>, add_break=True, before=None)[source]

Create and add a toolbar

Parameters:

short_name (str) – the name as referenced in the dict self._toolbars
title (str) – Displayed title of the toolbar
parent (Optional[QWidget]) – parent widget for the toolbar (typically a QMainWindow)
toolbar (Optional[QToolBar]) – A given toolbar, if None, it is created
area (ToolBarArea) – the area where this toolbar should be added, valid only for a QMainWindow parent
add_break (bool) – If True, a toolbar break is added in the given area before adding the toolbar, valid only for a QMainWindow parent
before (Union[str, QToolBar, None]) – if specified, the new toolbar will be inserted before this toolbar (by instance or short_name)

Returns:

The created toolbar

Return type:

QToolBar

See also

add_action, get_toolbar

add_widget(short_name, klass, *args, tip='', toolbar=None, visible=True, signal_str=None, slot=None, enabled=True, auto_toolbar=True, before=None, **kwargs)[source]

Create and add a widget to a toolbar

Parameters:

short_name (str) – the name as referenced in the dict self.actions
klass (Union[str, QWidget, Callable[..., QWidget]]) – should be a custom widget class or the name of a standard widget of QWidgets
args (Any) – variable arguments passed as is to the widget constructor
tip (str) – a tooltip to be displayed when hovering above the widget
toolbar (Union[str, QToolBar, None]) – a toolbar where the widget should be added.
visible (bool) – display or not the action in the toolbar/menu
signal_str (Optional[str]) – an attribute of type Signal of the widget
slot (Optional[Callable[..., Any]]) – a callable connected to the signal
enabled (bool) – enable state of the widget
auto_toolbar (bool) – if True add this action to the defined toolbar
before (Union[str, QAction, WidgetActionProxy, None]) – if set, the action is inserted before this action in the toolbar/menu; accepts a short_name str, a QAction instance, or a WidgetActionProxy
kwargs (Any) – variable named arguments passed as is to the widget constructor

Return type:

Union[WidgetActionProxy, QWidget]

affect_to(action_name, obj)[source]

Affect action to an object either a toolbar or a menu

Parameters:

action_name (Union[str, QAction, WidgetActionProxy]) – The action name as defined in setup_actions
obj (Union[QToolBar, QMenu]) – The object where to add the action

Return type:

None

apply_qt_theme(name)[source]

Apply a qt_themes theme to the whole application and persist it as the default

Return type:: None

apply_toolbar_style(name)[source]

Persist the toolbar button style and apply it to all toolbars

Return type:: None

connect_action(name, slot=None, connect=True, signal_name='')[source]

Connect (or disconnect) the action referenced by name to the given slot

Parameters:

name (str) – key of the action as referenced in the self._actions dict
slot (Optional[Callable[..., Any]]) – a method/function
connect (bool) – if True connect the trigger signal of the action to the defined slot else disconnect it
signal_name (str) – try to use it as a signal (for widgets added…) otherwise use the triggered signal

Return type:

None

delete_actions()[source]

Schedule the deletion of all the QActions referenced in this manager, and of its toolbars and menus that have no parent

A Qt object keeps the slots connected to its signals (often lambdas holding the manager) alive as long as the C++ object exists. Unparented actions, toolbars or menus therefore keep the whole UI that created them alive after it is closed, out of reach of Python’s garbage collector. Call this when the UI is closed for good.

Added in version 5.3.9.

Return type:: None

get_action(name)[source]

Getter of a given action

Parameters:: name (str) – The action name as defined in setup_actions
Return type:: Union[QAction, WidgetActionProxy]

get_menu(name)[source]

Getter of a given menu

Parameters:: name (str) – The menu name as defined when calling add_menu
Return type:: QMenu

get_toolbar(name)[source]

Getter of a given toolbar

Parameters:: name (str) – The toolbar name as defined when calling add_toolbar
Return type:: QToolBar

has_action(action_name)[source]

Check if an action has been defined :param action_name: The action name as defined in setup_actions :type action_name: str

Returns:: bool
Return type:: bool

has_menu(menu_name)[source]

Check if a menu has been defined

Parameters:: menu_name (str) – The menu name as defined when calling add_menu
Returns:: bool
Return type:: bool

has_toolbar(toolbar_name)[source]

Check if a toolbar has been defined

Parameters:: toolbar_name (str) – The toolbar name as defined when calling add_toolbar
Returns:: bool
Return type:: bool

reference_menu(short_name, menu)[source]

Add an existing menu to the list of managed menus

Return type:: None

reference_toolbar(short_name, toolbar)[source]

Add an existing toolbar to the list of managed toolbars

Return type:: None

refresh_icons()[source]

Rebuild the icons of all managed actions and menus with the current theme colours.

Icons bake their colours when created. This is done automatically when pymodaq_gui.qt_utils.apply_theme() changes the theme; call it if the palette was changed by other means. Only icons given by name are rebuilt, see QAction.refresh_icon().

Return type:: None

remove_action(toolbar=None, action=None)[source]

Remove an action from a toolbar and forget it

Parameters:

toolbar (QToolBar | str | None) – The toolbar (or its name) to remove the action from. If None, the action is not removed from a toolbar
action (str | QAction | WidgetActionProxy | None) – The action (or its short_name) to remove

Return type:

None

set_action_text(action_name, text)[source]

Convenience method to set the displayed text on an action

Parameters:

action_name (str) – The action name as defined in setup_actions
text (str) – The text to display

Return type:

None

set_menu(menu)[source]

Set the default menu

Parameters:: menu (QMenu | str) – The menu to set as default
Return type:: None

set_toolbar(toolbar)[source]

Set the default toolbar

Parameters:: toolbar (Union[QToolBar, str]) – The toolbar to set as default
Return type:: None

setup_actions()[source]

Method where to create actions to be subclassed. Mandatory

Examples

>>> self.add_action('Quit', 'close2', "Quit program")
>>> self.add_action('Grab', 'camera', "Grab from camera", checkable=True)
>>> self.add_action('Load', 'Open', "Load target file (.h5, .png, .jpg) or data from camera", checkable=False)
>>> self.add_action('Save', 'SaveAs', "Save current data", checkable=False)

See also

ActionManager.add_action

Return type:: None

setup_theme_menu(parent_menu)[source]

Add a ‘Theme’ submenu choosing the qt_themes theme of the whole application

Return type:: None

setup_toolbar_style_menu(parent_menu)[source]

Add a ‘Toolbar style’ submenu choosing how the toolbar buttons of all windows are drawn

Return type:: None

property actions: list[QAction]: Get all the actions (and widgets added to a toolbar) managed here

property actions_names: list[str]: Get all the action names

is_action_checked[source]