From c24d25bce3bd38f692253f61f19c1b2408101e17 Mon Sep 17 00:00:00 2001 From: Kenneth Lyons Date: Sat, 30 Jan 2021 10:06:49 -0800 Subject: [PATCH] Improve parametertree documentation - Increase cross-referencing - Give all built-in parameter and parameter items at least minimal docstring - Start improving coverage of the special options available for some parameters - Organize the built in parameters reference for easier navigation --- doc/source/apireference.rst | 2 +- doc/source/parametertree/index.rst | 19 +++++---- doc/source/parametertree/parameter.rst | 3 +- doc/source/parametertree/parametertypes.rst | 38 ++++++++++++++++- pyqtgraph/parametertree/Parameter.py | 5 +++ pyqtgraph/parametertree/parameterTypes.py | 46 +++++++++++++++++++-- 6 files changed, 99 insertions(+), 14 deletions(-) diff --git a/doc/source/apireference.rst b/doc/source/apireference.rst index c52c8df1..2392a65e 100644 --- a/doc/source/apireference.rst +++ b/doc/source/apireference.rst @@ -12,7 +12,7 @@ Contents: widgets/index 3dgraphics/index colormap - parametertree/index + parametertree/apiref dockarea graphicsscene/index flowchart/index diff --git a/doc/source/parametertree/index.rst b/doc/source/parametertree/index.rst index 94f590c3..1a6d5375 100644 --- a/doc/source/parametertree/index.rst +++ b/doc/source/parametertree/index.rst @@ -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 diff --git a/doc/source/parametertree/parameter.rst b/doc/source/parametertree/parameter.rst index b5326b91..fed39f3d 100644 --- a/doc/source/parametertree/parameter.rst +++ b/doc/source/parametertree/parameter.rst @@ -1,8 +1,9 @@ Parameter ========= +.. autofunction:: pyqtgraph.parametertree.registerParameterType + .. autoclass:: pyqtgraph.parametertree.Parameter :members: .. automethod:: pyqtgraph.parametertree.Parameter.__init__ - diff --git a/doc/source/parametertree/parametertypes.rst b/doc/source/parametertree/parametertypes.rst index 4344cee3..2ca29b37 100644 --- a/doc/source/parametertree/parametertypes.rst +++ b/doc/source/parametertree/parametertypes.rst @@ -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: diff --git a/pyqtgraph/parametertree/Parameter.py b/pyqtgraph/parametertree/Parameter.py index 4a2149b1..f90641d7 100644 --- a/pyqtgraph/parametertree/Parameter.py +++ b/pyqtgraph/parametertree/Parameter.py @@ -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) diff --git a/pyqtgraph/parametertree/parameterTypes.py b/pyqtgraph/parametertree/parameterTypes.py index 40262078..e8eb3173 100644 --- a/pyqtgraph/parametertree/parameterTypes.py +++ b/pyqtgraph/parametertree/parameterTypes.py @@ -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