Gtk.Template

A GtkWidget subclass can use a GtkBuilder UI Definition XML document as a template to create child widgets and set its own properties, without creating a GtkBuilder instance. This is implemented for Python by PyGObject with Gtk.Template.

The subclass uses a @Gtk.Template decorator and declares a class variable __gtype_name__ with the value of the XML template element class attribute.

Child widgets are declared, typically with the same names as the XML object element id attributes, at the class level as instances of Gtk.Template.Child.

Signal handler methods, typically with the same names as the XML signal element handler attributes, use the @Gtk.Template.Callback decorator.

Gtk.Template() takes a mandatory keyword argument passing the XML document or its location, either string, filename or resource_path.

Gtk.Template.Child() and Gtk.Template.Callback() optionally take a name argument matching the value of the respective XML attribute, in which case the Python attribute can have a different name.

Examples

xml = """\
<interface>
  <template class="example1" parent="GtkBox">
    <child>
      <object class="GtkButton" id="hello_button">
        <property name="label">Hello World</property>
        <signal name="clicked" handler="hello_button_clicked" swapped="no" />
      </object>
    </child>
  </template>
</interface>
"""

@Gtk.Template(string=xml)
class Foo(Gtk.Box):
    __gtype_name__ = "example1"

    hello_button = Gtk.Template.Child()

    @Gtk.Template.Callback()
    def hello_button_clicked(self, *args):
        pass

Python attribute names that are different to the XML values:

@Gtk.Template(string=xml)
class Foo(Gtk.Box):
    __gtype_name__ = "example1"

    my_button = Gtk.Template.Child("hello_button")

    @Gtk.Template.Callback("hello_button_clicked")
    def bar(self, *args):
        pass

Subclasses that declare __gtype_name__ can be used as objects in the XML:

xml = """\
<interface>
  <template class="example3" parent="GtkBox">
    <child>
      <object class="ExampleButton" id="hello_button">
        <property name="label">Hello World</property>
        <signal name="clicked" handler="hello_button_clicked" swapped="no" />
      </object>
    </child>
  </template>
</interface>
"""


class HelloButton(Gtk.Button):
    __gtype_name__ = "ExampleButton"


@Gtk.Template(string=xml)
class Foo(Gtk.Box):
    __gtype_name__ = "example3"

    hello_button = Gtk.Template.Child()

    @Gtk.Template.Callback()
    def hello_button_clicked(self, *args):
        pass