[gimp] devel-docs: Add gtkbuilder-porting-guide.txt

[Martin Nordholts <martinn src gnome org>]

commit c3b2e0e5646a6fe89e34734f1ed5831a8729e1d4
Author: Martin Nordholts <martinn src gnome org>
Date:   Sat Feb 13 12:25:29 2010 +0100

    devel-docs: Add gtkbuilder-porting-guide.txt
    
    Add guide giving a suggested workflow when porting C UI code to
    GtkBuilder UI declaration files.

 devel-docs/Makefile.am                  |   41 +++++----
 devel-docs/gtkbuilder-porting-guide.txt |  150 +++++++++++++++++++++++++++++++
 2 files changed, 171 insertions(+), 20 deletions(-)
---
diff --git a/devel-docs/Makefile.am b/devel-docs/Makefile.am
index d5ae510..0484d12 100644
--- a/devel-docs/Makefile.am
+++ b/devel-docs/Makefile.am
@@ -17,26 +17,27 @@ SUBDIRS = \
 	$(app)
 
 EXTRA_DIST = \
-	ChangeLog		\
-	README			\
-	README.gtkdoc		\
-	contexts.txt		\
-	debug-plug-ins.txt	\
-	exif-handling.txt	\
-	gbr.txt			\
-	ggr.txt  		\
-	gih.txt  		\
-	gpb.txt  		\
-	includes.txt		\
-	parasites.txt		\
-	pat.txt			\
-	release-howto.txt	\
-	structure.xml		\
-	submitting-patches.txt	\
-	tagging.txt		\
-	ui-framework.txt	\
-	undo.txt		\
-	vbr.txt			\
+	ChangeLog			\
+	README				\
+	README.gtkdoc			\
+	contexts.txt			\
+	debug-plug-ins.txt		\
+	exif-handling.txt		\
+	gbr.txt				\
+	ggr.txt  			\
+	gih.txt  			\
+	gpb.txt  			\
+	includes.txt			\
+	parasites.txt			\
+	pat.txt				\
+	gtkbuilder-porting-guide.txt	\
+	release-howto.txt		\
+	structure.xml			\
+	submitting-patches.txt		\
+	tagging.txt			\
+	ui-framework.txt		\
+	undo.txt			\
+	vbr.txt				\
 	xcf.txt
 
 
diff --git a/devel-docs/gtkbuilder-porting-guide.txt b/devel-docs/gtkbuilder-porting-guide.txt
new file mode 100644
index 0000000..2eb2c71
--- /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 how to port 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. Appearently 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>