Properties¶

Properties are part of a class and are defined through a 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 GObject.Object.list_properties() class method.

>>> 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 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 “_”.

>>> app = Gio.Application(application_id="foo.bar")

To get and set the property value see GObject.Object.get_property() and GObject.Object.set_property().

>>> 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:

>>> 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, 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.

>>> 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 GObject.Property decorator, which can be used similarly to the builtin Python property decorator:

GObject.Property(type=None, default=None, nick='', blurb='', flags=GObject.ParamFlags.READWRITE, minimum=None, maximum=None)¶

Parameters:

type (GObject.GType) – Either a GType, a type with a GType or a Python type which maps to a default GType
default (object) – A default value
nick (str) – Property nickname
block (str) – Short description
flags (GObject.ParamFlags) – Property configuration flags
minimum (object) – Minimum value, depends on the type
maximum (object) – Maximum value, depends on the type

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