8.5.3.3. 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 (ParameterTree) – Allow the use of modified ParameterTree (allowing drag/drop for instance)

params

Class attribute defining the Parameter tree structure. Should be overridden in subclasses to define the specific parameter hierarchy.

Type:: list of dicts

settings_name

The particular name given to the root Parameter object (self.settings)

Type:: str

settings

The root Parameter object containing all parameter definitions

Type:: Parameter

settings_tree

Widget holding a ParameterTree and a toolbar for interacting with the tree

Type:: QWidget

tree

The underlying ParameterTree widget for displaying parameters

Type:: ParameterTree

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.
`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.
`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]) – 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 (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)[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.

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

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.

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.

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)[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

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 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)[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 (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='')[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 “”.

Notes

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

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

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 = []

property settings: Parameter

The root parameter object containing all settings.

Type:: Parameter

settings_name = 'custom_settings'

property settings_tree: qtpy.QtWidgets.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 (ParameterTree) – ParameterTree that would allow specific dragdrop for instance)

widget

The main widget containing the toolbar and parameter tree

Type:: QWidget

tree

A custom parameter tree for displaying and editing parameters

Type:: ParameterTree

toolbar

Toolbar containing action buttons for parameter management

Type:: QToolBar

collapsible_widget

Widget that allows the toolbar to be collapsed/expanded

Type:: CollapsibleWidget

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.

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.

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 Default is (‘search’, ‘save’, ‘update’, ‘load’).