GTK+: Gnome cross platform GUI API programming Tips and Tricks

Free Information Technology Software and Development Magazine Subscriptions and Document Downloads

This tutorial will cover tips on using Gnome GTK+ (Gimp ToolKit) to build a GUI application for cross platform deployment. Suggestions, tips and pitfalls are noted about the use of various GTK+ components.

GTK+ is a multi-platform GUI API library which includes the standard interface widgets. It is a component of the GNOME desktop and applications development environment which also includes multi-platform API's for graphics, video, window management, XML parsing, a thread library, internationalization, database access and general desktop application development. There is a GUI interface builder, Glade which generates a GTK+ source code skeleton for rapid application development. The API's support the "C" computer language. I usually encapsulate these calls within C++ objects where convenient. There is also a C++ framework available known as "gtkmm".

GTK is published under the GPL license and thus is free to use and redistribute.

Linux:

• RPM:
  Systems which are Linux based will have GTK and Gnome as part of a regular install. The Gnome desktop and support services are NOT necessary to write a basic GTK+ GUI application.

  RedHat Linux RPMS's to install:

  • gtk2
  • gtk2-devel-2.XX
  • gtk2-engines
  • gtkhtml2-2.XX
  • gtkam
  • gtkam-gimp
  • gtkglarea
  • pango (Internationalized text handling)
  • atk (Accessibility Toolkit)
  • gdk-pixbuf-devel
  • gdk-pixbuf-gnome
  • gdk-pixbuf
  • glib
  • glade
  • freetype
  • fontconfig
  • fontconfig-devel
  Also requires tiff, png and jpeg libraries.

• Building GTK+ from source:
  The following must be done before configuring and building:
  • If installing to /opt, your PATH must include /opt/bin before /bin and /usr/bin if conflicting versions of pkgconfig are pressent.
    (export PATH=/opt/bin:$PATH)
  • Set the environment variable LD_LIBRARY_PATH to include /opt/lib.
    (export LD_LIBRARY_PATH=/opt/lib:$LD_LIBRARY_PATH)
  • Set environment variable PKG_CONFIG_PATH.
    (export PKG_CONFIG_PATH=/opt/lib/pkgconfig:/usr/lib/pkgconfig)

  Download the latest stable release from ftp://ftp.gtk.org/pub/gtk/. This requires downloading glib, atk, pango and gtk+ conpressed tar files. Also download from the "dependencies/" directory pkgconfig.

  Uncompress: tar -xzf pkgconfig-0.15.0.tar.gz glib-2.4.7.tar.gz pango-1.4.1.tar.gz atk-1.6.1.tar.gz gtk+-2.4.13.tar.gz

  For each subdirectory created configure and make:

  config-0.15.0
  ./configure --prefix=/opt
  make
  make install
  
  cd ../glib-2.4.7
  ./configure --prefix=/opt
  make
  make install
  
  cd ../pango-1.4.1
  ./configure --prefix=/opt
  make
  make install
  
  cd ../atk-1.6.1
  ./configure --prefix=/opt
  make
  make install
  
  cd ../gtk+-2.4.13
  ./configure --prefix=/opt
  make
  make install
  

  Also see GTK+ building reference.

  [Potential Pitfall]: Gtk+ configure error: "cofigure: error: Pango 1.2.0 and Xft backend is required for x11 target"
  Test for problem with: pkg-config --modversion pangoxft
  This command must return a version number or else this is an indication of a configuration problem.

  Actual problem is in configure of pango which gives error:

  ...
  checking for fontconfig >= 1.0.1... Package fontconfig was not found in the pkg-config search path.
  Perhaps you should add the directory containing `fontconfig.pc'
  to the PKG_CONFIG_PATH environment variable
  No package 'fontconfig' found
  configure: WARNING: No fontconfig found, skipping tests for FreeType and Xft
  ...
            

  Fix: Set environment variable PKG_CONFIG_PATH. (export PKG_CONFIG_PATH=/opt/lib/pkgconfig:/usr/lib/pkgconfig)
  This is so that the file fontconfig.pc can be located. This file is installed with the RPM fontconfig-devel. (required)

---

Microsoft Windows:

GTK can be compiled under Cygwin or Microsoft Visual C++.

MS/Windows install: I strongly recommend the GTK+ installer available from the Glade website:
MS/Windows GTK+ installer: http://gladewin32.sourceforge.net/

Two installers are available:

• gtk-win32-aio-2.4-rc16.exe: Installs the complete GTK development environment (headers, libraries, Glade GUI builder, GTK, GDK, Pango, etc.) Developers should use this installer to get the latest version of Glade.
• gtk-win32-2.4.6-rc2.exe: Installs GTK runtime environment.

GladWin32:

See: GladWin32: GTK+ GUI builder.

VC++ 6.0 Compiler/IDE:

If creating a new Visual C++ project:

• File + New and select "Win 32 Console Application". Enter a project name.
• The next dialog box allows one to define the type of application: Select "An empty project" + "Finish".

To add default include directories which can be referenced with <file.h> instead of "file.h": Tools + Options + select tab "Directories" + "include files".

Note: If using VC++ 6.0, update VC++ 6.0 to SP5. Download and run to expand to subdir. Then run setupsp5.exe

Visual C++ 6.0 configuration:

• Add sockets library to support htonl(): Select "Project" + "Settings..." + "Link". Add "Object/library module": ws2_32.lib
• GTK:
  VC++ compiler settings:
  • Project + Settings + C++ tab:
    Category: C++ Language Check "Enable exception handling".
    Category: Code Generation
    • Calling convention: _cdecl*
    • Struct member alignment: 8 byte.
    • Processor: Blend
    
    Category: Precompiled Headers Check not using
    Category: Preprocessor
    Additional Include directories: C:\GTK\Win32\include,C:\libxml2\Win32\include
  • Project + Settings + Link tab:
    • Category: General
      Object/library modules: glib-2.0.lib gobject-2.0.lib gthread-2.0.lib gdk-win32-2.0.lib gdk_pixbuf-2.0.lib gtk-win32-2.0.lib atk-1.0.lib pango-1.0.lib libxml2.lib
      Check: "Link incrementally"
    • Category: Input
      Additional library path: C:\GTK\Win32\lib,C:\libxml2\Win32\lib

System configuration:

• System Properties:
  • Select the "Advanced" tab.
  • Select the "Environment Variables ..." button.
  • In the "User Variables" frame, edit the environment variable "PATH" and add:
    C:\GTK\bin
  • Also set the following environment variables:
    

    Environment Variable
    LIB	c:\GTK\lib
    GTK_BASEPATH	c:\GTK
    INCLUDE	c:\GTK\INCLUDE;c:\GTK\GTK-2.0;c:\GTK\GLIB-2.0; c:\GTK\PANGO-1.0; c:\GTK\ATK-1.0; c:\GTK\GTKGLEXT-1.0; c:\GTK\GTK-2.0\INCLUDE; c:\GTK\GLIB-2.0\INCLUDE; c:\GTK\GTKGLEXT\INCLUDE; c:\GTK\INCLUDE\LIBGLADE-2.0; c:\GTK\INCLUDE\LIBXML2;

Also see the YoLinux tutorial on MS/Visual C++ best practices so that the mess that this IDE can create is kept to a minimum.

The basic framework of a GTK+ program requires:

• the include file: gtk/gtk.h
• callbacks used to close the principal window.
• main program.
• a call to gtk_init (&argc, &argv);
• instantiation of main window
• attach main window callbacks to main window. i.e. Callbacks to close window.
• a container widget to attach other widgets to the main window and begin the "widget tree".
• Attach widgets to parent components.
• render the widgets including the container widgets and principal window.
• a call to the main event loop: gtk_main ();

GTK is designed around a hierarchical class mechanism of widgets and objects of which GtkObject is the root. GtkObject provides the minimal set of information to support the GTK signal mechanism of callbacks which provide the functionality behind the GUI application. GTK is written in C and thus implements this mechanism with structures, composition and casting.

Casting allows one to view just the object info held in all objects without knowing the details of the widget or derived object. This principal is built-in to the GTK object and widget api.

GTK Widgets form a hierarchy of widgets joined together in a tree. Thus all widgets must be "linked" together with container or packing widgets to create this tree. It is this tree which is traversed for rendering of the GUI and for signal/callback handling. Thus an object which is "destroyed" will destroy the entire branch unless it is re-attached at some point in the hierarchy.

There are numerous widgets defined and available for use. One can also generate thier own widgets and compose widgets from combinations of other widgets.

Examples:

• Push Buttons
• Menu Widget
• Radio Button
• Check Button
• Scroll Bar
• Drawing Area
• Tree View
• Text View
• Text Entry Box
• Combo Box
• Scroll Bars (horizontal and vertical)

Signals can then be associated with a widget so that an action (i.e. button release) on a Button widget will invoke a callback function to be executed and perform the desired task (i.e. process or display something or both).

Container, Alignment and Packing widgets are used to place display widgets and other container widgets within a window frame. They do not take any form when rendered. (invisible)
Types:

• gtk_container_add()
  This will hold a single widget.

• gtk_alignment_new()
  Position a widget within it's window.
  Use the function gtk_alignment_set() to control layout and spacing.

• gtk_fixed_new()
  Fix widget position in window relative to upper left hand corner.
  Use the functions gtk_fixed_put(), gtk_fixed_move(), gtk_fixed_set_has_window() and gtk_fixed_get_has_window() to control layout.

• gtk_layout_new()
  Layout in infinite scrolling area.
  Use the functions gtk_layout_put(), gtk_layout_move(), gtk_layout_set_size(), gtk_layout_get_hadjustment(), gtk_layout_get_vadjustment(), gtk_layout_set_hadjustment() and gtk_layout_set_vadjustment() to control layout and spacing.

• gtk_hbox_new()
  Horizontal boxes
  
  Use the functions gtk_box_pack_start() and gtk_box_pack() to control layout and spacing.
  Also see gtk_hbutton_box_new().

• gtk_vbox_new()
  Vertical Boxes
  
  Use the functions gtk_box_pack_start() and gtk_box_pack() to control layout and spacing.
  Also see gtk_vbutton_box_new().

• gtk_table_new()
  Table
  
  Use the functions gtk_table_attach(), gtk_table_attach_defaults(), gtk_table_set_row_spacing(), gtk_table_set_col_spacing(), to control layout and spacing.

Signals allow for a routine to be called when a user interaction occurs. Use the routine g_signal_connect() to attach a "callback" function to a user interaction ("signal").

The signals have pre-defined names. Each widget has a defined list of signals which can act on the widget. For example, a "window" widget may have the signals:

• activate_focus
• frame_event
• move_focus
• ...

The widget also inherits the ability to receive a set of signals which all widgets can receive:

• delete_event
• button_press_event
• button_release_event
• expose_event
• hide_event
• show
• ...

Define the callback functions:

Associate the callback function to a user action performed on a specified widget:

The list of signals available are dependent on the widget. It is for this reason that the GUI builder Glade is very useful.

Passing C++ object to a Signal:

Signal inheritance:

The object oriented nature of GTK allows a widget to inherit the ability to receive signal types of the parents in its inheritance tree. Thus signals inherit pre-defined behaviors already configured in the GTK GUI and components. A signal daisy-chain is processed which executes the user defined signals and then processes the inherited signals. One may break this chain of events so that only your signal handlers are processed, To prevent inheritance of predefined signal behaviors, the signal function must return a boolean. Return "true" to break inheritance. Return "false" to maintain the behavior of predefined parent signals such that the chain of inherited signals are maintained and processed after your signal is processed.

Example:
GTK predefines the behavior of the up/down arrow keys for GUI focus navigation traversal of the interactive GUI control widgets. If using the up/down arrow within a text entry box we would need to deactivate the predefined navigation of the GUI by returning "true" to break the chain.

This example handles text entry and up/down arrows with two callbacks attached to the same widget.

Also see: GtkKeySnoopFunc()

• If trying to fix a crash, don't "gtk_widget_show()" a widget until it has been attached to a parent widget first.
  The widget structure is a tree hierarchy starting from the parent window and branching to each and every widget.

Change/assign button color:

(code snippet) OR:

---

Color declaration and assignment:

(code snippet)

Text labels can be placed anywhere on the GUI display. Placement is usually with a container such as "vbox" or "hbox". Note that the text can be modified using the html/xml tag "small".

Pango is the framework for layout and rendereing of internationalized text in GTK+. On Linux systems the final rendering is performed by X-Windows. Pango uses Unicode characters internally. Examples here use UTF-8 which is compatable with existing ASCII 8-bit software. Offsets in Pango are counted in bytes and not characters. While Pango was created to support non-Roman character languages like Japanese, Greek and Arabic, only English UTF-8 examples are shown.

Pango also supports a simple subset of HTML/XML for text attributes:

HTML Tag	Description
<b>	Bold
<big> or <span size="larger">	Increase font size
<small> or <span size="smaller">	Decrease font size
<i>	Italic
<s>	Strikethrough
<subs>	Subscript
<sup>	superscript
<tt>	Monospace Font
<u>	Underline
<span>	Use with attributes to specify rendering: font_desc: Shorthand label for font family, style, size, ... font_family: Name of font family. face: A font family attribute. size: # of thousandths of a point. style: normal, oblique, italic weight: ultralight, normal, heavy variant: normal, smallcaps stretch: ultracondensed, normal, ultraexpanded foreground: RGB color specification or color name. (i.e. #ff0000 or "red") background: RGB color specification or color name. (i.e. #0000ff or "blue") underline: single, double, low, none rise: position change in ten thousandths em. Subscript (-)ve, superscript (+)ve. strikethrough: true, false lang: Language code. Note: This also describes the set of Pango text attributes.

The XML tree root element tags are <markup> and </markup> but it is not necessary to reference or include them.

Example:

Pango converts HTML markup string into a text string and list of attributes and enables layout and rendering.

This converts the HTML representation of the text in "stringMarkupText" into text ("stringPlainText") and applied attributes "attrList".

Note: One may also use the equivalent GTK+ calls to gtk_label_set_markup() and the function above in the Text Labels example.

Result:

Links:

• Pango.org

The first series of examples are for the GTK text_entry and the second set briefly cover the GTK text_view widget. The text entry widget is preffered as it supports more features and fully supports view only functionality.

---

GTK Text Entry Widget:

Creates a new text entry/display widget.

Set entry text box background color:

See discussion of color definitions above.

Display entry text in green.

See discussion of color definitions above.

Modify entry text box style so text is BOLD:

Set entry text box size:

Set entry text box editable(default)/not editable:

Display text in the GTK text entry box widget.

Set display box as "insensitive". Display background as "grayed out" and disable user interaction.

Sensitivity:

• Sensitive: boolean set to true
  Interaction with widget (text entry widget) is allowed.
• Insensitive: boolean set to false
  Interaction with widget (text entry widget) is not allowed. Background is "grayed out".

One can also set the state to sensitive/insensitive using the routine gtk_widget_set_state().

Display tooltip when hovering text box:

GTK.org: Tooltips tutorial

Text display box with modified background and text:

Source code to this example: gtkTextEntryBox.c

---

Widgets and g_Threads:

Note: If updating the text with new data from a spawned GTK thread which listens to a socket or performs digital acquisition, one must protect the code segment with a GTK mutex. This must be applied to the calls in the spawned thread and not in the GUI main thread. This will avoid GUI update conflicts between gtk_main() and the GTK calls invoked in the thread. Thread support and stability is significantly improved in GTK+ 2.6.2.

The widget pointer text_entry_Widget is global to both the main thread and the spawned thread.

The required basic gdk threads framework:

gdk_threads_enter() is simply a wrapper function that locks the gdk_threads_mutex. Similarly, gdk_threads_leave() is a wrapper that unlocks the mutex. A look at the source of gtkmain.c shows that the lock is released while the main loop is running.

[Potential Pitfall]: You will create a deadlock condition if you try to update a widget before it has been realized.

---

GTK Text View Widget:

This is an alternate method of displaying text in a box. I prefer using a text entry widget as it has more available options.

See discussion of color definitions above.

The following code snippet shows how to embed and display an image within software. Any bitmap image (gif, jpeg, etc) can be converted to an "xpm" file using image manipulation software such as XV or Gimp and performing a "Save as ...".

[Potential Pitfall]: If your application core dumps when trying to employ pixmaps, try one of these clearly opposite solutions:

• Place "gtk_widget_show(window)" near the end just before gtk_main()
• Call "gtk_widget_show(window)" after declaration and attributes are set. (Fairly standard)

I have employed both solutions to fix a core dump. If one does not work try the other.

Transparent xpm include file: green_DOT.xpm

Embedding the pixmap in your display:

One may also read the XPM file using the function gtk_image_new_from_file(file-name) to generate a widget.

---

Using images to display status: It may be necessary to use pixmaps to display status thus changing the display. In this example we generate and display three color boxes (grey, red and green) but only display one at a time depending on which is relevant.

Generate the pixmap widgets: (See above discussion to see full source code.)

Attach all three pixmap widgets to the same location:

Callbacks to switch displays:

Display green box:

Display red box:

The three images are all located in the same place but only one is displayed at a time.

Source code to this example: gtkSwapPixmaps.c

Compile:

• gcc gtkSwapPixmaps.c -o gtkSwapPixmaps `pkg-config --cflags --libs gtk+-2.0`
  OR
• gcc gtkSwapPixmaps.c -o gtkSwapPixmaps -I/usr/include/gtk-2.0 -I/usr/lib/gtk-2.0/include -I/usr/include/atk-1.0 -I/usr/include/pango-1.0 -I/usr/X11R6/include -I/usr/include/freetype2 -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -Wl,--export-dynamic -lgtk-x11-2.0 -lgdk-x11-2.0 -latk-1.0 -lgdk_pixbuf-2.0 -lm -lpangoxft-1.0 -lpangox-1.0 -lpango-1.0 -lgobject-2.0 -lgmodule-2.0 -ldl -lglib-2.0

Creates a check box button. This button is not "grayed out" when insensitive but they are unselectable until the state is changed to GTK_STATE_SENSITIVE (default).

The GNOME GTK+ GUI builder Glade will generate a software skeleton for an application which is compilable and executable. Glade will also include many support routines which are useful whether you use Glade or not in the construction of your GTK+ application. These support routines are found in the Glade generated file src/support.c.

Glade lookup routine lookup_widget() (See Glade generated file src/support.c): Start at tree root "widget" and return "GtkWidget" corresponding to the "widget_name" (index to lookup table). If the widget tree root is given, then this routine can traverse the widget tree and return the GtkWidget pointer to the widget identified by name. This eliminates the need to pass all possible pointers used in processing but instead just pass around one, the root (i.e. main window) widget, and use lookup_widget() to locate all the others. Actually any widget can be passed as the routine will traverse the tree to first find the root ans then scan the tree. One must assign widget names using the Glade macro GLADE_HOOKUP_OBJECT. Glade will generate these associations in the generated file src/interface.c.

At the heart of the GLADE_HOOKUP_OBJECT macro is the GObject call g_object_set_data_full. This enables the association of text labels to widget pointers. One may add an association directly by using this routine.

The widget pointer can then be found using the widget identifier. i.e.:

The routine lookup_widget as generated by Glade in the file src/support.c.

• GTK Links:
  • GTK Home Page: http://gtk.org
    • http://gtk.org/tutorial1.2/
  • GNOME Developer Home Page http://developer.gnome.org
• Colors - resource file and widget states.
• PDF tutorial
• GTK for Windows: http://gladewin32.sourceforge.net - All in one installer (Ivan Wong)
• Widgets (not GTK native):
  • GtkSheet: Editable grid of cells for spreadsheet.
  • GtkPlot: Scientific plotting widget.

• YoLinux.com Tutorials:
  • GNOME libXML2 developer tutorial
  • GDK Threads
  • Python PyGTK GUI programming - GTK for Python
  • YoLinux software development tutorials

	"Developing Linux Applications with GTK+ and GDK" by Eric Harlow Pearson Education; 1st edition, ISBN# 0735700214 GTK+ 1.X
	"GTK+/Gnome Application Development" by Havoc Pennington Pearson Education; 1st edition, ISBN# 0735700788 GTK+ 1.X
	"Gtk+ Programming in C" by Syd Logan Prentice Hall PTR; 1st edition GTK+ 1.X