Understanding Gtk template objects

While looking at the code for gnome-builder which is written in C using Gtk and other libraries, I found the following code for a shortcut window definition:

ide-shortcuts-window-private.h:

#pragma once
#include <gtk/gtk.h>

G_BEGIN_DECLS

#define IDE_TYPE_SHORTCUTS_WINDOW (ide_shortcuts_window_get_type())

G_DECLARE_FINAL_TYPE (IdeShortcutsWindow, ide_shortcuts_window, IDE, SHORTCUTS_WINDOW, GtkShortcutsWindow)

G_END_DECLS

ide-shortcuts-window.c:

#define G_LOG_DOMAIN "ide-shortcuts-window"
#include "config.h"

#include <glib/gi18n.h>

#include "ide-shortcuts-window-private.h"

struct _IdeShortcutsWindow
{
  GtkShortcutsWindow parent_instance;
};

G_DEFINE_TYPE (IdeShortcutsWindow, ide_shortcuts_window, GTK_TYPE_SHORTCUTS_WINDOW)

static void
ide_shortcuts_window_class_init (IdeShortcutsWindowClass *klass)
{
  GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (klass);

  gtk_widget_class_set_template_from_resource (widget_class, "/org/gnome/libide-gui/ui/ide-shortcuts-window.ui");
}

static void
ide_shortcuts_window_init (IdeShortcutsWindow *self)
{
  gtk_widget_init_template (GTK_WIDGET (self));
}

And this ui file which describes the window:

<?xml version="1.0" encoding="UTF-8"?>
<interface>
  <!-- interface-requires gtk+ 3.19 -->
  <template class="IdeShortcutsWindow">
    <property name="modal">true</property>
    <child>
      <object class="GtkShortcutsSection">
        <property name="visible">true</property>
        <property name="section-name">editor</property>
        <property name="title" translatable="yes" context="shortcut window">Editor Shortcuts</property>
        <child>
          <object class="GtkShortcutsGroup">
            <property name="visible">true</property>
            <property name="title" translatable="yes" context="shortcut window">General</property>
            <child>
              <object class="GtkShortcutsShortcut">
                <property name="visible">true</property>
                <property name="title" translatable="yes" context="shortcut window">Show help</property>
                <property name="accelerator">F1</property>
              </object>
            </child>
              ...............

I have built some Gtk applications before but I have never seen or used such a way of describing objects and I am having a hard time understanding this code. I know that the .ui file describes a template from which the structure IdeShortcutsWindow will be initialized. But I don't quite understand how to use it. Should I create an instance of the structure like so:

IdeShortcutsWindow shortcuts;

But then how do I initialize it? Should I call the functions defined in ide-shortcuts-window.c for the instance? While looking at the rest of the code I didn't find a single other place where an instance of IdeShortcutsWindow is used.

Solution

Should I create an instance of the structure like so: IdeShortcutsWindow shortcuts;

A new instance of the class is created with g_object_new (IDE_TYPE_SHORTCUTS_WINDOW, NULL). You can see the same in gnome-builder code.

Sometimes helper functions are provided to create new instances. Say for example: gtk_button_new () and g_object_new (GTK_TYPE_BUTTON, NULL) are the same. This is applicable to all GObjects and not specific to GtkBuilder templates.

See related documentations: 1 2

Please note that some_type_new() is a function that can be used only in C. Languages using GObject introspection bindings (eg: Python) shall only use g_object_new (...) to create new objects.

Personally I maintain a template project to help me easily develop GTK Applications, may be helpful for you: Link