Expand GtkBuilder migration guide

docs/reference/gtk/migrating-GtkBuilder.sgml

@@ -16,14 +16,65 @@
     A good way to start a migration from libglade to GtkBuilder is
     to run the <link linkend="gtk-builder-convert">gtk-builder-convert</link>
     utility on your glade file, and inspect the resulting output.
-    If your code uses the @root parameter of glade_xml_new(), you 
+    If your code uses the @root parameter of glade_xml_new(), you
     may want to split your glade file into multiple GtkBuilder files
-    by using the <option>--root</option> option of 
+    by using the <option>--root</option> option of
     <application>gtk-builder-convert</application>. Alternatively, you
     can use gtk_builder_add_objects_from_file() to construct only certain
     objects from a GtkBuilder file.
   </para>
 
+  <para>
+    Alternatively, you can open the glade file with
+    <application>glade3</application> and then save it in GtkBuilder
+    format. This is supported by glade3 since version 3.6.
+  </para>
+
+  <table pgwide="1" frame="topbot">
+    <title>Step-by-step instructions for porting code from libglade to GtkBuilder</title>
+    <tgroup cols="2" colsep="0" rowsep="0">
+      <thead>
+        <row><entry>libglade</entry><entry>GtkBuilder</entry></row>
+      </thead>
+      <tbody>
+        <row>
+          <entry><![CDATA[#include <glade/glade.h>]]></entry>
+          <entry>not needed</entry>
+        </row>
+        <row>
+          <entry><screen>GladeXML*</screen></entry>
+          <entry><screen>GtkBuilder*</screen></entry>
+        </row>
+        <row>
+          <entry><screen>glade_xml_new (FILE, "first_widget", NULL)</screen></entry>
+          <entry>
+<screen>
+GError* error = NULL;
+GtkBuilder* builder = gtk_builder_new (<!-- -->);
+if (!gtk_builder_add_from_file (builder, FILE, &amp;error))
+  {
+    g_warning ("Couldn't load builder file: %s", error->message);
+    g_error_free (error);
+  }
+</screen>
+          </entry>
+        </row>
+        <row>
+          <entry><screen>glade_xml_get_widget (gxml, “widget_name”)</screen></entry>
+          <entry><screen>GTK_WIDGET (gtk_builder_get_object (builder, “widget_name”))</screen></entry>
+        </row>
+        <row>
+          <entry><screen>glade_get_widget_name (widget)</screen></entry>
+          <entry><screen>gtk_widget_get_name (widget)</screen></entry>
+        </row>
+        <row>
+          <entry><screen>glade_xml_get_widget_prefix (gxml, “prefix”)</screen></entry>
+          <entry>can be emulated by <literal>gtk_builder_get_objects (builder)</literal> together with manual filtering. It returns a GSList* instead of a GList* though.</entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </table>
+
   <para>
     While GtkBuilder strives to be a complete replacement for
     libglade, there are a number of areas where it is currently
@@ -32,21 +83,23 @@
 
       <listitem><para>
         GtkBuilder supports context information in translatable
-        properties in a slightly different way than libglade. 
+        properties in a slightly different way than libglade.
-        Intltool does not yet support this; see 
+        Intltool does not yet support this; see
-        <ulink url="http://bugzilla.gnome.org/show_bug.cgi?id=454894">bug 
+        <ulink url="http://bugzilla.gnome.org/show_bug.cgi?id=454894">bug
-        454894</ulink> for the current status of intltool support for 
+        454894</ulink> for the current status of intltool support for
-        GtkBuilder files. Thankfully, context in translations is a 
+        GtkBuilder files. Thankfully, context in translations is a
-        rarely used feature, and if you are not using it, intltools 
+        rarely used feature, and if you are not using it, intltools
         glade format support works just fine for GtkBuilder files.
       </para></listitem>
 
+      <listitem><para>
+        While libglade can often tolerate multiple widgets having the
+        same id in a glade file, GtkBuilder will not accept duplicate
+        object ids. Both <application>gtk-builder-convert</application>
+        and the GtkBuilder parser emit warnings when they see
+        duplicate ids.
+      </para></listitem>
   </itemizedlist>
   </para>
 
-  <para>
-    More details about migrating from libglade to GtkBuilder will 
-    appear here over time...
-  </para>
-
 </chapter>