Parameter Tree

A hierarchy of parameters can be edited using the ParameterTree() dialog.

See also

Parameter Editor

Here is one example.

View of a hierarchical parameter dictionary using ParameterTree

View of ParameterTree dialog.

The hierarchy (a dictionary of dictionaries) is displayed as a tree on the left side. The keys are text strings, to be displayed in the tree. The end of each branch of the tree is a dictionary of Parameter Items. See the next block of Python code. When the end of a branch is selected, a Parameter Editor is shown in the right side of the dialog.

Python code to construct the example hierarchical parameter dictionary

import pyQParamWidget as qpw

hierarchy = {
    "applications": {
        "tiled": {
            "server": {
                "settings_file": qpw.ParameterItemText(
                    label="settings file", value="~/.config/settings.ini"
                ),
                "catalog": qpw.ParameterItemText(label="catalog", value="bluesky_data"),
                "url": qpw.ParameterItemText(label="url", value="http://localhost"),
            },
        },
        "other": {
            "demo": qpw.ParameterItemCheckbox("demo mode?", True),
        },
    },
    "UI": {
        "plotting": {
            "autoplot": qpw.ParameterItemCheckbox(
                label="autoplot",
                value=True,
                tooltip="Plot when the run is selected.",
            ),
            "autoselect": qpw.ParameterItemCheckbox(
                label="autoselect",
                value=True,
                tooltip="Automatically select the signals to plot.",
            ),
            "colors": qpw.ParameterItemChoice(
                label="colors", value="", choices=["", "r", "b", "g", "k"]
            ),
        },
    },
}

Python code to display the hierarchy in a ParameterTree dialog

dialog = qpw.ParameterTree(None, parameters=hierarchy)
# dialog.show()  # modeless: does not block
dialog.exec()  # modal: blocks
# Show the final values of the parameters, once the dialog is closed.
print(f"{dialog.values()=}")

Get the values from the tree dialog

The widget’s values() method returns a hierarchical dictionary with the accepted parameter values. The dictionary keys are the same as the parameter dictionary (hierarchy) supplied.

dialog = qpw.ParameterTree(None, parameters=hierarchy)
dialog.exec()
# ...user interaction
results = dialog.values()

EXAMPLE

Using the hierarchy dictionary above, and making no changes in the tree dialog, print(results) would return:

{
    "applications": {
        "tiled": {
            "server": {
                "settings_file": "~/.config/settings.ini",
                "catalog": "bluesky_data",
                "url": "http://localhost",
            },
        },
        "other": {
            "demo": True,
        },
    },
    "UI": {
        "plotting": {
            "autoplot": True,
            "autoselect": True,
            "colors": "",
        },
}

Accept and Reset buttons

The Accept and Reset buttons are enabled when the editor has changes. The Accept button will update the parameter values from the widgets. The Reset button will update the widgets from the parameters. The user must resolve any changes (by pressing the corresponding button) before another item in the tree can be selected or the dialog can be dismissed.

If the user tries to close the dialog or select a new tree item while changes are unresolved, an alert will be shown (see Accept and Reset buttons). It will not be possible to select another item from the tree until the changes are resolved.

Alert message when selecting another tree item while editor has changes.

Editor shown for other parameters.

After the checkbox was changed (in this example), the server item was selected in the tree. The Alert message box appeared, stating that changes must first be resolved. Once the Alert message box was closed, the selected item changed back to other.