1 files changed, 150 insertions, 0 deletions
diff --git a/devel-docs/gtkbuilder-porting-guide.txt b/devel-docs/gtkbuilder-porting-guide.txt
new file mode 100644
index 0000000..43bbe09
--- /dev/null
+++ b/devel-docs/gtkbuilder-porting-guide.txt
@@ -0,0 +1,150 @@
+gtkbuilder-porting-guide.txt
+============================
+
+This document describes some tips and rules for porting UI code
+written with GTK+ and C to GtkBuilder + Glade.
+
+
+
+Overview
+--------
+
+1. Locate code to port
+2. Start a new UI file with Glade
+3. Systematically convert the code to Glade
+4. Construct UI with GtkBuilder and do setup of widgets
+5. Add .ui file to build system
+6. Test
+7. Enjoy less UI C code
+8. Troubleshooting
+
+
+
+Locate code to port
+-------------------
+
+Look for code that looks like this:
+
+  // Create a widget and add to hierarchy
+  widget = gtk_some_widget_new (some_params);
+  gtk_some_container_add (container, widget)
+  gtk_widget_show (widget);
+
+  // Repeat...
+
+
+
+Start a new UI file with Glade
+------------------------------
+
+Start glade-3. Pick project file format 'GtkBuilder' (not
+'Libglade'). For maximum compatibility, use the minimal gtk+ catalog
+possible. The file extension shall be .ui. Look where other files are
+put and how they are named.
+
+
+
+Systematically convert the code to Glade
+----------------------------------------
+
+Go through the code that you want to convert line by line and add
+widgets in Glade as you remove lines. For example:
+
+  main_vbox = gtk_vbox_new (FALSE, 12);
+  gtk_container_set_border_width (GTK_CONTAINER (main_vbox), 12);
+  gtk_container_add (GTK_CONTAINER (dialog_vbox),
+                     main_vbox);
+  gtk_widget_show (main_vbox);
+
+is replaced by
+
+  <object class="GtkVBox" id="main-vbox">
+    <property name="visible">True</property>
+    <property name="border_width">12</property>
+    <property name="orientation">vertical</property>
+    <property name="spacing">12</property>
+    <child>
+      <!-- ... -->
+    </child>
+  </object>
+
+in the UI declaration produced by Glade.
+
+
+
+Construct UI with GtkBuilder and do setup of widgets
+----------------------------------------------------
+
+The code to construct the UI will look something like this:
+
+  builder = gtk_builder_new ();
+  ui_file = g_build_filename (gimp_data_directory (),
+                              "ui/plug-ins/plug-in-file-gif-save.ui",
+                              NULL);
+  if (! gtk_builder_add_from_file (builder, ui_file, &error))
+    g_printerr (_("Error loading UI file '%s':\n%s"),
+                ui_file, error ? error->message : "???");
+  g_free (ui_file);
+
+and then you do setup of widgets using:
+
+  widget = GTK_WIDGET (gtk_builder_get_object (builder, "widget-name"));
+  gtk_widget_whatever (widget, params);
+
+Look in plug-ins/common/file-gif-save.c for helper function you can
+use for some tricky widgets.
+
+
+
+Add .ui file to build system
+----------------------------
+
+The UI declarations are installed as data files, see
+plug-ins/ui/Makefile.am for example, and it needs to be added to
+POTFILES.in for translations.
+
+
+
+Test
+----
+
+When you're done, make sure
+
+1. that translations still work. If they don't, maybe you forgot to
+add the UI file to the relevant POTFILES.in or maybe you changed
+strings, for example by adding markup. In the latter case, use pango
+text styles instead of markup (use GKT+ 2.16 UI files).
+
+2. that mnemonics still work, in particular when the mnemonic is not
+on the widget to be activated. For e.g. labels you need to explicitly
+assign a widget that will be actiated when the label mnemonic is
+pressed.
+
+3. that the spacing and other layout detals are still correct.
+
+
+
+Enjoy less UI C code
+--------------------
+
+Enjoy!
+
+
+
+Troubleshooting
+---------------
+
+If your GtkComboBox doesn't draw any items it's probably because it
+doesn't have a cell renderer. Apparently there is no UI to add one in
+GLade-3, so add it manually in the UI file, see the GTK+ doc for
+GtkCellLayout; this is what you need to add:
+
+<object class="GtkComboBox" name="some-id">
+  ...
+  <child>
+    <object class="GtkCellRendererText"/>
+    <attributes>
+      <attribute name="text">0</attribute>
+    </attributes>
+  </child>
+</object>