The GTK+ website offers a tutorial and a FAQ. More documentation ranging from whitepapers to online books can be found at the GNOME developer's site. After studying these materials you should be well prepared to come back to this reference manual for details.

See the documentation on this topic.

See the list of incompatible changes from 1.2 to 2.0. Also, the GNOME 2.0 porting guide on http://developer.gnome.org has some more detailed discussion of porting from 1.2 to 2.0. You may also find useful information in the documentation for specific widgets and functions.

If you have a question not covered in the manual, feel free to ask on the mailing lists and please file a bug report against the documentation.

See the documentation for GObject and GtkObject. For GObject note specifically g_object_ref() and g_object_unref(). GtkObject is a subclass of GObject so the same points apply, except that it has a "floating" state (explained in its documentation).

For strings returned from functions, they will be declared "const" (using G_CONST_RETURN) if they should not be freed. Non-const strings should be freed with g_free(). Arrays follow the same rule. (If you find an exception to the rules, please report a bug to http://bugzilla.gnome.org.)

If GtkFoo isn't a toplevel window, then

 foo = gtk_foo_new ();
 gtk_widget_destroy (foo);

is a memory leak, because no one assumed the initial floating reference. If you are using a widget and you aren't immediately packing it into a container, then you probably want standard reference counting, not floating reference counting.

To to get this, you must acquire a reference to the widget and drop the floating reference (“ref and sink” in GTK+ parlance) after creating it:

 foo = gtk_foo_new ();
 g_object_ref (foo); 
 gtk_object_sink (GTK_OBJECT (foo));

When you want to get rid of the widget, you must call gtk_widget_destroy() to break any external connections to the widget before dropping your reference:

 gtk_widget_destroy (foo); 
 g_object_unref (foo); 

When you immediately add a widget to a container, it takes care of assuming the initial floating reference and you don't have to worry about reference counting at all ... just call gtk_widget_destroy() to get rid of the widget.

This is covered in the GDK threads documentation. See also the GThread documentation for portable threading primitives.

Most people use GNU gettext, already required in order to install GLib. On a UNIX or Linux system with gettext installed, type info gettext to read the documentation.

The short checklist on how to use gettext is: call bindtextdomain() so gettext can find the files containing your translations, call textdomain() to set the default translation domain, then call gettext() to look up each string to be translated in the default domain. Conventionally, people define macros as follows for convenience:

  #define  _(x)  gettext (x)
  #define N_(x)  x

You use N_() (N stands for no-op) to mark a string for translation in a context where a function call to gettext() is not allowed, such as in an array initializer. You eventually have to call gettext() on the string to actually fetch the translation. _() both marks the string for translation and actually translates it.

Code using these macros ends up looking like this:

 #include <libintl.h>

 #define  _(x)  gettext (x)
 #define N_(x)  x

 static const char *global_variable = N_("Translate this string");

 static void
 make_widgets (void)
 {
    GtkWidget *label1;
    GtkWidget *label2;

    label1 = gtk_label_new (_("Another string to translate"));
    label2 = gtk_label_new (_(global_variable));
...

Libraries using gettext should use dgettext() instead of gettext(), which allows them to specify the translation domain each time they ask for a translation. Libraries should also avoid calling textdomain(), since they'll be specifying the domain instead of using the default. For dgettext() the _() macro can be defined as:

  #define _(x) dgettext ("MyDomain", x)

GTK+ uses Unicode (more exactly UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a sequence of one to six bytes and has a number of nice properties which make it a good choice for working with Unicode text in C programs:

More information about Unicode and UTF-8 can be found in the UTF-8 and Unicode FAQ for Unix/Linux. GLib provides functions for converting strings between UTF-8 and other encodings, see g_locale_to_utf8() and g_convert().

Text coming from external sources (e.g. files or user input), has to be converted to UTF-8 before being handed over to GTK+. The following example writes the content of a IS0-8859-1 encoded text file to stdout:

gchar *text, *utf8_text;
gsize length;
GError *error = NULL;

if (g_file_get_contents (filename, &text, &length, NULL)) 
  {
     utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1", 
                            NULL, NULL, &error);
     if (error != NULL)
       {
         fprintf ("Couldn't convert file %s to UTF-8\n", filename);
         g_error_free (error);
       }
     else
       g_print (utf8_text);
  }
else 
  fprintf (stderr, "Unable to read file %s\n", filename);

For string literals in the source code, there are several alternatives for handling non-ASCII content:

Here is an example showing the three approaches using the copyright sign © which has Unicode and ISO-8859-1 codepoint 169 and is represented in UTF-8 by the two bytes 194, 169:

g_print ("direct UTF-8: ©");
g_print ("escaped UTF-8: \302\251");
text = g_convert ("runtime conversion: ©", -1, "ISO-8859-1", "UTF-8", NULL, NULL, NULL);
g_print(text);
g_free (text);

There are two ways to approach this. The GTK+ header files use the subset of C that's also valid C++, so you can simply use the normal GTK+ API in a C++ program. Alternatively, you can use a "C++ binding" such as gtkmm which provides a C++-native API.

When using GTK+ directly, keep in mind that only functions can be connected to signals, not methods. So you will need to use global functions or "static" class functions for signal connections.

Another common issue when using GTK+ directly is that C++ will not implicitly convert an integer to an enumeration. This comes up when using bitfields; in C you can write the following code:

  gdk_window_set_events (gdk_window, 
                         GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);

while in C++ you must write:

  gdk_window_set_events (gdk_window, 
                         (GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);

There are very few functions that require this cast, however.

See the list of language bindings on http://www.gtk.org.

To load an image file straight into a display widget, use gtk_image_new_from_file() ^[1]. To load an image for another purpose, use gdk_pixbuf_new_from_file(). To load an animation, use gdk_pixbuf_animation_new_from_file(). gdk_pixbuf_animation_new_from_file() can also load non-animated images, so use it in combination with gdk_pixbuf_animation_is_static_image() to load a file of unknown type.

To load an image or animation file asynchronously (without blocking), use GdkPixbufLoader.

To draw a piece of text, use a Pango layout and gdk_draw_layout(), using code like the following:

 layout = gtk_widget_create_pango_layout (widget, text);
 fontdesc = pango_font_description_from_string ("Luxi Mono 12");
 pango_layout_set_font_description (layout, fontdesc); 
 gdk_draw_layout (..., layout);
 pango_font_description_free (fontdesc);
 g_object_unref (layout);

Do not use the deprecated GdkFont and gdk_draw_text().

See also the "Text Handling in GTK 2" section of Porting applications to the GNOME 2.0 platform.

To obtain the size of a piece of text, use a Pango layout and pango_layout_get_pixel_size(), using code like the following:

 layout = gtk_widget_create_pango_layout (widget, text);
 fontdesc = pango_font_description_from_string ("Luxi Mono 12");
 pango_layout_set_font_description (layout, fontdesc); 
 pango_layout_get_pixel_size (layout, &width, &height);
 pango_font_description_free (fontdesc);
 g_object_unref (layout);

Do not use the deprecated function gdk_text_width().

See also the "Text Handling in GTK 2" section of Porting applications to the GNOME 2.0 platform.

The GTK_TYPE_BLAH macros are defined as calls to gtk_blah_get_type(), and the _get_type() functions are declared as G_GNUC_CONST which allows the compiler to optimize the call away if it appears that the value is not being used.

A common workaround for this problem is to store the result in a volatile variable, which keeps the compiler from optimizing the call away.

volatile GType dummy = GTK_TYPE_BLAH;

See tree widget overview — you should use the GtkTreeView widget. (A list is just a tree with no branches, so the tree widget is used for lists as well.) Do not use the deprecated widgets GtkTree or GtkCList/GtkCTree in newly-written code, they are less flexible and result in an inferior user interface.

See text widget overview — you should use the GtkTextView widget. Do not use the deprecated widget GtkText in newly-written code, it has a number of problems that are best avoided.

If you only have a small amount of text, GtkLabel may also be appropriate of course. It can be made selectable with gtk_label_set_selectable(). For a single-line text entry, see GtkEntry.

GtkImage can display images in just about any format GTK+ understands. You can also use GtkDrawingArea if you need to do something more complex, such as draw text or graphics over the top of the image.

With GTK+, a GtkOptionMenu is recommended instead of a combo box, if the user is selecting from a fixed set of options. That is, non-editable combo boxes are not encouraged. GtkOptionMenu is much easier to use than GtkCombo as well. Use GtkCombo only when you need the editable text entry.

(As a future enhancement to GTK+, a new widget to replace GtkOptionMenu and GtkCombo is planned. This widget will be themeable to look like either a combo box or the current option menu, and will address some shortcomings in the GtkCombo API. Bug 50554 tracks this issue, if you want to check status or post comments.)

See gtk_widget_modify_fg(), gtk_widget_modify_bg(), gtk_widget_modify_base(), and gtk_widget_modify_text(). See GTK+ resource files for more discussion. You can also change widget color by installing a resource file and parsing it with gtk_rc_add_default_file(). The advantage of a resource file is that users can then override the color you've chosen.

To change the background color for widgets such as GtkLabel that have no background, place them in a GtkEventBox and set the background of the event box.

This has several possible answers, depending on what exactly you want to achieve. One option is gtk_widget_modify_font(). Note that this function can be used to change only the font size, as in the following example:

 PangoFontDesc *font_desc = pango_font_description_new ();
 pango_font_description_set_size (font_desc, 40);
 gtk_widget_modify_font (widget, font);
 pango_font_description_free (font_desc);

If you want to make the text of a label larger, you can use gtk_label_set_markup():

gtk_label_set_markup (label, "<big>big text</big>");

This is preferred for many apps because it's a relative size to the user's chosen font size. See g_markup_escape_text() if you are constructing such strings on the fly.

You can also change the font of a widget by putting

 gtk-font-name = "Sans 30"

in a resource file and parsing it with gtk_rc_add_default_file(). The advantage of a resource file is that users can then override the font you've chosen. See GTK+ resource files for more discussion.

In GTK+ a disabled widget is termed "insensitive." See gtk_widget_set_sensitive().

See gtk_text_buffer_get_bounds() and gtk_text_buffer_get_text() or gtk_text_iter_get_text().

  GtkTextIter start, end;
  GtkTextBuffer *buffer;
  char *text;

  buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (text_view));
  gtk_text_buffer_get_bounds (buffer, &start, &end);
  text = gtk_text_iter_get_text (&start, &end);
  /* use text */
  g_free (text);

If you use gtk_text_buffer_insert_with_tags() with appropriate tags to select the font, the inserted text will have the desired appearance, but text typed in by the user before or after the tagged block will appear in the default style.

To ensure that all text has the desired appearance, use gtk_widget_modify_font() to change the default font for the widget.

The "insert" mark marks the insertion point where gtk_text_buffer_insert() inserts new text into the buffer. The text is inserted before the "insert" mark, so that it generally stays at the end of the buffer. If it gets explicitly moved to some other position, e.g. when the user selects some text, use gtk_text_buffer_move_mark() to set it to the desired location before inserting more text. The "insert" mark of a buffer can be obtained with gtk_text_buffer_get_insert().

To ensure that the end of the buffer remains visible, use gtk_text_view_scroll_to_mark() to scroll to the "insert" mark after inserting new text.

Remember that the GtkTreeModel columns don't necessarily have to be displayed. So you can put non-user-visible data in your model just like any other data, and retrieve it with gtk_tree_model_get(). See the tree widget overview.

As there is no separate data column in the GtkTreeModel, there's no built in function to find the iter from data. You can write a custom searching function to walk the tree and find the data, or use gtk_tree_model_foreach().

You can pack more than one GtkCellRenderer into a single GtkTreeViewColumn using gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end(). So pack both a GtkCellRendererPixbuf and a GtkCellRendererText into the column.

Both the GtkTreeStore and the GtkListStore implement the GtkTreeModel interface. Consequentially, the can use any function this interface implements. The easiest way to read a set of data back is to use gtk_tree_model_get().

Use gtk_tree_view_insert_column_with_data_func() or gtk_tree_view_column_set_cell_data_func() and do the conversion from number to string yourself (with, say, g_strdup_printf()).

The following example demonstrates this:

enum 
{
  DOUBLE_COLUMN,
  N_COLUMNS
};

GtkListStore *mycolumns;
GtkTreeView *treeview;

void 
my_cell_double_to_text (GtkTreeViewColumn *tree_column,
	                GtkCellRenderer   *cell, 
                        GtkTreeModel      *tree_model,
	                GtkTreeIter       *iter, 
                        gpointer           data)
{
  GtkCellRendererText *cell_text = (GtkCellRendererText *)cell;
  gdouble d;
  gchar *text;

  /* Get the double value from the model. */
  gtk_tree_model_get (tree_model, iter, (gint)data, &d, -1);
  /* Now we can format the value ourselves. */
  text = g_strdup_printf ("%.2f", d);
  g_object_set (cell, "text", text, NULL);
  g_free (text);
}

void 
set_up_new_columns (GtkTreeView *myview)
{
  GtkCellRendererText *renderer;
  GtkTreeViewColumn *column;
  GtkListStore *mycolumns;

  /* Create the data model and associate it with the given TreeView */
  mycolumns = gtk_list_store_new (N_COLUMNS, G_TYPE_DOUBLE);
  gtk_tree_view_set_model (myview, GTK_TREE_MODEL (mycolumns));

  /* Create a GtkCellRendererText */
  renderer = gtk_cell_renderer_text_new ();

  /* Create a new column that has a title ("Example column"),
   * uses the above created renderer that will render the double
   * value into text from the associated model's rows. 
   */
  column = gtk_tree_view_column_new ();
  gtk_tree_view_column_set_title  (column, "Example column");
  renderer = gtk_cell_renderer_text_new ();
  gtk_tree_view_column_pack_start (column, renderer, TRUE);

  /* Append the new column after the GtkTreeView's previous columns. */
  gtk_tree_view_append_column (GTK_TREE_VIEW (myview), column);
  /* Since we created the column by hand, we can set it up for our
   * needs, e.g. set its minimum and maximum width, etc.
   */
  /* Set up a custom function that will be called when the column content
   * is rendered. We use the func_data pointer as an index into our
   * model. This is convenient when using multi column lists. 
   */
  gtk_tree_view_column_set_cell_data_func (column, renderer,
	                                   my_cell_double_to_text, 
                                           (gpointer)DOUBLE_COLUMN, NULL);
}