mirror of https://github.com/GNOME/gimp.git
151 lines
3.8 KiB
Plaintext
151 lines
3.8 KiB
Plaintext
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. 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>
|