<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<chapter id="gtk-migrating-GtkBuilder">

  <title>Migrating from libglade to GtkBuilder</title>

  <para>
    Since version 2.12, GTK+ provides #GtkBuilder to construct
    user interfaces from XML descriptions, similar to the functionality
    provided by #GladeXML in the libglade library.
  </para>

  <para>
    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 
    may want to split your glade file into multiple GtkBuilder files
    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>
    While GtkBuilder strives to be a complete replacement for
    libglade, there are a number of areas where it is currently
    still behind libglade:
    <itemizedlist>

      <listitem><para>
        GtkBuilder supports context information in translatable
        properties in a slightly different way than libglade. 
        Intltool does not yet support this; see 
        <ulink url="http://bugzilla.gnome.org/show_bug.cgi?id=454894">bug 
        454894</ulink> for the current status of intltool support for 
        GtkBuilder files. Thankfully, context in translations is a 
        rarely used feature, and if you are not using it, intltools 
        glade format support works just fine for GtkBuilder files.
      </para></listitem>

  </itemizedlist>
  </para>

  <para>
    More details about migrating from libglade to GtkBuilder will 
    appear here over time...
  </para>

</chapter>
