Merge branch 'cjmayo-template'

Author: sebp

examples/builder_example.glade

@@ -2,16 +2,16 @@
 <interface>
   <!-- interface-requires gtk+ 3.0 -->
   <object class="GtkWindow" id="window1">
-    <property name="can_focus">False</property>
+    <property name="can-focus">False</property>
     <signal name="destroy" handler="onDestroy" swapped="no"/>
     <child>
       <object class="GtkButton" id="button1">
         <property name="label" translatable="yes">button</property>
-        <property name="use_action_appearance">False</property>
+        <property name="use-action-appearance">False</property>
         <property name="visible">True</property>
-        <property name="can_focus">True</property>
-        <property name="receives_default">True</property>
-        <property name="use_action_appearance">False</property>
+        <property name="can-focus">True</property>
+        <property name="receives-default">True</property>
+        <property name="use-action-appearance">False</property>
         <signal name="pressed" handler="onButtonPressed" swapped="no"/>
       </object>
     </child>

examples/template_example.py

@@ -0,0 +1,23 @@
+import gi
+
+gi.require_version("Gtk", "3.0")
+from gi.repository import Gtk
+
+
+@Gtk.Template(filename="template_example.ui")
+class Window1(Gtk.Window):
+    __gtype_name__ = "window1"
+
+    @Gtk.Template.Callback()
+    def onDestroy(self, *args):
+        Gtk.main_quit()
+
+    @Gtk.Template.Callback()
+    def onButtonPressed(self, button):
+        print("Hello World!")
+
+
+window = Window1()
+window.show()
+
+Gtk.main()

examples/template_example.ui

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+  <!-- interface-requires gtk+ 3.0 -->
+  <template class="window1" parent="GtkWindow">
+    <signal name="destroy" handler="onDestroy" swapped="no"/>
+    <child>
+      <object class="GtkButton" id="button1">
+        <property name="label" translatable="yes">button</property>
+        <property name="use-action-appearance">False</property>
+        <property name="visible">True</property>
+        <property name="can-focus">True</property>
+        <property name="receives-default">True</property>
+        <property name="use-action-appearance">False</property>
+        <signal name="pressed" handler="onButtonPressed" swapped="no"/>
+      </object>
+    </child>
+  </template>
+</interface>

source/builder.txt

@@ -1,8 +1,8 @@
 Glade and Gtk.Builder
 =====================
 The :class:`Gtk.Builder` class offers you the opportunity to design user interfaces without writing a single line of code.
-This is possible through describing the interface by an XML file and then loading the XML description at runtime and create the objects automatically, which the Builder class does for you.
-For the purpose of not needing to write the XML manually the `Glade <https://glade.gnome.org/>`_ application lets you create the user interface in a WYSIWYG (what you see is what you get) manner
+This is achieved by defining the interface in an XML file and then loading that XML UI definition at runtime using the Builder class which creates the objects automatically.
+To avoid writing the XML manually use the `Glade <https://glade.gnome.org/>`_ application which lets you create the user interface in a WYSIWYG (what you see is what you get) manner
 
 This method has several advantages:
 
@@ -29,10 +29,10 @@ The resulting XML file should look like this.
         <child>
           <object class="GtkButton" id="button1">
             <property name="label" translatable="yes">button</property>
-            <property name="use_action_appearance">False</property>
+            <property name="use-action-appearance">False</property>
             <property name="visible">True</property>
-            <property name="can_focus">True</property>
-            <property name="receives_default">True</property>
+            <property name="can-focus">True</property>
+            <property name="receives-default">True</property>
           </object>
         </child>
       </object>
@@ -120,3 +120,20 @@ The final code of the example
 
 .. literalinclude:: ../examples/builder_example.py
     :linenos:
+
+Gtk.Template
+------------
+:class:`Gtk.WidgetClass` allows UI definition files to be used to extend a widget,
+PyGObject provides :doc:`guide/gtk_template` as a way of accessing this from Python.
+
+The UI definition file used in the example needs a small change to include a *<template>* element:
+
+.. literalinclude:: ../examples/template_example.ui
+    :language: xml
+
+Then it can be used to implement the example with a :class:`Gtk.Window` subclass:
+
+.. literalinclude:: ../examples/template_example.py
+    :linenos:
+
+More information can be found at the `PyGObject <https://pygobject.readthedocs.io/en/latest/guide/gtk_template.html>`_ website.