GtkBuilder and external objects

What if you want to reference an object you created from a GtkBuilder script? or even more add children to a container created outside the scope of GtkBuilder?

You can not!

But do not worry, a simple API like the following will allow us to reference any external object from builder.

void gtk_builder_expose_object (GtkBuilder *builder,
                                const gchar *name,
                                GObject *object);

Now consider a GtkBuilder script like this…

<interface>
  <object class="GtkButton" id="button">
    <property name="image" external-object="True">image</property>
    <signal name="clicked" handler="on_button_clicked"
     object="builder" external-object="yes"/>
  </object>
</interface>

All you have to do is tell builder which objects are external setting the “external-object” parameter then is as simple as calling gtk_builder_expose_object() to actually expose it.
Please note that the external-object parameter is needed to avoid naming space conflicts.

GtkWidget *image = gtk_image_new ();
GtkBuilder *builder = gtk_builder_new ();
gtk_builder_expose_object (builder, "image", G_OBJECT (image));
gtk_builder_expose_object (builder, "builder", G_OBJECT (builder));
gtk_builder_add_from_string (builder, buffer, -1, &error);

Ok but what about adding children to an existing container ?¿

The first idea was to use a fragment of builder xml format (basically the &ltchild&gt tag) and a new API gtk_builder_add_to_parent_*() but then I realize that would prevent us from setting properties on the external object and also it will not allow us to define anarchist objects that is objects outside the container hierarchy like for example a GtkAction.

So instead, I decided to add a new element: <template>

This new element is similar to <object> with the only difference it will be used as an entry point for the external object referenced by the template id.
Now with a template defined by this xml you can add children and set properties on an external object called “mybox”

<?xml version="1.0"?>
<interface>
  <!-- interface-requires gtk+ 3.0 -->
  <template class="GtkBox" id="mybox">
    <property name="visible">True</property>
    <property name="can_focus">False</property>
    <child>
      <object id="entry">
        <property name="visible">True</property>
        <property name="can_focus">True</property>
      </object>
      <packing>
        <property name="expand">False</property>
        <property name="fill">True</property>
        <property name="position">0</property>
      </packing>
    </child>
    <child>
      <object id="button">
        <property name="label">gtk-apply</property>
        <property name="visible">True</property>
        <property name="can_focus">True</property>
        <property name="receives_default">True</property>
        <property name="use_stock">True</property>
      </object>
      <packing>
        <property name="expand">False</property>
        <property name="fill">True</property>
        <property name="position">1</property>
      </packing>
    </child>
  </template>
</interface>

by simply using gtk_builder_add_from_string() in conjunction with gtk_builder_expose_object() like this:

builder = gtk_builder_new ();
mybox = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 0);
g_object_ref_sink (mybox);
gtk_builder_expose_object (builder, "mybox", G_OBJECT (mybox));
gtk_builder_add_from_string (builder, buffer, -1, &error);

Pretty simple is not it?

Patch available @ Bugzilla #688205 or if you prefer git this is the branch I been working on

git checkout -b composite-templates origin/composite-templates