devel-docs/gtkbuilder-porting-guide.txt

   1 gtkbuilder-porting-guide.txt
   2 ============================
   3
   4 This document describes some tips and rules for porting UI code
   5 written with GTK+ and C to GtkBuilder + Glade.
   6
   7
   8
   9 Overview
  10 --------
  11
  12 1. Locate code to port
  13 2. Start a new UI file with Glade
  14 3. Systematically convert the code to Glade
  15 4. Construct UI with GtkBuilder and do setup of widgets
  16 5. Add .ui file to build system
  17 6. Test
  18 7. Enjoy less UI C code
  19 8. Troubleshooting
  20
  21
  22
  23 Locate code to port
  24 -------------------
  25
  26 Look for code that looks like this:
  27
  28   // Create a widget and add to hierarchy
  29   widget = gtk_some_widget_new (some_params);
  30   gtk_some_container_add (container, widget)
  31   gtk_widget_show (widget);
  32
  33   // Repeat...
  34
  35
  36
  37 Start a new UI file with Glade
  38 ------------------------------
  39
  40 Start glade-3. Pick project file format 'GtkBuilder' (not
  41 'Libglade'). For maximum compatibility, use the minimal gtk+ catalog
  42 possible. The file extension shall be .ui. Look where other files are
  43 put and how they are named.
  44
  45
  46
  47 Systematically convert the code to Glade
  48 ----------------------------------------
  49
  50 Go through the code that you want to convert line by line and add
  51 widgets in Glade as you remove lines. For example:
  52
  53   main_vbox = gtk_vbox_new (FALSE, 12);
  54   gtk_container_set_border_width (GTK_CONTAINER (main_vbox), 12);
  55   gtk_container_add (GTK_CONTAINER (dialog_vbox),
  56                      main_vbox);
  57   gtk_widget_show (main_vbox);
  58
  59 is replaced by
  60
  61   <object class="GtkVBox" id="main-vbox">
  62     <property name="visible">True</property>
  63     <property name="border_width">12</property>
  64     <property name="orientation">vertical</property>
  65     <property name="spacing">12</property>
  66     <child>
  67       <!-- ... -->
  68     </child>
  69   </object>
  70
  71 in the UI declaration produced by Glade.
  72
  73
  74
  75 Construct UI with GtkBuilder and do setup of widgets
  76 ----------------------------------------------------
  77
  78 The code to construct the UI will look something like this:
  79
  80   builder = gtk_builder_new ();
  81   ui_file = g_build_filename (gimp_data_directory (),
  82                               "ui/plug-ins/plug-in-file-gif-save.ui",
  83                               NULL);
  84   if (! gtk_builder_add_from_file (builder, ui_file, &error))
  85     g_printerr (_("Error loading UI file '%s':\n%s"),
  86                 ui_file, error ? error->message : "???");
  87   g_free (ui_file);
  88
  89 and then you do setup of widgets using:
  90
  91   widget = GTK_WIDGET (gtk_builder_get_object (builder, "widget-name"));
  92   gtk_widget_whatever (widget, params);
  93
  94 Look in plug-ins/common/file-gif-save.c for helper function you can
  95 use for some tricky widgets.
  96
  97
  98
  99 Add .ui file to build system
 100 ----------------------------
 101
 102 The UI declarations are installed as data files, see
 103 plug-ins/ui/Makefile.am for example, and it needs to be added to
 104 POTFILES.in for translations.
 105
 106
 107
 108 Test
 109 ----
 110
 111 When you're done, make sure
 112
 113 1. that translations still work. If they don't, maybe you forgot to
 114 add the UI file to the relevant POTFILES.in or maybe you changed
 115 strings, for example by adding markup. In the latter case, use pango
 116 text styles instead of markup (use GKT+ 2.16 UI files).
 117
 118 2. that mnemonics still work, in particular when the mnemonic is not
 119 on the widget to be activated. For e.g. labels you need to explicitly
 120 assign a widget that will be actiated when the label mnemonic is
 121 pressed.
 122
 123 3. that the spacing and other layout detals are still correct.
 124
 125
 126
 127 Enjoy less UI C code
 128 --------------------
 129
 130 Enjoy!
 131
 132
 133
 134 Troubleshooting
 135 ---------------
 136
 137 If your GtkComboBox doesn't draw any items it's probably because it
 138 doesn't have a cell renderer. Appearently there is no UI to add one in
 139 GLade-3, so add it manually in the UI file, see the GTK+ doc for
 140 GtkCellLayout; this is what you need to add:
 141
 142 <object class="GtkComboBox" name="some-id">
 143   ...
 144   <child>
 145     <object class="GtkCellRendererText"/>
 146     <attributes>
 147       <attribute name="text">0</attribute>
 148     </attributes>
 149   </child>
 150 </object>