8.6.4.6. pymodaq_gui.managers.parameter_manager module

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

Bases: object

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 (Optional[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.
`clear_settings_slot`()	Remove all the children of the settings (the tree is emptied)
`connect_tree`()	Call parameter_tree_changed each time the settings change
`create_parameter`(settings)	Create a Parameter object from various input types.
`disconnect_tree`()	Stop calling parameter_tree_changed when the settings change
`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_activated`(param)	Non-mandatory method to be subclassed for actions to perform when a parameter is activated.
`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
`tree_batch_update`()	Context manager to change many settings at once: the tree does not repaint nor resize its first column for each item, it does it once at the end
`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.

static create_parameter(settings)[source]

Create a Parameter object from various input types.

Parameters:: settings (Union[Parameter, List[Dict[str, str]], Path, str]) – 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)[source]

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 (Tuple[Parameter, int]) – The child parameter that was added and its index in the children of param

Return type:

None

Examples

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

Notes

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

clear_settings_slot()[source]

Remove all the children of the settings (the tree is emptied)

Return type:: None

connect_tree()[source]

Call parameter_tree_changed each time the settings change

Return type:: None

disconnect_tree()[source]

Stop calling parameter_tree_changed when the settings change

Return type:: None

limits_changed(param, data)[source]

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.

Return type:

None

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)[source]

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 (Union[Path, bool, None]) – Path to the XML file containing saved settings. If None or False (the value sent by a triggered QAction), opens a file dialog for the user to select a file. Default is None.
Return type:: 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)[source]

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

Return type:

None

on_toolbar_toggled()[source]

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.

Return type:: None

options_changed(param, data)[source]

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.

Return type:

None

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_activated(param)[source]

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

This method is called automatically when the button of a parameter of type action or action_led is clicked (or when its activate method is called). The activation is not a change of value, so it is not given to value_changed().

Parameters:: param (Parameter) – The parameter that has just been activated
Return type:: None

param_deleted(param)[source]

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
Return type:: None

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)[source]

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[Tuple[Parameter, str, Any]]) – List of changes, where each change is a tuple of (parameter, change_type, data)

Return type:

None

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 - ‘activated’: A parameter of type ‘action’ or ‘action_led’ was activated (its button clicked)

save_settings_slot(file_path=None)[source]

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 (Union[Path, bool, None]) – Path where the settings should be saved. If None or False (the value sent by a triggered QAction), opens a file dialog for the user to select a location. The file extension must be ‘.xml’. Default is None.
Return type:: 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='')[source]

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 “”.
Return type:: None

Notes

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

set_settings(settings)[source]

similar to the property setter but easier to subclass

Return type:: None

tree_batch_update()[source]

Context manager to change many settings at once: the tree does not repaint nor resize its first column for each item, it does it once at the end

Return type:: Iterator[None]

update_settings_slot(file_path=None)[source]

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 (Union[Path, bool, None]) – Path to the XML file containing settings to apply. If None or False (the value sent by a triggered QAction), opens a file dialog for the user to select a file. Default is None.
Return type:: 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)[source]

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
Return type:: None

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.

params: List[Any] = []

property settings: Parameter

The root parameter object containing all settings.

Type:: Parameter

Setter accepts:: Union[Parameter, List[Dict[str, str]], Path]

settings_name = 'custom_settings'

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

class pymodaq_gui.managers.parameter_manager.ParameterTreeWidget(action_list=('save', 'update', 'load'), tree=None)[source]

Bases: ActionManager

Widget that combines a ParameterTree with a toolbar for parameter management.

This class provides a complete UI for managing parameters, including actions for saving, loading, updating settings, and searching through the parameter tree. The toolbar can be collapsed to save screen space.

Parameters:

action_list (tuple) – Tuple of action names to include in the toolbar. Valid values are: ‘save’, ‘update’, ‘load’, and ‘search’. Default is (‘save’, ‘update’, ‘load’).
tree (Optional[ParameterTree]) – ParameterTree that would allow specific dragdrop for instance)

Variables:

widget (QWidget) – The main widget containing the toolbar and parameter tree
tree (ParameterTree) – A custom parameter tree for displaying and editing parameters
toolbar (QToolBar) – Toolbar containing action buttons for parameter management
collapsible_widget (CollapsibleWidget) – Widget that allows the toolbar to be collapsed/expanded

Methods

`activate_search`()	Show the collapsible widget and focus on the search field.
`collapse_toolbar`()	Collapse the toolbar and clear search field focus.
`setup_actions`([action_list])	Create and configure toolbar actions based on the provided action list.

activate_search()[source]

Show the collapsible widget and focus on the search field.

Expands the toolbar if it’s currently collapsed, then sets focus to the search field and selects all existing text for easy replacement.

Return type:: None

collapse_toolbar()[source]

Collapse the toolbar and clear search field focus.

If the toolbar is currently expanded, this method collapses it and removes focus from the search field, effectively canceling the search mode.

Return type:: None

setup_actions(action_list=('search', 'save', 'update', 'load'))[source]

Create and configure toolbar actions based on the provided action list.

Parameters:: action_list (tuple) – Tuple of action names to include. Valid values are: - ‘search’: Adds a search field with debounced text input - ‘save’: Adds a button to save settings to an XML file - ‘update’: Adds a button to update settings from an XML file - ‘load’: Adds a button to load settings from an XML file - ‘clear’: Adds a button to clear the content of the tree Default is (‘search’, ‘save’, ‘update’, ‘load’).
Return type:: None