File: migrating-GtkBuilder.sgml

package info (click to toggle)
gtk%2B2.0 2.24.33-7
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid, trixie, trixie-proposed-updates, trixie-updates
  • size: 124,860 kB
  • sloc: ansic: 574,091; makefile: 5,171; sh: 4,618; xml: 1,193; python: 1,117; perl: 749; awk: 49; cpp: 34
file content (97 lines) | stat: -rw-r--r-- 3,562 bytes parent folder | download | duplicates (8)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
<?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 using
    <application>glade3</application> to convert your .glade file.
    If your code uses the @root parameter of glade_xml_new(),
    you can use gtk_builder_add_objects_from_file() to construct only certain
    objects from a GtkBuilder file.
  </para>

  <para>
    Alternatively, GTK+ also offers the
    <link linkend="gtk-builder-convert">gtk-builder-convert</link> script you can use
    to do the conversion; in which case you should be careful to inspect the output
    and make sure you didn't lose any data.
  </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: &percnt;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
    still behind libglade:
    <itemizedlist>

      <listitem><para>
        GtkBuilder supports context information in translatable
        properties in a slightly different way than libglade.
        Intltool does support this since version 0.41.1.
      </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>

</chapter>