# 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

To add widgets to the built-in child of a parent, describe the built-in widget in the XML with its `child` element having an `internal-child` attribute set to the name of the built-in widget:

    <interface>
      <template class="example2" parent="GtkDialog">
        <child internal-child="vbox">
          <object class="GtkBox">
            <child>
              <object class="GtkButton" id="hello_button">
                <property name="label">Hello World</property>
              </object>
            </child>
          </object>
        </child>
      </template>
    </interface>

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