A GnomeHello that works on GNOME2

When it comes to starting GNOME programming in C, a well written tutorial as GTK+ / Gnome Application Development is a good starting point. The author, Havoc Pennington, lists C source code (called GnomeHello) in the article as an example and readers are able to leverage it to construct their own GNOME applications.

When I started following the instruction — I'm thinking of developing my own 'toy application' —, what discouraged me is that Havoc's GnomeHello was based on GNOME 1.x, the old version of GNOME. Currently available GNOME is version 2, and its API has changed slightly, which caused compilation failure with verbatim copy of that GnomeHello source files. You need certainly modify some API function calls to fit the new GNOME2 API.

One more issue is that the build configuration Havoc illustrates is rather old style and it won't compile the GnomeHello application at all. And GNOME help system has changed from SGML to DocBook(XML) mechanism, which obsoletes the methodology of the instruction.

Moreover, internationalization (i18n) instruction is also incomplete. You want to consult other sources describing gettext/intltool to make translation of GnomeHello.

Coping with all the above issues, I managed to construct a buildable source tree of GnomeHello on Ubuntu 10.10(ja) and successfully made both help system and Japanese localization work. For everything to work, you have to 'make install' the source. You can donwload the tarball of this source tree at the end of this article. The rest of it addresses briefly the main points that I touched.

0) Development tools

I set up Ubuntu 10.10(ja) on ThinkPad R52 to start this work. Ubuntu installer doesn't put necessary development tools as default, so manual install is mandatory.

$ sudo apt-get update # If you want.
$ sudo apt-get install build-essential
$ sudo apt-get install libgtk2.0-dev
$ sudo apt-get install autoconf
$ sudo apt-get install automake
$ sudo apt-get install libtool
$ sudo apt-get install libglib2.0-dev
$ sudo apt-get install libgnome2-dev
$ sudo apt-get install autopoint
$ sudo apt-get install gnome-devel gnome-devel-docs

If you want Emacs23 as your preferable text editor like me, Put packages this way :

$ sudo apt-get install emacs23
$ sudo apt-get install emacs-goodies-el
$ sudo apt-get install emacs23-el

Note : Emacs23 on Ubuntu 10.10 Japanese Edition has *broad* width which has ThinkPad R52 screen all to itself. Ubuntu10.10 (Maverick Meerkat)と幅広なEmacs23 describes how to configure X to use Emacs in its right size.

Installed versions on my machine are :
gcc 4.4.5 (This is installed by default)
libgtk2.0-dev 2.22.0
autoconf 2.67
automake 1.11.1
libtool 2.2.6b
libglib2.0-dev 2.26.0
libgnome2-dev 2.32.0
autopoint 0.18.1
gnome-devel 2.28
gnome-devel-docs 2.30.1

1) hello.c

This file defines the main() function which is an entry point of this program. Firstly, i18n is correctly initialized with 2 another lines, and PACKAGE is replaced with GETTEXT_PACKAGE which is defind in configure.ac.

GNOME initialization the original source employs is old style of gnome_init() (or its variant gnome_init_with_popt_table() to process command line arguments). This way works, of course, to some degree. But if we want to refer to some program specific paths in C source files, such as data directory to locate pixmap files, gnome_program_init() [1.1] must be used. This way of initialization requires new methodology of command line parsing other than popt, so I also modified this part.

Window geometry processing came here in the main() (from hello_app_new()) because gnome_parse_geometry() is missing in GNOME2 API and is not available. Instead, after gtk_widget_show_all(), the program calls gtk_window_parse_geometry() [1.2] to process X window specific geometry initialization.

Reference :

2) menus.c

Simple GNOMEUIINFO_HELP() macro the original GnomeHello specifies won't work at all. This is partly because help system can't identify correct path of the help file, and partly because GNOME2 help system uses new methodology (DocBook XML) rather than the old SGML-HTML transformation paradaigm.

I replaced GNOMEUIINFO_HELP() with GNOMEUIINFO_ITEM_NONE() macro and placed a callback function help_cb() in it. In the callback, gnome_help_display_with_doc_id() [2.1] is called with DocBook XML filename specified. Build configuration must also be modified later on.

Reference :

3) app.c

gnome_parse_geometry() is missing in GNOME2 for some reason which I don't know of. I replaced it with gtk_window_parse_geometry() [3.1] and moved it in the main() funcion in hello.c since it must be called after all widgets are shown.

Reference :

4) autogen.sh

autogen.sh is supposed to reconfigure according to autoconf/automake input file changes. To write this script from scratch is a laborsome work, so simple copy from some existing source is a good choice. I copied gnome-autogen.sh in the gnome-common source package, renamed it autogen.sh in the top source tree of the GnomeHello. It works fine. You can view [4.1] and download [4.2] GNU sources.

Reference :
[4.1]All Projects
[4.2]Getting the most out of Git in GNOME

5) configure.ac

The original Havoc's GnomeHello describes configure.in. While grappling with GnomeHello, refering to a site (which I forgot where it was) describing functional macro for GNOME2, I renamed it to configure.ac. What is difference? Probably just the file name extension is. The initial configure.ac template is created with autoscan as usual. I added to this template GNOME, i18n(gettext/intltool), and DocBook(help) related macros. You may need to modify version strings in macros to fit your own.

6) Makefile.am
Basically, based on Havoc's explanation. I replaced GNOME compilation flags, added some macro definitions (DATADIR/LIBDIR/SYSCONFDIR/PREFIX) which can be refered (and will be refered later on ) in the C source files. Specifically, DATADIR is refered in menus.c, resolving pixmap file path with gnome_program_locate_file() [6.1] function in about_cb() callback to locate my poorly designed pixmap file. :(

Reference :

7) DocBook help

Help system has totally changed from GNOME 1 to 2 [7.1]. In GNOME1, document is SGML written and HTML file is generated during the build time. In GNOME2, DocBook XML is the help source and build makes localized version of the XML help document. If you want your native language localization, add your locale to configure.ac and doc/Makefile.am. I already marked with 'ja' (Japanese). At some point of build process, doc/ja.po is automatically created. Put your localization string here and make/make install will copy your localized version of help xml file to show in your program. If you are new to DocBook documentation, refer to [7.2].

Reference :>
[7.1] Migrating to GNOME Documentation Build Utilities>
[7.2] GNOME Handbook of Writing Software Documentation V1.0.2>

8) i18n issue

AM_GLIB_GNU_GETTEXT macro in configure.ac is obsolete. It won't work right. Instead, use AM_GNU_GETTEXT/AM_GNU_GETTEXT_VERSION [8.1]. In the beginning of main() function in hello.c, gettext initialization with several lines are done. But if you really want UTF-8 working, function call bind_textdomain_codeset() is mandatory [8.2].

As Havoc describes in the GnomeHello article, you need _() and N_() marking on all user-exposed strings. and to fetch all those i18n strings as a pot template, intltool is used in po/ directory [8.3]. Rename this generated template (.pot) to for example ja.po, and edit header. 'charset=UTF-8' line is important to make Emacs understand UTF-8 so as to begin string localization.

Reference :
[8.1]Use upstream gettext instead the glib one
[8.2]Internationalising GNOME applications
[8.3]Marking strings for translation

That's all there is to it. Why don't you set off your own GNOME application programming today?

GPL(GNU General Public License) v3 and the newest GFDL(GNU Free Documentation License)

C source tarball.

-Working Environment
Ubuntu 10.10