Properties — PyGObject

# 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