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 True 12 vertical 12 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: ... 0