API of the various managers, special classes easing the use of various things such as QActions and toolbars, Parameters, ControlModules, Experiments, Configurations, ROIs…

8.3.3. GUI Managers

The ActionManager and Parameter Manager are defined in the pymodaq_gui package and ease the developement of GUI. There are the base classes of most GUI in PyMoDAQ, especially the CustomApp and CustomExt classes.

addaction([name, icon_name, tip, checkable, ...])	Create a new action and add it eventually to a toolbar and a menu
QAction(icon_unchecked[, name, ...])	QAction subclass to mimic signals as pushbuttons.
ActionManager([toolbar, menu])	MixIn Class to be used by all UserInterface to manage their QActions and the action they are connected to

ParameterManager([settings_name, ...])

Class dealing with Parameter and ParameterTree management.

class pymodaq_gui.managers.action_manager.QAction(icon_unchecked, name='', icon_checked=None, icon_color=None, icon_checked_color=None, flip_h=False, flip_v=False, rotate=0, fill=None)

QAction subclass to mimic signals as pushbuttons. Done to be sure of backcompatibility when I moved from pushbuttons to QAction

Attributes:

clicked

Methods

click
connect_to
set_icon

pymodaq_gui.managers.action_manager.addaction(name='', icon_name='', tip='', checkable=False, checked=False, slot=None, toolbar=None, menu=None, visible=True, shortcut=None, 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)

Create a new action and add it eventually to a toolbar and a menu

Parameters:

• name (str) – Displayed name if should be displayed (for instance in menus)

• 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

• slot (Callable) – Method or function that will be called when the action is triggered

• toolbar (QToolBar) – a toolbar where action should be added.

• menu (QMenu) – a menu where action should be added.

• visible (bool) – display or not the action in the toolbar/menu

• shortcut (Union[str, Key, QKeySequence]) – Using this shortcut will trigger the action

• enabled (bool) – set the enabled state

• icon_checked (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) Optional, if set, will be the icon when the action is checked (checkable will be set to True)

• icon_color (Union[QColor, str]) – color to be applied (if possible) to the unchecked icon

• icon_checked_color (Union[QColor, str]) – color to be applied to the checked icon (if any)

• 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 degrees

• before (QAction) – if set, the action is inserted before this action in the toolbar/menu; if None the action is appended at the end

• action (QAction | QWidgetAction)

• fill (bool) – Fill or not the icon, if None left to the user configuration

• rotate – Rotate the icon by this value in degree

class pymodaq_gui.managers.action_manager.ActionManager(toolbar=None, menu=None)

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

Parameters:

• toolbar (QToolBar) – The toolbar to use as default

• menu (QMenu) – The menu to use as default

Attributes:

actions

actions_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_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_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
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 :type action_name: str :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 toolbar to the list of managed toolbars
reference_toolbar(short_name, toolbar)	Add an existing toolbar to the list of managed toolbars
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_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
remove_action
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)

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]) – 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]) – 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]) – color to be applied (if possible) to the unchecked icon

• icon_checked_color (Union[QColor, bytes, str]) – color to be applied to the checked icon (if any)

• 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 (QAction | QWidgetAction)

• fill (bool) – Fill or not the icon, if None left to the user configuration

• rotate – Rotate the icon by this value in degree

See also

affect_to

add_menu(short_name, title='', parent_menu=None, icon_name='', auto_menu=True, menu=None, before=None)

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) – 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 (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)

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 (QWidget) – parent widget for the toolbar (typically a QMainWindow)

• toolbar (QToolBar) – A given toolbar, if None, it is created

• area (ToolBarArea, optional) – the area where this toolbar should be added, valid only for a QMainWindow parent

• add_break (bool, optional) – 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)

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, object]) – should be a custom widget class or the name of a standard widget of QWidgets

• args (list) – 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]) – a toolbar where the widget should be added.

• visible (bool) – display or not the action in the toolbar/menu

• signal_str (str) – an attribute of type Signal of the widget

• slot (Callable) – 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 (dict) – variable named arguments passed as is to the widget constructor

Return type:

Union[WidgetActionProxy, QWidget]

affect_to(action_name, obj)

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

apply_toolbar_style(name)

Persist the toolbar button style and apply it to all toolbars

connect_action(name, slot=None, connect=True, signal_name='')

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 (method) – 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

get_action(name)

Getter of a given action

Parameters:

name (str) – The action name as defined in setup_actions

Return type:

Union[QAction, WidgetActionProxy]

get_menu(name)

Getter of a given menu

Parameters:

name (str) – The menu name as defined when calling add_menu

Return type:

QMenu

get_toolbar(name)

Getter of a given toolbar

Parameters:

name (str) – The toolbar name as defined when calling add_toolbar

Return type:

QToolBar

has_action(action_name)

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

Returns:

bool

Return type:

bool

has_menu(menu_name)

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)

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)

Add an existing toolbar to the list of managed toolbars

reference_toolbar(short_name, toolbar)

Add an existing toolbar to the list of managed toolbars

set_action_text(action_name, text)

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

set_menu(menu)

Set the default menu

Parameters:

menu (QMenu | str) – The menu to set as default

set_toolbar(toolbar)

Set the default toolbar

Parameters:

toolbar (Union[QToolBar, str]) – The toolbar to set as default

setup_actions()

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

setup_toolbar_style_menu(parent_menu)

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

property menu: QMenu

Get the default menu

property menus: list[QMenu]

Get all menus

property menus_names: list[str]

Get all menu names

property toolbar: QToolBar

Get the default toolbar

property toolbars: list[QToolBar]

Get all toolbars

property toolbars_names: list[str]

Get all toolbar names

class pymodaq_gui.managers.parameter_manager.ParameterManager(settings_name=None, action_list=('search', 'save', 'update', 'load'), tree=None)

Class dealing with Parameter and ParameterTree management.

This class provides a complete parameter management system with support for saving, loading, and updating parameters from XML files. It also includes search functionality and callback methods for responding to parameter changes.

Parameters:

• settings_name (Optional[str]) – The name to assign to the root Parameter object. If None, uses the class attribute ‘settings_name’. Default is None.

• action_list (tuple) – Tuple of action names to include in the toolbar. Valid values are: ‘search’, ‘save’, ‘update’, and ‘load’. Default is (‘search’, ‘save’, ‘update’, ‘load’).

• tree (ParameterTree) – Allow the use of modified ParameterTree (allowing drag/drop for instance)

Variables:

• params (list of dicts) – Class attribute defining the Parameter tree structure. Should be overridden in subclasses to define the specific parameter hierarchy.

• settings_name (str) – The particular name given to the root Parameter object (self.settings)

• settings (Parameter) – The root Parameter object containing all parameter definitions

• settings_tree (QWidget) – Widget holding a ParameterTree and a toolbar for interacting with the tree

• tree (ParameterTree) – The underlying ParameterTree widget for displaying parameters

Examples

>>> class MyManager(ParameterManager):
...     settings_name = 'my_settings'
...     params = [
...         {'title': 'Main:', 'name': 'main_settings', 'type': 'group', 'children': [
...             {'title': 'Value:', 'name': 'value', 'type': 'int', 'value': 0},
...         ]},
...     ]
...
...     def value_changed(self, param):
...         if param.name() == 'value':
...             print(f'Value changed to: {param.value()}')

Attributes:

settings

Parameter: The root parameter object containing all settings.

settings_tree

QWidget: The main widget containing the parameter tree and toolbar.

tree

ParameterTree: The underlying parameter tree widget.

Methods

child_added(param, data)	Non-mandatory method to be subclassed for actions to perform when a child parameter is added.
create_parameter(settings)	Create a Parameter object from various input types.
limits_changed(param, data)	Non-mandatory method to be subclassed for actions to perform when parameter limits change.
load_settings_slot([file_path])	Load settings from an XML file, replacing current settings entirely.
menu_changed(param, data)	Non-mandatory method to be subclassed for actions to perform when context menu changed.
on_toolbar_toggled()	Handle toolbar expand/collapse events and manage search filter state.
options_changed(param, data)	Non-mandatory method to be subclassed for actions to perform when parameter options change.
param_deleted(param)	Non-mandatory method to be subclassed for actions to perform when a parameter is deleted.
parameter_tree_changed(param, changes)	Handle changes in the parameter tree and dispatch to specific handlers.
save_settings_slot([file_path])	Save the current settings to an XML file.
search_settings_slot([text])	Handle search text changes and filter the parameter tree.
set_settings(settings)	similar to the property setter but easier to subclass
update_settings_slot([file_path])	Update settings from an XML file with matching structure validation.
value_changed(param)	Non-mandatory method to be subclassed for actions to perform when a parameter value changes.

clear_settings_slot
connect_tree
disconnect_tree

static create_parameter(settings)

Create a Parameter object from various input types.

Parameters:

settings (Union[Parameter, List[Dict[str, str]], Path]) – The settings to convert. Can be: - A Parameter object (creates a copy) - A list of dictionaries defining parameter structure - A Path or string pointing to an XML file with saved parameters

Returns:

A new Parameter object created from the input settings

Return type:

Parameter

Raises:

TypeError – If settings is not one of the supported types

Examples

>>> params_list = [{'title': 'Value', 'name': 'val', 'type': 'int', 'value': 5}]
>>> param = ParameterManager.create_parameter(params_list)
>>> print(param.child('val').value())
5

child_added(param, data)

Non-mandatory method to be subclassed for actions to perform when a child parameter is added.

This method is called automatically when a new child parameter is added to the parameter tree. Override this method in subclasses to implement custom behavior in response to parameter additions.

Parameters:

• param (Parameter) – The parent parameter to which the child is being added

• data (Parameter) – The child parameter that was added

Examples

>>> def child_added(self, param, data):
...     if param.name() == 'dynamic_list':
...         print(f'New item added: {data.name()}')
...         self.update_item_count()

Notes

For this method to be triggered, one of the following Parameter methods must be used: - addChild() - addChildren() - insertChildren()

limits_changed(param, data)

Non-mandatory method to be subclassed for actions to perform when parameter limits change.

This method is called automatically when the limits (min/max bounds) of a parameter are changed. Override this method in subclasses to respond to limit changes, such as validating dependent parameters or updating the UI.

Parameters:

• param (Parameter) – The parameter whose limits have been changed

• data (Tuple[Number, Number]) – Tuple containing (min_limit, max_limit). For numeric parameters, these are typically float or int values. For specialized parameters, could be other comparable objects.

Examples

>>> def limits_changed(self, param, data):
...     if param.name() == 'temperature':
...         min_temp, max_temp = data
...         print(f'Temperature range updated: {min_temp}°C to {max_temp}°C')
...         self.validate_current_temperature()

Notes

For this method to be triggered, the Parameter.setLimits() method must be used.

load_settings_slot(file_path=None)

Load settings from an XML file, replacing current settings entirely.

Opens a file dialog for the user to select a file, or uses the provided file path. The current parameter tree structure is completely replaced with the loaded settings.

Parameters:

file_path (Path) – Path to the XML file containing saved settings. If None or False, opens a file dialog for the user to select a file. Default is None.

Notes

The starting directory for the file dialog is the user’s config folder with a ‘settings’ subfolder. This method completely replaces the current settings structure, unlike update_settings_slot() which requires matching structure.

Warning

This operation replaces all current settings. Any unsaved changes will be lost.

Examples

>>> manager = ParameterManager()
>>> # Interactive load
>>> manager.load_settings_slot()
>>> # Programmatic load
>>> manager.load_settings_slot(Path('saved_settings.xml'))

See also

update_settings_slot

Update settings while preserving structure

save_settings_slot

Save current settings to file

menu_changed(param, data)

Non-mandatory method to be subclassed for actions to perform when context menu changed.

This method is called automatically when the user selects one of the entry of the context menu

Parameters:

• param (Parameter) – The parameter whose menu has been changed

• data (str) – The selected menu string

on_toolbar_toggled()

Handle toolbar expand/collapse events and manage search filter state.

When the toolbar is expanded, restores the previous search filter. When collapsed, clears the search filter to show all parameters again.

Notes

This ensures that collapsing the toolbar (which hides the search field) also clears any active search filter, providing a consistent user experience.

options_changed(param, data)

Non-mandatory method to be subclassed for actions to perform when parameter options change.

This method is called automatically when options of a parameter are modified using the setOpts() method. Override this method in subclasses to respond to option changes such as visibility, enabled state, or other properties.

Parameters:

• param (Parameter) – The parameter whose options have been changed

• data (Dict[str, Any]) – Dictionary where keys are option names (strings) and values are the new option values. Common options include ‘visible’, ‘enabled’, ‘readonly’, etc.

Examples

>>> def options_changed(self, param, data):
...     if param.name() == 'advanced_mode' and 'visible' in data:
...         if data['visible']:
...             print('Advanced options are now visible')
...         else:
...             print('Advanced options are now hidden')

Notes

For this method to be triggered, the Parameter.setOpts() method must be used.

param_deleted(param)

Non-mandatory method to be subclassed for actions to perform when a parameter is deleted.

This method is called automatically when a parameter is removed from the parameter tree. Override this method in subclasses to implement custom cleanup or notification behavior.

Parameters:

param (Parameter) – The parameter that has been deleted from the tree

Examples

>>> def param_deleted(self, param):
...     if param.name() == 'temporary_setting':
...         print(f'Temporary setting {param.name()} was removed')
...         self.cleanup_related_resources(param)

Notes

For this method to be triggered, the Parameter.removeChild() method must be used.

parameter_tree_changed(param, changes)

Handle changes in the parameter tree and dispatch to specific handlers.

This method is called whenever any change occurs in the parameter tree. It processes the changes and calls the appropriate handler method based on the type of change.

Parameters:

• param (Parameter) – The parameter object that emitted the change signal

• changes (list of tuple) – List of changes, where each change is a tuple of (parameter, change_type, data)

Notes

The following change types are handled: - ‘childAdded’: A new child parameter was added - ‘value’: A parameter value was changed - ‘parent’: A parameter was removed (parent changed to None) - ‘options’: Parameter options were modified - ‘limits’: Parameter limits were changed

save_settings_slot(file_path=None)

Save the current settings to an XML file.

Opens a file dialog for the user to select a save location, or uses the provided file path. The settings are serialized to XML format and saved to disk.

Parameters:

file_path (Path) – Path where the settings should be saved. If None or False, opens a file dialog for the user to select a location. The file extension must be ‘.xml’. Default is None.

Notes

The starting directory for the file dialog is the user’s config folder with a ‘settings’ subfolder. The file is automatically given a .xml extension if not already present.

Examples

>>> manager = ParameterManager()
>>> # Interactive save
>>> manager.save_settings_slot()
>>> # Programmatic save
>>> manager.save_settings_slot(Path('my_settings.xml'))

search_settings_slot(text='')

Handle search text changes and filter the parameter tree.

This slot is connected to the search widget’s text changed signal. It stores the current search text and applies the filter to show only matching parameters.

Parameters:

text (str) – The search text to filter parameters by. Empty string shows all parameters. Default is “”.

Notes

The search is typically case-insensitive and matches against parameter names and titles.

set_settings(settings)

similar to the property setter but easier to subclass

update_settings_slot(file_path=None)

Update settings from an XML file with matching structure validation.

Opens a file dialog for the user to select a file, or uses the provided file path. The loaded settings must have the same structure (parameter names and hierarchy) as the current settings. Only the values are updated, not the structure.

Parameters:

file_path (Path) – Path to the XML file containing settings to apply. If None or False, opens a file dialog for the user to select a file. Default is None.

Notes

The starting directory for the file dialog is the user’s config folder with a ‘settings’ subfolder. The loaded settings must have identical structure (same parameter names and children) as the current settings, otherwise the update is rejected with a warning message.

Examples

>>> manager = ParameterManager()
>>> # Interactive update
>>> manager.update_settings_slot()
>>> # Programmatic update
>>> manager.update_settings_slot(Path('compatible_settings.xml'))

See also

load_settings_slot

Load settings without structure validation

save_settings_slot

Save current settings to file

value_changed(param)

Non-mandatory method to be subclassed for actions to perform when a parameter value changes.

This method is called automatically when a parameter’s value is changed using the setValue() method. Override this method in subclasses to implement custom behavior in response to value changes.

Parameters:

param (Parameter) – The parameter whose value has just changed

Examples

>>> def value_changed(self, param):
...     if param.name() == 'enable_feature':
...         if param.value():
...             print('Feature enabled')
...             self.settings.child('status', 'ready').setValue(True)
...         else:
...             print('Feature disabled')

Notes

For this method to be triggered, changes must be made using the Parameter.setValue() method, not by direct attribute assignment.

property settings: Parameter

The root parameter object containing all settings.

Type:

Parameter

property settings_tree: QWidget

The main widget containing the parameter tree and toolbar.

Type:

QWidget

property tree: ParameterTree

The underlying parameter tree widget.

Type:

ParameterTree

8.3.4. Module Managers

The Module Manager is the tool used in all extensions to deal and use the control modules from the DashBoard.

ModulesManager([detectors, actuators, ...])

Class to manage DAQ_Viewers and DAQ_Moves with UI to select some

class pymodaq.utils.managers.modules_manager.ModulesManager(detectors=None, actuators=None, selected_detectors=None, selected_actuators=None, parent_name='', **kwargs)

Class to manage DAQ_Viewers and DAQ_Moves with UI to select some

Easier to connect control modules signals to slots, test, …

Parameters:

• detectors (Optional[Sequence[DAQ_Viewer]])

• actuators (Optional[Sequence[DAQ_Move]])

• selected_detectors (Optional[Sequence[DAQ_Viewer]]) – sublist of detectors

• selected_actuators (Optional[Sequence[DAQ_Move]]) – sublist of actuators

Attributes:

Nactuators

Get the number of selected actuators

Ndetectors

Get the number of selected detectors

actuator_timeout

actuators

Get the list of selected actuators

actuators_all

Get the list of all actuators

actuators_name

Get all the names of the actuators

detector_timeout

detectors

Get the list of selected detectors

detectors_all

Get/Set the list of all detectors

detectors_name

Get all the names of the detectors

modules

Get the list of detectors and actuators

modules_all

Get the list of all detectors and actuators

modules_name

selected_actuators_name

Get/Set the names of the selected actuators

selected_detectors_name

Get/Set the names of the selected detectors

Methods

add_modules(modules)	Add new modules to the manager keeping the initial set of selected actuators or detectors
connect_actuators([connect, slot, signal])	Connect the selected actuators signal to a given or default slot
connect_and_move_actuators(dte_act[, mode, ...])	Connect Actuators specified in the dte object and move them either absolute or relative to the given value
connect_detectors([connect, slot])	Connect selected DAQ_Viewers's grab_done_signal to the given slot
forget_callback(callback[, module_type, ...])	to be called by the caller of self.move_actuators_with_callback or self.grab_data_with_callback in order to disconnect properly the callback
get_det_data_list()	Deprecated alias for probe_detectors(), kept for backward compatibility.
get_missing_actuators()	match on origin (stable per-module id) rather than name: dte_act's .name holds the requested actuator's title, which is what gets stamped as .origin on the DataActuator the actuator reports back
get_missing_detectors()	match on origin (stable per-module id) rather than name, since a single detector emits one DataWithAxes per channel, each possibly named differently
get_mod_from_name(name[, mod])	Getter of a given module from its name (title)
get_mods_from_names(names[, mod])	Getter of a list of given modules from their name (title)
get_names(modules)	Get the titles of a list of Control Modules
get_probed_data_full_names([dim])	Return full names (origin/name) of probed data, optionally filtered by dim.
get_random_id()	get a random id not already used by a module
grab_data([check_do_override, Naverage])	Do a single grab of connected and selected detectors
grab_datas(**kwargs)	For back compatibility but use self.grab_data
move_actuators(dte_act[, mode, polling])	will apply positions to each currently selected actuators.
move_actuators_with_callback(dte_act[, ...])	Move actuators defined within a DataToExport to the value included in the DatActuators within
on_hardware_initialization(do_init, module)	Bypass method during initialization to assert whether a Master of some slave module already exists
order_positions(positions)	Reorder the content of the DataToExport given the order of the selected actuators
probe_actuators()	Open a single dialog to set target positions for all selected actuators, move them, then populate the Actuators panel's result tree (probe_actuators_results)
probe_detectors()	Do a snap of selected detectors, to populate the Detectors panel's result tree (probe_detectors_results) and return the data
set_actuators(actuators, selected_actuators)	Populates actuators and the subset to be selected in the UI
set_actuators_from_names(actuators, ...)	Populates actuators and the subset to be selected in the UI from their names
set_detectors(detectors, selected_detectors)	Populates detectors and the subset to be selected in the UI
set_detectors_from_names(detectors, ...)	Populates detectors and the subset to be selected in the UI from their names
test_move_actuators()	Deprecated alias for probe_actuators(), kept for backward compatibility.
value_changed(param)

actuators_changed
det_done
det_done_signal
detectors_changed
enable_modules
grab_data_with_callback
modules_added_signal
move_done
move_done_signal
raise_actuator_timeout
reset_signals
show_only_control_modules
timeout_signal

classmethod get_names(modules)

Get the titles of a list of Control Modules

Parameters:

modules (list[Union[DAQ_Move, DAQ_Viewer]])

add_modules(modules)

Add new modules to the manager keeping the initial set of selected actuators or detectors

connect_actuators(connect=True, slot=None, signal='move_done')

Connect the selected actuators signal to a given or default slot

Parameters:

• connect (bool)

• slot (builtin_function_or_method) – method or function the chosen signal will be connected to if None, then the default move_done slot is used

• signal (str) –

  What kind of signal is to be used:

  • ’move_done’ will connect the move_done_signal to the slot

  • ’current_value’ will connect the ‘current_value_signal’ to the slot

See also

move_done()

connect_and_move_actuators(dte_act, mode=MoveType.ABS, polling=True, slot=None, signal='move_done')

Connect Actuators specified in the dte object and move them either absolute or relative to the given value

Return type:

DataToExport

connect_detectors(connect=True, slot=None)

Connect selected DAQ_Viewers’s grab_done_signal to the given slot

Parameters:

• connect (bool) – if True, connect to the given slot (or default slot) if False, disconnect all detectors (not only the currently selected ones. This is made because when selected detectors changed if you only disconnect those one, the previously connected ones will stay connected)

• slot (method) – A method that should be connected, if None self.det_done is connected by default

forget_callback(callback, module_type=ModuleType.Detector, disconnect_modules=True)

to be called by the caller of self.move_actuators_with_callback or self.grab_data_with_callback in order to disconnect properly the callback

Optionaly also disconnect each selected actuaor and/or detector to the inner method checking when each move/grab is done

get_det_data_list()

Deprecated alias for probe_detectors(), kept for backward compatibility.

Return type:

DataToExport

get_missing_actuators()

match on origin (stable per-module id) rather than name: dte_act’s .name holds the requested actuator’s title, which is what gets stamped as .origin on the DataActuator the actuator reports back

Return type:

list[str]

get_missing_detectors()

match on origin (stable per-module id) rather than name, since a single detector emits one DataWithAxes per channel, each possibly named differently

Return type:

list[str]

get_mod_from_name(name, mod=ModuleType.Detector)

Getter of a given module from its name (title)

Returns None is no control module with this name exists

Parameters:

• name (str)

• mod (str) – either ModuleType.Detector for DAQ_Viewer modules or ModuleType.Actuator for DAQ_Move modules

Return type:

Union[DAQ_Move, DAQ_Viewer, None]

get_mods_from_names(names, mod=ModuleType.Detector)

Getter of a list of given modules from their name (title)

Parameters:

• names (list of str)

• mod (str) – either ModuleType.Detector for DAQ_Viewer modules or ModuleType.Actuator for DAQ_Move modules

Return type:

List[Union[DAQ_Move, DAQ_Viewer]]

get_probed_data_full_names(dim=None)

Return full names (origin/name) of probed data, optionally filtered by dim.

Parameters:

dim (DataDim | str) – One of ‘Data0D’, ‘Data1D’, ‘Data2D’, ‘DataND’. If None, all dims are returned.

Return type:

List[str]

get_random_id()

get a random id not already used by a module

Return type:

int

grab_data(check_do_override=True, Naverage=None, **kwargs)

Do a single grab of connected and selected detectors

Return type:

DataToExport

grab_datas(**kwargs)

For back compatibility but use self.grab_data

move_actuators(dte_act, mode=MoveType.ABS, polling=True)

will apply positions to each currently selected actuators. By Default the mode is absolute but can be

Deprecated, you should use move_actuators_with_callback to avoid using a polling mechanism which uses Qt event loop processevents in a while loop

Parameters:

• dte_act (DataToExport) – the DataToExport of position to apply. Its length must be equal to the number of selected actuators

• mode (str) – either MoveType.ABS (‘abs’) for absolute positioning or MoveType.REL (‘rel’) for relative

• polling (bool (should not be used, prefer the callback version)) – if True will wait for the selected actuators to reach their target positions (they have to be connected to a method checking for the position and letting the programm know the move is done (default connection is this object move_done method)

Return type:

DataToExport

move_actuators_with_callback(dte_act, mode=MoveType.REL, callback=None, do_connect_modules=True)

Move actuators defined within a DataToExport to the value included in the DatActuators within

This method will emit a signal to a given callback with a DataToExport containing DataActuators when the moves are done

on_hardware_initialization(do_init, module)

Bypass method during initialization to assert whether a Master of some slave module already exists

order_positions(positions)

Reorder the content of the DataToExport given the order of the selected actuators

probe_actuators()

Open a single dialog to set target positions for all selected actuators, move them, then populate the Actuators panel’s result tree (probe_actuators_results)

probe_detectors()

Do a snap of selected detectors, to populate the Detectors panel’s result tree (probe_detectors_results) and return the data

Return type:

DataToExport

set_actuators(actuators, selected_actuators)

Populates actuators and the subset to be selected in the UI

set_actuators_from_names(actuators, selected_actuators)

Populates actuators and the subset to be selected in the UI from their names

set_detectors(detectors, selected_detectors)

Populates detectors and the subset to be selected in the UI

set_detectors_from_names(detectors, selected_detectors)

Populates detectors and the subset to be selected in the UI from their names

test_move_actuators()

Deprecated alias for probe_actuators(), kept for backward compatibility.

property Nactuators

Get the number of selected actuators

property Ndetectors

Get the number of selected detectors

property actuators: List[DAQ_Move]

Get the list of selected actuators

property actuators_all: list[DAQ_Move]

Get the list of all actuators

property actuators_name

Get all the names of the actuators

property detectors: List[DAQ_Viewer]

Get the list of selected detectors

property detectors_all: List[DAQ_Viewer]

Get/Set the list of all detectors

property detectors_name

Get all the names of the detectors

property modules

Get the list of detectors and actuators

property modules_all

Get the list of all detectors and actuators

property selected_actuators_name: List[str]

Get/Set the names of the selected actuators

property selected_detectors_name

Get/Set the names of the selected detectors

8.3.5. DashBoard Managers

API of the various managers, special classes easing the experimental orchestration in the DashBoard.

experiment.experiment_manager.ExperimentManager([...])
state.state_manager.StateManager([dashboard])	Main class managing the configuration of control modules from a Dashboard in terms of their settings and actuator's value.

class pymodaq.utils.managers.experiment.experiment_manager.ExperimentManager(dashboard=None)

Methods

connect_things()
do_things_for_new_creation()
get_entry_folder(**kwargs_to_entry_folder)	Get the folder path where the managed entries are stored.
list_managed_entries_path(...)	Should return a list of Path objects representing managed entries.
load_control_modules(plugins_sorted)	Load an experiment file and create the corresponding Control Modules in the Dashboard.
remove_preset_related_files(preset_name)	Remove the entries of the other managers (and the dock layout) attached to an experiment
save_entries([entry_path])	Particular implementation to save entries for this inherited Manager
setup_actions()

finalize_execute
list_control_modules_from_preset

class pymodaq.utils.managers.state.state_manager.StateManager(dashboard=None)

Main class managing the configuration of control modules from a Dashboard in terms of their settings and actuator’s value.

This class provides a GUI to create, modify and save configurations for different experiments (DashBoard state) controlling various modules (actuators, detectors…).

Attributes:

actuators

detectors

experiment_filename

experiment_manager

extensions

Methods

add_subentry(special_entry_name)
connect_things()
format_subentries(entries)
get_entry_folder(**kwargs_to_entry_folder)	Get the folder path where the managed entries are stored.
get_module_from_param(param)	should return the module name from data bundled in the ParameterWithPath
populate_from_file(file_path)	for quick testing purpose, not meant to be used at the end
populate_from_settings(settings)	Initialize the state from a Parameter settings.
save_entries([entry_path])
save_new_history_entry()	Implements this method from ManagerBase.
set_experiment_filename(name)	convenience method to be used as slot in Qt connection
setup_actions()
show()	Open the StateManager User Interface

actuator_moved
finalize
update_settings