[gjs: 1/2] examples: add examples of GtkBuilder templates

[Philip Chimento <pchimento src gnome org>]

commit f7f280de86f5172c7bb386d0640776eca216790c
Author: Andy Holmes <andrew g r holmes gmail com>
Date:   Wed Apr 21 19:43:35 2021 -0700

    examples: add examples of GtkBuilder templates
    
    Add some basic examples of using GtkBuilder templates in GJS, with a
    few comments covering the few options available.

 examples/gtk3-template.js | 58 +++++++++++++++++++++++++++++++++++++++++++++
 examples/gtk3-template.ui | 44 ++++++++++++++++++++++++++++++++++
 examples/gtk4-template.js | 60 +++++++++++++++++++++++++++++++++++++++++++++++
 examples/gtk4-template.ui | 44 ++++++++++++++++++++++++++++++++++
 4 files changed, 206 insertions(+)
---
diff --git a/examples/gtk3-template.js b/examples/gtk3-template.js
new file mode 100644
index 00000000..0ba1dbf2
--- /dev/null
+++ b/examples/gtk3-template.js
@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MIT OR LGPL-2.0-or-later
+// SPDX-FileCopyrightText: 2021 Andy Holmes <andyholmes gnome org>
+
+imports.gi.versions.Gtk = '3.0';
+const {GObject, Gio, Gtk} = imports.gi;
+
+
+Gtk.init(null);
+
+
+/* In this example the template contents are loaded from the file as a string.
+ *
+ * The `Template` property of the class definition will accept:
+ *   - a `Uint8Array` or `GLib.Bytes` of XML
+ *   - an absolute file URI, such as `file:///home/user/window.ui`
+ *   - a GResource URI, such as `resource:///org/gnome/AppName/window.ui`
+ */
+const file = Gio.File.new_for_path('gtk3-template.ui');
+const [, template] = file.load_contents(null);
+
+
+const ExampleWindow = GObject.registerClass({
+    GTypeName: 'ExampleWindow',
+    Template: template,
+    Children: [
+        'box',
+    ],
+    InternalChildren: [
+        'button',
+    ],
+}, class ExampleWindow extends Gtk.Window {
+    _init(params = {}) {
+        super._init(params);
+
+        // The template has been initialized and you can access the children
+        this.box.visible = true;
+
+        // Internal children are set on the instance prefixed with a `_`
+        this._button.visible = true;
+    }
+
+    // The signal handler bound in the UI file
+    _onButtonClicked(button) {
+        if (this instanceof Gtk.Window)
+            log('Callback scope is bound to `ExampleWindow`');
+
+        button.label = 'Button was clicked!';
+    }
+});
+
+
+// Create a window that stops the program when it is closed
+const win = new ExampleWindow();
+win.connect('destroy', () => Gtk.main_quit());
+win.present();
+
+Gtk.main();
+
diff --git a/examples/gtk3-template.ui b/examples/gtk3-template.ui
new file mode 100644
index 00000000..254ed8e7
--- /dev/null
+++ b/examples/gtk3-template.ui
@@ -0,0 +1,44 @@
+<!-- SPDX-License-Identifier: MIT OR LGPL-2.0-or-later -->
+<!-- SPDX-FileCopyrightText: 2021 Andy Holmes <andyholmes gnome org> -->
+<interface>
+  <!-- Template
+
+    * class: must be the `GTypeName` given in the class definition, or the
+      class name prefixed with `Gjs_` if not given (eg `Gjs_ExampleWinow`)
+    * parent: the GType name of the derived class
+
+    -->
+  <template class="ExampleWindow" parent="GtkWindow">
+    <property name="default-width">480</property>
+    <property name="default-height">320</property>
+    <child>
+      <object class="GtkBox" id="box">
+        <property name="visible">True</property>
+        <child>
+          <object class="GtkButton" id="button">
+            <property name="label">Button</property>
+            <property name="halign">center</property>
+            <property name="hexpand">True</property>
+            <property name="valign">center</property>
+            <property name="visible">True</property>
+
+            <!-- Signals
+
+              * name: the signal name
+              * handler: the name of method on the subclass to call when emitted
+              * swapped: must always be "no" in GJS applications
+              * object: the object bound to `this` in the callback. This is
+                usually the template class (eg. `ExampleClass`) but may also be
+                an object ID (eg. `box` or `button`).
+
+              -->
+            <signal name="clicked"
+                    handler="_onButtonClicked"
+                    swapped="no"
+                    object="ExampleWindow"/>
+          </object>
+        </child>
+      </object>
+    </child>
+  </template>
+</interface>
diff --git a/examples/gtk4-template.js b/examples/gtk4-template.js
new file mode 100644
index 00000000..ac274f10
--- /dev/null
+++ b/examples/gtk4-template.js
@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: MIT OR LGPL-2.0-or-later
+// SPDX-FileCopyrightText: 2021 Andy Holmes <andyholmes gnome org>
+
+imports.gi.versions.Gtk = '4.0';
+const {GLib, GObject, Gio, Gtk} = imports.gi;
+
+
+Gtk.init();
+
+
+/* In this example the template contents are loaded from the file as a string.
+ *
+ * The `Template` property of the class definition will accept:
+ *   - a `Uint8Array` or `GLib.Bytes` of XML
+ *   - an absolute file URI, such as `file:///home/user/window.ui`
+ *   - a GResource URI, such as `resource:///org/gnome/AppName/window.ui`
+ */
+const file = Gio.File.new_for_path('gtk4-template.ui');
+const [, template] = file.load_contents(null);
+
+
+const ExampleWindow = GObject.registerClass({
+    GTypeName: 'ExampleWindow',
+    Template: template,
+    Children: [
+        'box',
+    ],
+    InternalChildren: [
+        'button',
+    ],
+}, class ExampleWindow extends Gtk.Window {
+    _init(params = {}) {
+        super._init(params);
+
+        // The template has been initialized and you can access the children
+        this.box.visible = true;
+
+        // Internal children are set on the instance prefixed with a `_`
+        this._button.visible = true;
+    }
+
+    // The signal handler bound in the UI file
+    _onButtonClicked(button) {
+        if (this instanceof Gtk.Window)
+            log('Callback scope is bound to `ExampleWindow`');
+
+        button.label = 'Button was clicked!';
+    }
+});
+
+
+// Create a window that stops the program when it is closed
+const loop = GLib.MainLoop.new(null, false);
+
+const win = new ExampleWindow();
+win.connect('close-request', () => loop.quit());
+win.present();
+
+loop.run();
+
diff --git a/examples/gtk4-template.ui b/examples/gtk4-template.ui
new file mode 100644
index 00000000..254ed8e7
--- /dev/null
+++ b/examples/gtk4-template.ui
@@ -0,0 +1,44 @@
+<!-- SPDX-License-Identifier: MIT OR LGPL-2.0-or-later -->
+<!-- SPDX-FileCopyrightText: 2021 Andy Holmes <andyholmes gnome org> -->
+<interface>
+  <!-- Template
+
+    * class: must be the `GTypeName` given in the class definition, or the
+      class name prefixed with `Gjs_` if not given (eg `Gjs_ExampleWinow`)
+    * parent: the GType name of the derived class
+
+    -->
+  <template class="ExampleWindow" parent="GtkWindow">
+    <property name="default-width">480</property>
+    <property name="default-height">320</property>
+    <child>
+      <object class="GtkBox" id="box">
+        <property name="visible">True</property>
+        <child>
+          <object class="GtkButton" id="button">
+            <property name="label">Button</property>
+            <property name="halign">center</property>
+            <property name="hexpand">True</property>
+            <property name="valign">center</property>
+            <property name="visible">True</property>
+
+            <!-- Signals
+
+              * name: the signal name
+              * handler: the name of method on the subclass to call when emitted
+              * swapped: must always be "no" in GJS applications
+              * object: the object bound to `this` in the callback. This is
+                usually the template class (eg. `ExampleClass`) but may also be
+                an object ID (eg. `box` or `button`).
+
+              -->
+            <signal name="clicked"
+                    handler="_onButtonClicked"
+                    swapped="no"
+                    object="ExampleWindow"/>
+          </object>
+        </child>
+      </object>
+    </child>
+  </template>
+</interface>