Parameter

pyqtgraph.parametertree.registerParameterType(name, cls, override=False)

Register a parameter type in the parametertree system.

This enables construction of custom Parameter classes by name in create().

class pyqtgraph.parametertree.Parameter(**opts)

A Parameter is the basic unit of data in a parameter tree. Each parameter has a name, a type, a value, and several other properties that modify the behavior of the Parameter. Parameters may have parent / child / sibling relationships to construct organized hierarchies. Parameters generally do not have any inherent GUI or visual interpretation; instead they manage ParameterItem instances which take care of display and user interaction.

Note: It is fairly uncommon to use the Parameter class directly; mostly you will use subclasses which provide specialized type and data handling. The static pethod Parameter.create(…) is an easy way to generate instances of these subclasses.

For more Parameter types, see ParameterTree.parameterTypes module.

Signals:
sigStateChanged(self, change, info)	Emitted when anything changes about this parameter at all. The second argument is a string indicating what changed (‘value’, ‘childAdded’, etc..) The third argument can be any extra information about the change
sigTreeStateChanged(self, changes)	Emitted when any child in the tree changes state (but only if monitorChildren() is called) the format of changes is [(param, change, info), …]
sigValueChanged(self, value)	Emitted when value is finished changing
sigValueChanging(self, value)	Emitted immediately for all value changes, including during editing.
sigChildAdded(self, child, index)	Emitted when a child is added
sigChildRemoved(self, child)	Emitted when a child is removed
sigRemoved(self)	Emitted when this parameter is removed
sigParentChanged(self, parent)	Emitted when this parameter’s parent has changed
sigLimitsChanged(self, limits)	Emitted when this parameter’s limits have changed
sigDefaultChanged(self, default)	Emitted when this parameter’s default value has changed
sigNameChanged(self, name)	Emitted when this parameter’s name has changed
sigOptionsChanged(self, opts)	Emitted when any of this parameter’s options have changed
sigContextMenu(self, name)	Emitted when a context menu was clicked

__init__(**opts)

Initialize a Parameter object. Although it is rare to directly create a Parameter instance, the options available to this method are also allowed by most Parameter subclasses.

Keyword Arguments:
name	The name to give this Parameter. This is the name that will appear in the left-most column of a ParameterTree for this Parameter.
value	The value to initially assign to this Parameter.
default	The default value for this Parameter (most Parameters provide an option to ‘reset to default’).
children	A list of children for this Parameter. Children may be given either as a Parameter instance or as a dictionary to pass to Parameter.create(). In this way, it is possible to specify complex hierarchies of Parameters from a single nested data structure.
readonly	If True, the user will not be allowed to edit this Parameter. (default=False)
enabled	If False, any widget(s) for this parameter will appear disabled. (default=True)
visible	If False, the Parameter will not appear when displayed in a ParameterTree. (default=True)
renamable	If True, the user may rename this Parameter. (default=False)
removable	If True, the user may remove this Parameter. (default=False)
expanded	If True, the Parameter will initially be expanded in ParameterTrees: Its children will be visible. (default=True)
syncExpanded	If True, the expanded state of this Parameter is synchronized with all ParameterTrees it is displayed in. (default=False)
title	(str or None) If specified, then the parameter will be displayed to the user using this string as its name. However, the parameter will still be referred to internally using the name specified above. Note that this option is not compatible with renamable=True. (default=None; added in version 0.9.9)

addChild(child, autoIncrementName=None)

Add another parameter to the end of this parameter’s child list.

See insertChild() for a description of the autoIncrementName argument.

addChildren(children)

Add a list or dict of children to this parameter. This method calls addChild once for each value in children.

blockTreeChangeSignal()

Used to temporarily block and accumulate tree change signals. You must remember to unblock, so it is advisable to use treeChangeBlocker() instead.

child(*names)

Return a child parameter. Accepts the name of the child or a tuple (path, to, child)

Added in version 0.9.9. Earlier versions used the ‘param’ method, which is still implemented for backward compatibility.

childPath(child)

Return the path of parameter names from self to child. If child is not a (grand)child of self, return None.

children()

Return a list of this parameter’s children. Warning: this overrides QObject.children

clearChildren()

Remove all child parameters.

contextMenu(name)

“A context menu entry was clicked

static create(**opts)

Static method that creates a new Parameter (or subclass) instance using opts[‘type’] to select the appropriate class.

All options are passed directly to the new Parameter’s __init__ method. Use registerParameterType() to add new class types.

defaultValue()

Return the default value for this parameter.

getValues()

Return a tree of all values that are children of this parameter

hasChildren()

Return True if this Parameter has children.

hasDefault()

Returns True if this parameter has a default value.

hide()

Hide this parameter. It and its children will no longer be visible in any ParameterTree widgets it is connected to.

insertChild(pos, child, autoIncrementName=None)

Insert a new child at pos. If pos is a Parameter, then insert at the position of that Parameter. If child is a dict, then a parameter is constructed using Parameter.create.

By default, the child’s ‘autoIncrementName’ option determines whether the name will be adjusted to avoid prior name collisions. This behavior may be overridden by specifying the autoIncrementName argument. This argument was added in version 0.9.9.

isType(typ)

Return True if this parameter type matches the name typ. This can occur either of two ways:

• If self.type() == typ

• If this parameter’s class is registered with the name typ

makeTreeItem(depth)

Return a TreeWidgetItem suitable for displaying/controlling the content of this parameter. This is called automatically when a ParameterTree attempts to display this Parameter. Most subclasses will want to override this function.

name()

Return the name of this Parameter.

parent()

Return the parent of this parameter.

parentChanged(parent)

This method is called when the parameter’s parent has changed. It may be useful to extend this method in subclasses.

readonly()

Return True if this parameter is read-only. (this is the opposite of writable())

remove()

Remove this parameter from its parent’s child list

removeChild(child)

Remove a child parameter.

restoreState(state, recursive=True, addChildren=True, removeChildren=True, blockSignals=True)

Restore the state of this parameter and its children from a structure generated using saveState() If recursive is True, then attempt to restore the state of child parameters as well. If addChildren is True, then any children which are referenced in the state object will be created if they do not already exist. If removeChildren is True, then any children which are not referenced in the state object will be removed. If blockSignals is True, no signals will be emitted until the tree has been completely restored. This prevents signal handlers from responding to a partially-rebuilt network.

saveState(filter=None)

Return a structure representing the entire state of the parameter tree. The tree state may be restored from this structure using restoreState().

If filter is set to ‘user’, then only user-settable data will be included in the returned state.

setDefault(val)

Set the default value for this parameter.

setLimits(limits)

Set limits on the acceptable values for this parameter. The format of limits depends on the type of the parameter and some parameters do not make use of limits at all.

setName(name)

Attempt to change the name of this parameter; return the actual name. (The parameter may reject the name change or automatically pick a different name)

setOpts(**opts)

Set any arbitrary options on this parameter. The exact behavior of this function will depend on the parameter type, but most parameters will accept a common set of options: value, name, limits, default, readonly, removable, renamable, visible, enabled, expanded and syncExpanded.

See Parameter.__init__ for more information on default options.

setReadonly(readonly=True)

Set whether this Parameter’s value may be edited by the user (this is the opposite of setWritable()).

setToDefault()

Set this parameter’s value to the default.

setValue(value, blockSignal=None)

Set the value of this Parameter; return the actual value that was set. (this may be different from the value that was requested)

setWritable(writable=True)

Set whether this Parameter should be editable by the user. (This is exactly the opposite of setReadonly).

show(s=True)

Show this parameter.

title()

Return the title of this Parameter.

By default, the title is the same as the name unless it has been explicitly specified otherwise.

treeChangeBlocker()

Return an object that can be used to temporarily block and accumulate sigTreeStateChanged signals. This is meant to be used when numerous changes are about to be made to the tree and only one change signal should be emitted at the end.

Example:

with param.treeChangeBlocker():
    param.addChild(...)
    param.removeChild(...)
    param.setValue(...)

treeStateChanged(param, changes)

Called when the state of any sub-parameter has changed.

Arguments:
param	The immediate child whose tree state has changed. note that the change may have originated from a grandchild.
changes	List of tuples describing all changes that have been made in this event: (param, changeDescr, data)

This function can be extended to react to tree state changes.

type()

Return the type string for this Parameter.

unblockTreeChangeSignal()

Unblocks enission of sigTreeStateChanged and flushes the changes out through a single signal.

value()

Return the value of this Parameter.

valueIsDefault()

Returns True if this parameter’s value is equal to the default value.

writable()

Returns True if this parameter’s value can be changed by the user. Note that the value of the parameter can always be changed by calling setValue().