Subclassing - PyGObject

Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Edit this page
Toggle table of contents sidebar

# Subclassing

Before entering in detail, you should know some important points about GObject subclassing:

1. It is possible to subclass a `GObject.Object`. Subclassing creates a new `GObject.GType` which is connected to the new Python type. This means you can use it with API which takes `GObject.GType`.

2. `GObject.Object` only supports single inheritance, this means you can only subclass one `GObject.Object`, but multiple Python classes.

3. The Python wrapper instance for a GObject.Object is always the same. For the same C instance you will always get the same Python instance.

## Inherit from GObject.GObject

A native GObject is accessible via `GObject.Object`. It is rarely instantiated directly, we generally use an inherited classes. A `Gtk.Widget` is an inherited class of a `GObject.Object`. It may be interesting to make an inherited class to create a new widget, like a settings dialog.

To inherit from `GObject.Object`, you must call super().__init__ in your constructor to initialize the gobjects you are inheriting, like in the example below:

    from gi.repository import GObject

    class MyObject(GObject.Object):

        def __init__(self):
            super().__init__(self)

You can also pass arguments to super().__init__, for example to change some property of your parent gobject:

    class MyWindow(Gtk.Window):

        def __init__(self):
            super().__init__(self, title='Custom title')

In case you want to specify the GType name we have to provide a `__gtype_name__`:

    class MyWindow(Gtk.Window):
        __gtype_name__ = 'MyWindow'

        def __init__(self):
            super().__init__(self)

## Properties

One of the nice features of GObject is its generic get/set mechanism for object properties. Any class that inherits from GObject.Object can define new properties. Each property has a type that never changes (e.g. `str`, `float`, `int`…).

### Create new properties

A property is defined with a name and a type. Even if Python itself is dynamically typed, you can’t change the type of a property once it is defined. A property can be created using `GObject.Property()`.

    from gi.repository import GObject

    class MyObject(GObject.Object):

        foo = GObject.Property(type=str, default='bar')
        property_float = GObject.Property(type=float)

        def __init__(self):
            super().__init__(self)

Properties can also be read-only, if you want some properties to be readable but not writable. To do so, you can add some flags to the property definition, to control read/write access. Flags are `GObject.ParamFlags.READABLE` (only read access for external code), `GObject.ParamFlags.WRITABLE` (only write access), `GObject.ParamFlags.READWRITE` (public):

    foo = GObject.Property(type=str, flags=GObject.ParamFlags.READABLE) # not writable
    bar = GObject.Property(type=str, flags=GObject.ParamFlags.WRITABLE) # not readable

You can also define new read-only properties with a new method decorated with `GObject.Property()`:

    from gi.repository import GObject

    class MyObject(GObject.Object):

        def __init__(self):
            super().__init__(self)

        @GObject.Property
        def readonly(self):
            return 'This is read-only.'

You can get this property using:

    my_object = MyObject()
    print(my_object.readonly)
    print(my_object.get_property('readonly'))

The API of `GObject.Property()` is similar to the builtin `property`. You can create property setters in a way similar to Python property:

    class AnotherObject(GObject.Object):
        value = 0

        @GObject.Property
        def prop(self):
            """Read only property."""
            return 1

        @GObject.Property(type=int)
        def prop_int(self):
            """Read-write integer property."""
            return self.value

        @prop_int.setter
        def prop_int(self, value):
            self.value = value

There is also a way to define minimum and maximum values for numbers:

    class AnotherObject(GObject.Object):
        value = 0

        @GObject.Property(type=int, minimum=0, maximum=100)
        def prop_int(self):
            """Integer property with min-max.'"""
            return self.value

        @prop_int.setter
        def prop_int(self, value):
            self.value = value

    my_object = AnotherObject()
    my_object.prop_int = 200  # This will fail

Alternatively you can use the more verbose __gproperties__ class attribute to define properties:

    from gi.repository import GObject

    class MyObject(GObject.Object):

        __gproperties__ = {
            'int-prop': (
                int, # type
                'integer prop', # nick
                'A property that contains an integer', # blurb
                1, # min
                5, # max
                2, # default
                GObject.ParamFlags.READWRITE # flags
            ),
        }

        def __init__(self):
            super().__init__(self)
            self.int_prop = 2

        def do_get_property(self, prop):
            if prop.name == 'int-prop':
                return self.int_prop
            else:
                raise AttributeError('unknown property %s' % prop.name)

        def do_set_property(self, prop, value):
            if prop.name == 'int-prop':
                self.int_prop = value
            else:
                raise AttributeError('unknown property %s' % prop.name)

For this approach properties must be defined in the `__gproperties__` class attribute, a dictionary, and handled in `GObject.Object.do_get_property()` and `GObject.Object.do_set_property()` virtual methods.

Hint

Changes to custom properties are also signaled by the `notify` detailed signal. But remember that it will normalize your property name to hyphens instead of underscores, so you will write `notify::prop-int` and not `notify::prop_int`.

## Signals

Each signal is registered in the type system together with the type on which it can be emitted: users of the type are said to connect to the signal on a given type instance when they register a function to be invoked upon the signal emission. Users can also emit the signal by themselves or stop the emission of the signal from within one of the functions connected to the signal.

### Create new signals

New signals can be created by using the `GObject.Signal()` decorator. The decorated methods are the object method handlers, these will be called when the signal is emitted.

The time at which the method handlers are invoked depends on the signal flags. `GObject.SignalFlags.RUN_FIRST` indicates that this signal will invoke the object method handler in the first emission stage. Alternatives are `GObject.SignalFlags.RUN_LAST` (the method handler will be invoked in the third emission stage) and `GObject.SignalFlags.RUN_CLEANUP` (invoke the method handler in the last emission stage).

Signals can also have arguments, the number and type of each argument is defined as a tuple of types.

Signals can be emitted using `GObject.Object.emit()`.

    from gi.repository import GObject

    class MyObject(GObject.Object):

        def __init__(self):
            super().__init__(self)

        @GObject.Signal(flags=GObject.SignalFlags.RUN_LAST, arg_types=(int,))
        def arg_signal(self, number):
            """Called every time the signal is emitted"""
            print('number:', number)

        @GObject.Signal
        def noarg_signal(self):
            """Called every time the signal is emitted"""
            print('noarg_signal')

    my_object = MyObject()

    def signal_callback(object_, number):
        """Called every time the signal is emitted until disconnection"""
        print(object_, number)

    my_object.connect('arg_signal', signal_callback)
    my_object.emit('arg_signal', 100)  # emit the signal "arg_signal", with the
                                       # argument 100

    my_object.emit('noarg_signal')

Alternatively you can use the more verbose __gsignals__ class attribute to define signals. When a new signal is created, a method handler can also be defined in the form of `do_signal_name`, it will be called each time the signal is emitted.

    class MyObject(GObject.Object):
        __gsignals__ = {
            'my_signal': (
                GObject.SignalFlags.RUN_FIRST,  # flag
                None,  # return type
                (int,)  # arguments
            )
        }

        def do_my_signal(self, arg):
            print("method handler for `my_signal' called with argument", arg)

## Virtual Methods

GObject and its based libraries usually have gobjects that expose virtual methods. These methods serve to override functionality of the base gobject or to run code on a specific scenario. In that case you should call the base gobject virtual method to preserve its original behavior.

In PyGObject these methods are prefixed with `do_`. Some examples are `GObject.Object.do_get_property()` or `Gio.Application.do_activate()`.

Important

The Python `super` class only works for the immediate parent. If you want to chain some virtual method from a object that is more up in the hierarchy of the one you are subclassing you must call the method directly from the object class: `SomeOject.method(self, args)`.

    class SomeOject(OtherObject):
        ...

    class MyObject(SomeOject):

        def __init__(self):
            super().__init__(self)

        def do_virtual_method(self):
            # Call the original method to keep its original behavior
            super().do_virtual_method(self)

            # Run some extra code
            ...

        """This is a virtual method from SomeOject parent"""
        def do_other(self):
            OtherObject.do_other(self)  # We can't use super()
            ...