Property

Detailed Description

The Property function lets you declare properties that behave both as Qt and Python properties, and have their 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:

 1 from PySide6.QtCore import QObject, Property
 2
 3 class MyObject(QObject):
 4     def __init__(self, startval=42):
 5         QObject.__init__(self)
 6         self.ppval = startval
 7
 8     def readPP(self):
 9         return self.ppval
10
11     def setPP(self, val):
12         self.ppval = val
13
14     pp = Property(int, readPP, setPP)
15
16 obj = MyObject()
17 obj.pp = 47
18 print(obj.pp)

The full options for QtCore.Property can be found with QtCore.Property.__doc__:

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:

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:

 1 from PySide6.QtCore import QObject, Property
 2
 3 class MyObject(QObject):
 4     def __init__(self, startval=42):
 5         QObject.__init__(self)
 6         self.ppval = startval
 7
 8     @Property(int)
 9     def pp(self):
10         return self.ppval
11
12     @pp.setter
13     def pp(self, val):
14         self.ppval = val
15
16 obj = MyObject()
17 obj.pp = 47
18 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

If you are using properties of your objects in QML expressions, QML requires that the property changes are notified. Here is an example illustrating how to do this:

 1 from PySide6.QtCore import QObject, Signal, Property
 2
 3 class Person(QObject):
 4     def __init__(self, name):
 5         QObject.__init__(self)
 6         self._person_name = name
 7
 8     def _name(self):
 9         return self._person_name
10
11     @Signal
12     def name_changed(self):
13         pass
14
15     name = Property(str, _name, notify=name_changed)