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 widgets/index
3dgraphics/index 3dgraphics/index
colormap colormap
parametertree/index parametertree/apiref
dockarea dockarea
graphicsscene/index graphicsscene/index
flowchart/index flowchart/index

View File

@ -3,17 +3,22 @@
Parameter Trees 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. 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. 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 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.
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 PyQtGraph's parameter tree system works similarly to the model-view architecture used by some components of Qt:
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.
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:: .. toctree::
:maxdepth: 2 :maxdepth: 2

View File

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

View File

@ -1,6 +1,40 @@
Built-in Parameter Types Built-in Parameter Types
======================== ========================
.. automodule:: pyqtgraph.parametertree.parameterTypes .. currentmodule:: pyqtgraph.parametertree.parameterTypes
Parameters
----------
.. autoclass:: SimpleParameter
:members: :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 = {} PARAM_NAMES = {}
def registerParameterType(name, cls, override=False): 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 global PARAM_TYPES
if name in PARAM_TYPES and not override: if name in PARAM_TYPES and not override:
raise Exception("Parameter type '%s' already exists (use override=True to replace)" % name) 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 ..Qt import QtCore, QtGui
from ..python2_3 import asUnicode from ..python2_3 import asUnicode
from .Parameter import Parameter, registerParameterType from .Parameter import Parameter, registerParameterType
@ -303,9 +304,27 @@ class EventProxy(QtCore.QObject):
class SimpleParameter(Parameter): 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 itemClass = WidgetParameterItem
def __init__(self, *args, **kargs): 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) Parameter.__init__(self, *args, **kargs)
## override a few methods for color parameters ## override a few methods for color parameters
@ -547,6 +566,21 @@ class ListParameterItem(WidgetParameterItem):
class ListParameter(Parameter): 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 itemClass = ListParameterItem
def __init__(self, **opts): def __init__(self, **opts):
@ -562,6 +596,7 @@ class ListParameter(Parameter):
self.setLimits(opts['limits']) self.setLimits(opts['limits'])
def setLimits(self, limits): def setLimits(self, limits):
"""Change the list of allowed values."""
self.forward, self.reverse = self.mapping(limits) self.forward, self.reverse = self.mapping(limits)
Parameter.setLimits(self, limits) Parameter.setLimits(self, limits)
@ -591,6 +626,7 @@ registerParameterType('list', ListParameter, override=True)
class ActionParameterItem(ParameterItem): class ActionParameterItem(ParameterItem):
"""ParameterItem displaying a clickable button."""
def __init__(self, param, depth): def __init__(self, param, depth):
ParameterItem.__init__(self, param, depth) ParameterItem.__init__(self, param, depth)
self.layoutWidget = QtGui.QWidget() self.layoutWidget = QtGui.QWidget()
@ -620,7 +656,10 @@ class ActionParameterItem(ParameterItem):
self.param.activate() self.param.activate()
class ActionParameter(Parameter): 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 itemClass = ActionParameterItem
sigActivated = QtCore.Signal(object) sigActivated = QtCore.Signal(object)
@ -632,6 +671,7 @@ registerParameterType('action', ActionParameter, override=True)
class TextParameterItem(WidgetParameterItem): class TextParameterItem(WidgetParameterItem):
"""ParameterItem displaying a QTextEdit widget."""
def __init__(self, param, depth): def __init__(self, param, depth):
WidgetParameterItem.__init__(self, param, depth) WidgetParameterItem.__init__(self, param, depth)
self.hideWidget = False self.hideWidget = False
@ -663,7 +703,7 @@ class TextParameterItem(WidgetParameterItem):
return self.textBox return self.textBox
class TextParameter(Parameter): 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 itemClass = TextParameterItem