Merge pull request #1527 from ixjlyons/improve-parameter-docs

Improve parametertree documentation coverage
This commit is contained in:
Ogi Moore 2021-01-30 11:01:08 -08:00 committed by GitHub
commit 56ee690d58
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 99 additions and 14 deletions

View File

@ -12,7 +12,7 @@ Contents:
widgets/index
3dgraphics/index
colormap
parametertree/index
parametertree/apiref
dockarea
graphicsscene/index
flowchart/index

View File

@ -3,17 +3,22 @@
Parameter Trees
===============
.. currentmodule:: pyqtgraph.parametertree
Parameter trees are a system for handling hierarchies of parameters while automatically generating one or more GUIs to display and interact with the parameters.
This feature is commonly seen, for example, in user interface design applications which display a list of editable properties for each widget.
Parameters generally have a name, a data type (int, float, string, color, etc), and a value matching the data type. Parameters may be grouped and nested
to form hierarchies and may be subclassed to provide custom behavior and display widgets.
Parameters generally have a name, a data type (int, float, string, color, etc), and a value matching the data type. Parameters may be grouped and nested to form hierarchies and may be subclassed to provide custom behavior and display widgets.
PyQtGraph's parameter tree system works similarly to the model-view architecture used by some components of Qt: Parameters are purely data-handling classes
that exist independent of any graphical interface. A ParameterTree is a widget that automatically generates a graphical interface which represents
the state of a haierarchy of Parameter objects and allows the user to edit the values within that hierarchy. This separation of data (model) and graphical
interface (view) allows the same data to be represented multiple times and in a variety of different ways.
PyQtGraph's parameter tree system works similarly to the model-view architecture used by some components of Qt:
For more information, see the 'parametertree' example included with pyqtgraph and the API reference
- A :class:`Parameter` is a purely data-handling class that exists independent of any graphical interface.
- A :class:`ParameterItem` is an interactive graphical representation of a :class:`Parameter`.
- A :class:`ParameterTree` is a widget that automatically generates a graphical interface which represents the state of a hierarchy of Parameter objects and allows the user to edit the values within that hierarchy.
This separation of data (model) and graphical interface (view) allows the same data to be represented multiple times and in a variety of different ways.
For example, a floating point number parameter could be represented by a slider or a spinbox, or both.
For more information, see the 'parametertree' example included with pyqtgraph and the API reference:
.. toctree::
:maxdepth: 2

View File

@ -1,8 +1,9 @@
Parameter
=========
.. autofunction:: pyqtgraph.parametertree.registerParameterType
.. autoclass:: pyqtgraph.parametertree.Parameter
:members:
.. automethod:: pyqtgraph.parametertree.Parameter.__init__

View File

@ -1,6 +1,40 @@
Built-in Parameter Types
========================
.. automodule:: pyqtgraph.parametertree.parameterTypes
:members:
.. currentmodule:: pyqtgraph.parametertree.parameterTypes
Parameters
----------
.. autoclass:: SimpleParameter
:members:
.. autoclass:: GroupParameter
:members:
.. autoclass:: ListParameter
:members:
.. autoclass:: TextParameter
:members:
.. autoclass:: ActionParameter
:members:
ParameterItems
--------------
.. autoclass:: WidgetParameterItem
:members:
.. autoclass:: GroupParameterItem
:members:
.. autoclass:: ListParameterItem
:members:
.. autoclass:: TextParameterItem
:members:
.. autoclass:: ActionParameterItem
:members:

View File

@ -9,6 +9,11 @@ PARAM_TYPES = {}
PARAM_NAMES = {}
def registerParameterType(name, cls, override=False):
"""Register a parameter type in the parametertree system.
This enables construction of custom Parameter classes by name in
:meth:`~pyqtgraph.parametertree.Parameter.create`.
"""
global PARAM_TYPES
if name in PARAM_TYPES and not override:
raise Exception("Parameter type '%s' already exists (use override=True to replace)" % name)

View File

@ -1,3 +1,4 @@
# -*- coding: utf-8 -*-
from ..Qt import QtCore, QtGui
from ..python2_3 import asUnicode
from .Parameter import Parameter, registerParameterType
@ -303,9 +304,27 @@ class EventProxy(QtCore.QObject):
class SimpleParameter(Parameter):
"""Parameter representing a single value.
This parameter is backed by :class:`WidgetParameterItem` to represent the
following parameter names:
- 'int'
- 'float'
- 'bool'
- 'str'
- 'color'
- 'colormap'
"""
itemClass = WidgetParameterItem
def __init__(self, *args, **kargs):
"""Initialize the parameter.
This is normally called implicitly through :meth:`Parameter.create`.
The keyword arguments avaialble to :meth:`Parameter.__init__` are
applicable.
"""
Parameter.__init__(self, *args, **kargs)
## override a few methods for color parameters
@ -547,6 +566,21 @@ class ListParameterItem(WidgetParameterItem):
class ListParameter(Parameter):
"""Parameter with a list of acceptable values.
By default, this parameter is represtented by a :class:`ListParameterItem`,
displaying a combo box to select a value from the list.
In addition to the generic :class:`~pyqtgraph.parametertree.Parameter`
options, this parameter type accepts a ``limits`` argument specifying the
list of allowed values. ``values`` is an alias and may be used instead.
The values may generally be of any data type, as long as they can be
represented as a string. If the string representation provided is
undesirable, the values may be given as a dictionary mapping the desired
string representation to the value.
"""
itemClass = ListParameterItem
def __init__(self, **opts):
@ -562,6 +596,7 @@ class ListParameter(Parameter):
self.setLimits(opts['limits'])
def setLimits(self, limits):
"""Change the list of allowed values."""
self.forward, self.reverse = self.mapping(limits)
Parameter.setLimits(self, limits)
@ -591,6 +626,7 @@ registerParameterType('list', ListParameter, override=True)
class ActionParameterItem(ParameterItem):
"""ParameterItem displaying a clickable button."""
def __init__(self, param, depth):
ParameterItem.__init__(self, param, depth)
self.layoutWidget = QtGui.QWidget()
@ -620,7 +656,10 @@ class ActionParameterItem(ParameterItem):
self.param.activate()
class ActionParameter(Parameter):
"""Used for displaying a button within the tree."""
"""Used for displaying a button within the tree.
``sigActivated(self)`` is emitted when the button is clicked.
"""
itemClass = ActionParameterItem
sigActivated = QtCore.Signal(object)
@ -632,6 +671,7 @@ registerParameterType('action', ActionParameter, override=True)
class TextParameterItem(WidgetParameterItem):
"""ParameterItem displaying a QTextEdit widget."""
def __init__(self, param, depth):
WidgetParameterItem.__init__(self, param, depth)
self.hideWidget = False
@ -663,7 +703,7 @@ class TextParameterItem(WidgetParameterItem):
return self.textBox
class TextParameter(Parameter):
"""Editable string; displayed as large text box in the tree."""
"""Editable string, displayed as large text box in the tree."""
itemClass = TextParameterItem