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?

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

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:

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.

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.

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)

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.

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:

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.

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:

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;

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.

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

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:

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 ?

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

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