Skip to main content
`Ctrl`+`K`

# Interactive Parameters

As indicated by the documentation for Parameters and Parameter Trees, a Parameter is commonly used to expose a value to the user without burdening developers with GUI representations. The `interact` method and friends extend such support to arbitrary Python functions. [1] Before reading further, make sure to read existing Parameter documentation to become familiar with common extra options, creation techniques, and so on.

## Basic Use

Consider a function `a` whose arguments should be tweakable by the user to immediately update some result. Without using `interact`, you might do something like this:

    from pyqtgraph.Qt import QtWidgets
    import pyqtgraph as pg
    from pyqtgraph.parametertree import Parameter, ParameterTree, parameterTypes as ptypes

    def a(x=5, y=6):
       QtWidgets.QMessageBox.information(None, 'Hello World', f'X is {x}, Y is {y}')

    # -----------
    # discussion is from here:
    params = Parameter.create(name='"a" parameters', type='group', children=[
       dict(name='x', type='int', value=5),
       dict(name='y', type='int', value=6)
    ])

    def onChange(_param, _value):
       a(**params)

    for child in params.children():
       child.sigValueChanged.connect(onChange)
    # to here
    # -----------

    app = pg.mkQApp()
    tree = ParameterTree()
    tree.setParameters(params)
    tree.show()
    pg.exec()

Notice in the `-----` comment block, lots of boilerplate and value duplication takes place. If an argument name changes, or the default value changes, the parameter definition must be independently updated as well. In (very common) cases like these, use `interact` instead (the code below is functionally equivalent to above):

    from pyqtgraph.Qt import QtWidgets
    import pyqtgraph as pg
    from pyqtgraph.parametertree import Parameter, ParameterTree, interact

    def a(x=5, y=6):
       QtWidgets.QMessageBox.information(None, 'Hello World', f'X is {x}, Y is {y}')

    # One line of code, no name/value duplication
    params = interact(a)

    app = pg.mkQApp()
    tree = ParameterTree()
    tree.setParameters(params)
    tree.show()
    pg.exec()

There are several caveats, but this is one of the most common scenarios for function interaction.

### `runOptions`

Often, an `interact`-ed function shouldn’t run until multiple parameter values are changed. Or, the function should be run every time a value is changing, not just changed. In these cases, modify the `runOptions` parameter.

    from pyqtgraph.parametertree import interact, RunOptions

    # Will add a button named "Run". When clicked, the function will run
    params = interact(a, runOptions=RunOptions.ON_ACTION)
    # Will run on any `sigValueChanging` signal
    params = interact(a, runOptions=RunOptions.ON_CHANGING)
    # Runs on `sigValueChanged` or when "Run" is pressed
    params = interact(a, runOptions=[RunOptions.ON_CHANGED, RunOptions.ON_ACTION])
    # Any combination of RUN_* options can be used

The default run behavior can also be modified. If several functions are being interacted at once, and all should be with a “Run” button, simply use the provided context manager:

    from pyqtgraph.parametertree import interact
    # `runOptions` can be set to any combination of options as demonstrated above, too
    with interact.optsContext(runOptions=RunOptions.ON_ACTION):
        # All will have `runOptions` set to ON_ACTION
        p1 = interact(aFunc)
        p2 = interact(bFunc)
        p3 = interact(cFunc)
    # After the context, `runOptions` is back to the previous default

If the default for all interaction should be changed, you can directly call `interactDefaults.setOpts` (but be warned - anyone who imports your module will have it modified for them, too. So use the context manager whenever possible). Thus, it is highly advised to make your own `Interactor` object in these cases. The previous options set will be returned for easy resetting afterward:

    from pyqtgraph.parametertree import Interactor
    myInteractor = Interactor()
    oldOpts = myInteractor.setOpts(runOptions=RunOptions.ON_ACTION)
    # Can also directly create interactor with these opts:
    # myInteractor = Interactor(runOptions=RunOptions.ON_ACTION)

    # ... do some things...
    # Unset option
    myInteractor.setOpts(**oldOpts)

### `ignores`

When interacting with a function where some arguments should appear as parameters and others should be hidden, use `ignores`:

    from pyqtgraph.parametertree import interact

    def a(x=5, y=6):
        print(x, y)

    # Only 'x' will show up in the parameter
    params = interact(a, ignores=['y'])

### `closures`

Sometimes, values that should be passed to the `interact`-ed function should come from a different scope (or “closure”), i.e. a variable definition that should be propagated from somewhere else. In these cases, wrap that argument in a function and pass it into `closures` like so. Note that an `InteractiveFunction` object is needed as descibed in a later section.

    from skimage import morphology as morph
    import numpy as np
    from pyqtgraph.parametertree import interact, InteractiveFunction, ParameterTree
    import pyqtgraph as pg

    def dilateImage(image, radius=3):
        image = morph.dilation(image, morph.disk(radius))
        view.setImage(image)

    app = pg.mkQApp()
    view = pg.ImageView()
    # Simulate a grayscale image
    image = np.random.randint(0, 256, size=(512, 512))
    dilate_interact = InteractiveFunction(dilateImage, closures={'image': lambda: image})
    params = interact(dilate_interact)
    # As the 'image' variable changes, the new value will be used during parameter interaction
    view.show()
    tree = ParameterTree()
    tree.setParameters(params)
    tree.show()
    image = 255 - image # Even though 'image' is reassigned, it will be used by the parameter
    pg.exec()

### `parent`

Often, one parameter tree is used to represent several different interactive functions. When this is the case, specify the existing parameter as the `parent`. In all but simple cases, it is usually easier to leverage the decorator version.

    from pyqtgraph.parametertree import Parameter
    def aFunc(x=5, y=6):
        QtWidgets.QMessageBox.information(None, 'Hello World', f'X is {x}, Y is {y}')
    def bFunc(first=5, second=6):
        QtWidgets.QMessageBox.information(None, 'Hello World', f'first is {first}, second is {second}')
    def cFunc(uno=5, dos=6):
        QtWidgets.QMessageBox.information(None, 'Hello World', f'uno is {uno}, dos is {dos}')

    params = Parameter.create(name='Parameters', type='group')
    # All interactions are in the same parent
    interact(aFunc, parent=params)
    interact(bFunc, parent=params)
    interact(cFunc, parent=params)

### `nest`

In all examples so far, `interact` makes a `GroupParameter` which houses another `GroupParameter` inside. The inner group contains the parameter definitions for the function arguments. If these arguments should be directly inside the parent, use `nest=False`:

    def a(x=5, y=6):
        return x + y

    # 'x' and 'y' will be returned in a list, not nested inside another GroupParameter
    # If `parent=...` was specified in the `interact` call, `x` and `y` will be inserted
    # directly as children of `parent`
    params = interact(a, nest=False)

### `runActionTemplate`

When the `runOptions` argument is set to (or contains) `RunOptions.ON_ACTION`, a button will be added next to the parameter group which can be clicked to run the function with the current parameter values. The button’s options can be customized through passing a dictionary to `runActionTemplate`. The dictionary can contain any key accepted as an `action` parameter option. For instance, to run a function either by pressing the button or a shortcut, you can interact like so:

    def a(x=5, y=6):
        return x + y

    # The button will be labeled "Run" and will run the function when clicked or when
    # the shortcut "Ctrl+R" is pressed
    params = interact(a, runActionTemplate={'shortcut': 'Ctrl+R'})

    # Alternatively, add an icon to the button
    params = interact(a, runActionTemplate={'icon': 'run.png'})

    # Why not both?
    params = interact(a, runActionTemplate={'icon': 'run.png', 'shortcut': 'Ctrl+R'})

### `existOk`

When `nest=False`, there can be overlap when several function arguments share the same name. In these cases, the result is an error unless `existOk=True` (the default).

    def a(x=5, y=6):
        return x + y
    def b(x=5, another=6):
        return x + another
    params = interact(a, nest=False)

    # Will raise an error, since 'x' was already in the parameter from interacting with 'a'
    interact(b, nest=False, parent=params, existOk=False)

### `overrides`

In all examples so far, additional parameter arguments such as `limits` were ignored. Return to the closures example and observe what happens when `radius` is < 0:

    ValueError: All-zero footprint is not supported.

To prevent such cases, `overrides` can contain additional parameter specifications (or default values) that will update the created parameter:

    # Cannot go lower than 0
    # These are bound to the 'radius' parameter
    params = interact(dilate_interact, radius={'limits': [1, None]})

Now, the user is unable to set the spinbox to a value < 1.

Similar options can be provided when the parameter type doesn’t match the default value (`list` is a common case):

    def chooseOne(which='a'):
        print(which)

    params = interact(chooseOne, which={'type': 'list', 'limits': list('abc')})

Any value accepted in `Parameter.create` can be used in the override for a parameter.

Also note that overrides can consist of raw values, in the case where just the value should be adjusted or when there is no default:

    def printAString(string):
        print(string)

    params = interact(printAString, string='anything')

#### Functions with `**kwargs`

Functions who allow `**kwargs` can accept additional specified overrides even if they don’t match argument names:

    def a(**canBeNamedAnything):
        print(canBeNamedAnything)
    # 'one' and 'two' will be int parameters that appear
    params = interact(a, one=1, two=2)

If additional overrides are provided when the function doesn’t accept keywords in this manner, they are ignored.

## The Decorator Version

To simplify the process of interacting with multiple functions using the same parameter, a decorator is provided:

    from pyqtgraph.parametertree import Interactor, interact
    params = Parameter.create(name='Parameters', type='group')
    interactor = Interactor(parent=params) # Same parent for all `interact` calls

    info = QtWidgets.QMessageBox.information

    @interactor.decorate()
    def aFunc(x=5, y=6):
        info(None, 'Hello World', f'X is {x}, Y is {y}')

    @interactor.decorate()
    def bFunc(first=5, second=6):
        info(None, 'Hello World', f'first is {first}, second is {second}')

    @interactor.decorate()
    def cFunc(uno=5, dos=6):
        info(None, 'Hello World', f'uno is {uno}, dos is {dos}')

    # Alternatively, the default interactor can be used if you don't need to
    # make your own `Interactor` instance.
    @interact.decorate(parent=params)
    def anotherFunc(one="one"):
        print(one)

    # All interactions are in the same parent

Any value accepted by `interact` can be passed to the decorator.

## Title Formatting

If functions should have formatted titles, specify this in the `titleFormat` parameter:

    def my_snake_case_function(a=5):
        print(a)

    def titleFormat(name):
        return name.replace('_', ' ').title()

    # The title in the parameter tree will be "My Snake Case Function"
    params = interact(my_snake_case_function, titleFormat=titleFormat)

## Using `InteractiveFunction`

In all versions of `interact` described so far, it is not possible to temporarily stop an interacted function from triggering on parameter changes. Normally, one can `disconnect` the hooked-up signals, but since the actually connected functions are out of scope, this is not possible when using `interact`. Additionally, it is not possible to change overrides or `closures` arguments after the fact. Finally, it is not possible to easily call an interacted function with parameter arguments/defaults through normal interact use. If any of these needs arise, use an `InteractiveFunction` instead during registration. This provides `disconnect()` and `reconnect()` methods, and object accessors to `closures` arguments.

    from pyqtgraph.parametertree import InteractiveFunction, interact, Parameter, RunOptions

    def myfunc(a=5):
        print(a)

    useFunc = InteractiveFunction(myfunc)
    param = interact(useFunc, runOptions=RunOptions.ON_CHANGED)
    param['a'] = 6
    # Will print 6
    useFunc.disconnect()
    param['a'] = 5
    # Won't print anything
    useFunc.reconnect()
    param['a'] = 10
    # Will print 10

Note that in cases like these, where simple wrapping of a function must take place, you can use `InteractiveFunction` like a decorator:

    from pyqtgraph.parametertree import InteractiveFunction, interact, Parameter, RunOptions

    @InteractiveFunction
    def myfunc(a=5):
        print(a)

    # myfunc is now an InteractiveFunction that can be used as above
    # Also, calling `myfunc` will preserve parameter arguments
    param = interact(myfunc, RunOptions.ON_ACTION)
    param['a'] = 6

    myfunc()
    # will print '6' since this is the parameter value

[1]

Functions defined in C or whose definitions cannot be parsed by `inspect.signature` cannot be used here. However, in these cases a dummy function can be wrapped and passed instead. Note that all values are passed as keywords, so if positional arguments are expected it will not work.