1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
==========
Properties
==========
Properties are part of a class and are defined through a
:obj:`GObject.ParamSpec`, which contains the type, name, value range and so
on.
To find all the registered properties of a class you can use the
:meth:`GObject.Object.list_properties` class method.
.. code:: pycon
>>> Gio.Application.list_properties()
[<GParamString 'application-id'>, <GParamFlags 'flags'>, <GParamString
'resource-base-path'>, <GParamBoolean 'is-registered'>, <GParamBoolean
'is-remote'>, <GParamUInt 'inactivity-timeout'>, <GParamObject
'action-group'>, <GParamBoolean 'is-busy'>]
>>> param = Gio.Application.list_properties()[0]
>>> param.name
'application-id'
>>> param.owner_type
<GType GApplication (94881584893168)>
>>> param.value_type
<GType gchararray (64)>
>>>
The :obj:`GObject.Object` contructor takes multiple properties as keyword
arguments. Property names usually contain "-" for seperating words. In Python
you can either use "-" or "_". In this case variable names don't allow "-", so
we use "_".
.. code:: pycon
>>> app = Gio.Application(application_id="foo.bar")
To get and set the property value see :meth:`GObject.Object.get_property` and
:meth:`GObject.Object.set_property`.
.. code:: pycon
>>> app = Gio.Application(application_id="foo.bar")
>>> app
<Gio.Application object at 0x7f7499284fa0 (GApplication at 0x564b571e7c00)>
>>> app.get_property("application_id")
'foo.bar'
>>> app.set_property("application_id", "a.b")
>>> app.get_property("application-id")
'a.b'
>>>
Each instance also has a ``props`` attribute which exposes all properties
as instance attributes:
.. code:: pycon
>>> from gi.repository import Gtk
>>> button = Gtk.Button(label="foo")
>>> button.props.label
'foo'
>>> button.props.label = "bar"
>>> button.get_label()
'bar'
>>>
To track changes of properties, :obj:`GObject.Object` has a special ``notify``
signal with the property name as the detail string. Note that in this case you
have to give the real property name and replacing "-" with "_" wont work.
.. code:: pycon
>>> app = Gio.Application(application_id="foo.bar")
>>> def my_func(instance, param):
... print("New value %r" % instance.get_property(param.name))
...
>>> app.connect("notify::application-id", my_func)
11L
>>> app.set_property("application-id", "something.different")
New value 'something.different'
>>>
You can define your own properties using the :obj:`GObject.Property` decorator,
which can be used similarly to the builtin Python :any:`property` decorator:
.. function:: GObject.Property(type=None, default=None, nick='', blurb='', \
flags=GObject.ParamFlags.READWRITE, minimum=None, maximum=None)
:param GObject.GType type: Either a GType, a type with a GType or a
Python type which maps to a default GType
:param object default: A default value
:param str nick: Property nickname
:param str block: Short description
:param GObject.ParamFlags flags: Property configuration flags
:param object minimum: Minimum value, depends on the type
:param object maximum: Maximum value, depends on the type
.. code:: python
class AnotherObject(GObject.Object):
value = 0
@GObject.Property
def prop_pyobj(self):
"""Read only property."""
return object()
@GObject.Property(type=int)
def prop_gint(self):
"""Read-write integer property."""
return self.value
@prop_gint.setter
def prop_gint(self, value):
self.value = value
|
