## Common Questions

Common Questions — Find answers to common questions in the GTK+ manual

## Questions and Answers

This is an "index" of the reference manual organized by common "How do I..." questions. If you aren't sure which documentation to read for the question you have, this list is a good place to start.

##### 1. General

1.1. | How do I get started with GTK+?
| 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.
1.2. | Where can I get help with GTK+, submit a bug report, or make a feature request?
| See the documentation on this topic.
1.3. | How do I port from one GTK+ version to another?

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.

1.4. | How does memory management work in GTK+? Should I free data returned from functions?

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.)

1.5. | Why does my program leak memory, if I destroy a widget immediately after creating it ?

If GtkFoo isn't a toplevel window, then

    1
    2

    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:

    1
    2
    3

    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:

    1
    2

    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.

1.6. | How do I use GTK+ with threads?
| This is covered in the GDK threads documentation. See also the GThread documentation for portable threading primitives.
1.7. | How do I internationalize a GTK+ program?

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, call `bind_textdomain_codeset()` to request that all translated strings are returned in UTF-8, then call `gettext()` to look up each string to be translated in the default domain. Conventionally, people define macros as follows for convenience:

    1
    2

    #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.

Nowadays, GLib provides the common shorthand macros in the header file `gi18n.h`, so you don't have to define them yourself, just include that header.

Code using these macros ends up looking like this:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13

    #include <gi18n.h>

    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 will be specifying the domain instead of using the default. For `dgettext()` the `_()` macro can be defined as:

    1

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

Again, GLib comes with the `gi18n-lib.h`, saving you the trouble of defining the macros by hand. The macros in that header expect the translation domain to be specified by the `GETTEXT_PACKAGE` macro.

1.8. | How do I use non-ASCII characters in GTK+ programs ?

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:

- ASCII characters are encoded by their familiar ASCII codepoints.

- ASCII characters never appear as part of any other character.

- The zero byte doesn't occur as part of a character, so that UTF-8 strings can be manipulated with the usual C library functions for handling zero-terminated strings.

More information about Unicode and UTF-8 can be found in the UTF-8 and Unicode i 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`:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18

    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:

direct UTF-8 | If your editor and compiler are capable of handling UTF-8 encoded sources, it is very convenient to simply use UTF-8 for string literals, since it allows you to edit the strings in "wysiwyg". Note that choosing this option may reduce the portability of your code.
escaped UTF-8 | Even if your toolchain can't handle UTF-8 directly, you can still encode string literals in UTF-8 by using octal or hexadecimal escapes like `\212` or `\xa8` to encode each byte. This is portable, but modifying the escaped strings is not very convenient. Be careful when mixing hexadecimal escapes with ordinary text; `"\xa8abcd"` is a string of length 1 !
runtime conversion | If the string literals can be represented in an encoding which your toolchain can handle (e.g. IS0-8859-1), you can write your source files in that encoding and use `g_convert()` to convert the strings to UTF-8 at runtime. Note that this has some runtime overhead, so you may want to move the conversion out of inner loops.

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:

    1
    2
    3
    4
    5

    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);

If you are using `gettext()` to localize your application, you need to call `bind_textdomain_codeset()` to ensure that translated strings are returned in UTF-8 encoding.

1.9. | How do I use GTK+ with C++?

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 native C++ 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:

    1
    2

    gdk_window_set_events (gdk_window,
                           GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);

while in C++ you must write:

    1
    2

    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.

1.10. | How do I use GTK+ with other non-C languages?
| See the list of language bindings on http://www.gtk.org.
1.11. | How do I load an image or animation from a file?

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 i 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.

1.12. | How do I draw text ?

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

    1
    2
    3
    4
    5
    6

    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.

1.13. | How do I measure the size of a piece of text ?

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

    1
    2
    3
    4
    5
    6

    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.

1.14. | Why are types not registered if I use their `GTK_TYPE_BLAH` macro ?

The `GTK_TYPE_BLAH` macros are defined as calls to ``gtk_blah_get_type()``, and the ``_get_type()`` i 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.

    1

    volatile GType dummy = GTK_TYPE_BLAH;

1.15. | How do I create a transparent toplevel window ?

To make a window transparent, it needs to use a visual which supports that. This is done by getting the RGBA colormap of the screen with `gdk_screen_get_rgba_colormap()` and setting it on the window. Note that `gdk_screen_get_rgba_colormap()` will return `NULL` if transparent windows are not supported on the screen; also note that this may change from screen to screen, so it needs to be repeated whenever the window is moved to a different screen.

    1
    2
    3
    4
    5
    6
    7

    GdkColormap *colormap;

    colormap = gdk_screen_get_rgba_colormap (screen);
    if (!colormap)
      colormap = gdk_screen_get_rgb_colormap (screen);

    gtk_widget_set_colormap (widget, colormap);

One possibility to fill the alpha channel on the window is to use `gdk_draw_rgb_32_image()`.

Note that the presence of an RGBA visual is no guarantee that the window will actually appear transparent on screen. On X11, this requires a compositing manager to be running. See `gtk_widget_is_composited()` for a way to find out if the alpha channel will be respected.

##### 2. Which widget should I use...

2.1. | ...for lists and trees?
| 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.
2.2. | ...for multi-line text display or editing?
| 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.
2.3. | ...to display an image or animation?
| 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.
2.4. | ...for presenting a set of mutually-exclusive choices, where Windows would use a combo box?
| With GTK+, a GtkComboBox is the recommended widget to use for this use case. This widget looks like either a combo box or the current option menu, depending on the current theme. If you need an editable text entry, use GtkComboBoxEntry.

##### 3. GtkWidget

3.1. | How do I change the color of a widget?

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.

3.2. | How do I change the font of a widget?

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 have chosen. See GTK+ resource files for more discussion.

3.3. | How do I disable/ghost/desensitize a widget?
| In GTK+ a disabled widget is termed "insensitive." See `gtk_widget_set_sensitive()`.

##### 4. GtkTextView

4.1. | How do I get the contents of the entire text widget as a string?

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

    1
    2
    3
    4
    5
    6
    7
    8
    9

    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);

4.2. | How do I make a text widget display its complete contents in a specific font?
| 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.
4.3. | How do I make a text view scroll to the end of the buffer automatically ?

A good way to keep a text buffer scrolled to the end is to place a mark at the end of the buffer, and give it right gravity. The gravity has the effect that text inserted at the mark gets inserted before, keeping the mark at the end.

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

The gtk-demo application contains an example of this technique.

##### 5. GtkTreeView

5.1. | How do I associate some data with a row in the tree?
| 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.
5.2. | What's the GtkTreeView equivalent of `gtk_clist_find_row_from_data()`?
| 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()`.
5.3. | How do I put an image and some text in the same column?
| 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.
5.4. | I can set data easily on my GtkTreeStore/GtkListStore models using `gtk_list_store_set()` and `gtk_tree_store_set()`, but can't read it back?
| 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()`.
5.5. | How do I change the way that numbers are formatted by GtkTreeView?

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

The following example demonstrates this:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64

    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);
    }

5.6. | How do I hide the expander arrows in my tree view ?
| Set the expander-column property of the tree view to a hidden column. See `gtk_tree_view_set_expander_column()` and `gtk_tree_view_column_set_visible()`.

##### 6. Using cairo with GTK+

6.1. | How do I use cairo to draw in GTK+ applications ?
| Use `gdk_cairo_create()` to obtain a cairo context for drawing on a GDK window or pixmap. See Cairo Interaction for some more useful functions.
6.2. | I have created a cairo context with `gdk_cairo_create()`, but when I later use it, my drawing does not show up. Why is that ?

All drawing in GTK+ is normally done in an expose handler, and GTK+ creates a temporary pixmap for double-buffering the drawing. If you create a cairo context outside the expose handler, it is backed by the GDK window itself, not the double-buffering pixmap. Consequently, any drawing you do with that cairo context gets overwritten at the end of the expose handler, when the double-buffering pixmap is copied back.

Possible solutions to this problem are:

- Turn off double-buffering, with `gtk_widget_set_double_buffered()`. This is not ideal, since it can cause some flickering.

- Create the cairo context inside the expose handler. If you do this, `gdk_create_cairo()` arranges for it to be backed by the double-buffering pixmap. This is the preferred solution, and is used throughout GTK+ itself.

6.3. | Can I improve the performance of my application by using the Glitz backend of cairo ?
| No. The GDK X11 backend uses the cairo X backend (and the other GDK backends use their respective native cairo backends). The GTK+ developers believe that the best way to improving the GDK drawing performance is to optimize the cairo X backend and the relevant code paths in the X server that is uses (mostly the Render extension).
6.4. | Can I use cairo to draw on a GdkPixbuf ?
| No, at least not yet. The cairo image surface does not support the pixel format used by GdkPixbuf.

[1] If the file load fails, `gtk_image_new_from_file()` will display no image graphic — to detect a failed load yourself, use `gdk_pixbuf_new_from_file()` directly, then `gtk_image_new_from_pixbuf()`.