mirror of https://github.com/GNOME/gimp.git
devel-docs: Add gtkbuilder-porting-guide.txt
Add guide giving a suggested workflow when porting C UI code to GtkBuilder UI declaration files.
This commit is contained in:
parent
5c154c17dc
commit
c3b2e0e564
|
@ -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
|
||||
|
||||
|
||||
|
|
|
@ -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>
|
Loading…
Reference in New Issue