diff options
author | Christian Tismer <tismer@stackless.com> | 2021-04-30 15:20:32 +0200 |
---|---|---|
committer | Christian Tismer <tismer@stackless.com> | 2021-04-30 16:01:19 +0200 |
commit | 6a06abd970bc55ae3439897a7399c3acbfd5d0a7 (patch) | |
tree | d843decd6fcf57084994dfaf362bcea52472f38f /sources | |
parent | 6d2af409eedee377b3c2ba0cd8156b9409fabd9d (diff) |
Property: provide some hopefully exact documentation
Task-number: PYSIDE-1513
Pick-to: 5.15
Change-Id: I5817869aaf495f4005c4fda92d15fceafb15600a
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
Diffstat (limited to 'sources')
-rw-r--r-- | sources/pyside6/doc/extras/QtCore.Property.rst | 73 |
1 files changed, 70 insertions, 3 deletions
diff --git a/sources/pyside6/doc/extras/QtCore.Property.rst b/sources/pyside6/doc/extras/QtCore.Property.rst index ae61e44e4..5eb299f67 100644 --- a/sources/pyside6/doc/extras/QtCore.Property.rst +++ b/sources/pyside6/doc/extras/QtCore.Property.rst @@ -9,7 +9,9 @@ Detailed Description The Property function lets you declare properties that behave both as Qt and Python properties, and have their -setters and getters defined as Python functions. +getters and setters defined as Python functions. + +They are equivalent to the ``Q_PROPERTY`` macro in the `Qt Docs`_. Here is an example that illustrates how to use this function: @@ -20,14 +22,14 @@ function: from PySide6.QtCore import QObject, Property class MyObject(QObject): - def __init__(self,startval=42): + def __init__(self, startval=42): QObject.__init__(self) self.ppval = startval def readPP(self): return self.ppval - def setPP(self,val): + def setPP(self, val): self.ppval = val pp = Property(int, readPP, setPP) @@ -36,6 +38,68 @@ function: obj.pp = 47 print(obj.pp) +The full options for ``QtCore.Property`` can be found with ``QtCore.Property.__doc__``: + +.. code-block:: + + Property(self, type: type, + fget: Optional[Callable] = None, + fset: Optional[Callable] = None, + freset: Optional[Callable] = None, + fdel: Optional[Callable] = None, + doc: str = '', notify: Optional[Callable] = None, + designable: bool = True, scriptable: bool = True, + stored: bool = True, user: bool = False, + constant: bool = False, final: bool = False) -> PySide6.QtCore.Property + +Normally, only ``type``, ``fget``and ``fset`` are used. + + +Properties compared with Python properties +------------------------------------------ + +``Python`` has property objects very similar to ``QtCore.Property``. +Despite the fact that the latter has an extra ``freset`` function, the usage +of properties is almost the same. The main difference is that ``QtCore.Property`` +requires a ``type`` parameter. + +In the above example, the following lines would be equivalent properties: + +.. code-block:: + + pp = QtCore.Property(int, readPP, setPP) # PySide version + pp = property(readPP, setPP) # Python version + +As you know from the `Python Docs`_, ``Python`` allows to break the property +creation into multiple steps, using the decorator syntax. We can do this in +``PySide`` as well: + +.. code-block:: + :linenos: + + from PySide6.QtCore import QObject, Property + + class MyObject(QObject): + def __init__(self, startval=42): + QObject.__init__(self) + self.ppval = startval + + @Property(int) + def pp(self): + return self.ppval + + @pp.setter + def pp(self, val): + self.ppval = val + + obj = MyObject() + obj.pp = 47 + print(obj.pp) + +Please be careful here: The two ``Python`` functions have the same name, intentionally. +This is needed to let ``Python`` know that these functions belong to the same property. + + Properties in QML expressions ----------------------------- @@ -61,3 +125,6 @@ example illustrating how to do this: pass name = Property(str, _name, notify=name_changed) + +.. _`Python Docs`: https://docs.python.org/3/library/functions.html?highlight=property#property +.. _`Qt Docs`: https://doc.qt.io/qt-6/properties.html |