Interfaces

GObject interfaces are a way of ensuring that objects passed to C code have the right capabilities.

When a GObject implements an interface it should implement an expected set of methods, properties and signals. In the Python sense, an interface is another class that is inherited.

For example in GTK, Gtk.Image supports various sources for the image that it will display. Some of these sources can be a Gio.Icon or a Gdk.Paintable, both are actually interfaces so you don’t pass a direct instance of these, instead you should use some of the gobjects that implement the interface. For Gio.Icon those can be Gio.ThemedIcon that represents an icon from the icon theme, or Gio.FileIcon that represents an icon created from an image file.

Another important interface of reference is Gio.ListModel. It represents a mutable list of GObject.Objects. If you want to implement Gio.ListModel you must implement three methods, these are Gio.ListModel.get_item_type(), Gio.ListModel.get_n_items() and Gio.ListModel.get_item(). The interfaces methods that you should implement are exposed as virtual methods. With these methods any consumer can iterate the list and use the objects for any purpose.

Tip

A generic implementation of Gio.ListModel is Gio.ListStore. It allows you to set the GObject.Object type that it will store and provides methods to append, insert, sort, find and remove gobjects.

Example

In this examples we’ll be implementing a Gio.ListModel in Python. It will store a custom GObject.Object and provide some helper methods for it.

from gi.repository import Gio, GObject


class Person(GObject.Object):
    __gtype_name__ = 'Person'

    name = GObject.Property(type=str)

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

        self.name = name


class PersonsModel(GObject.GObject, Gio.ListModel):
    __gtype_name__ = 'PersonsModel'

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

        # Private list to store the persons
        self._persons = []

    '''
    Interface Methods
    '''

    def do_get_item(self, position):
        return self._persons[position]

    def do_get_item_type(self):
        return Person

    def do_get_n_items(self):
        return len(self._persons)

    '''
    Our Helper Methods
    '''

    def add(self, person):
        self._persons.append(person)

        '''
        We must call Gio.ListModel.items_changed() every time we change the list.

        It's a helper to emit the "items-changed" signal, so consumer can know
        that the list changed at some point. We pass the position of the change,
        the number of removed items and the number of added items.
        '''
        self.items_changed(len(self._persons) - 1, 0, 1)

    def remove(self, position):
        del self._persons[position]
        self.items_changed(position, 1, 0)

    def get_index_by_name(self, name):
        for i, person in enumerate(self._persons):
            if person.name == name:
                return i

        return None