![]() |
![]() |
![]() |
![]() |
Common Questions — Find answers to common questions in the GTK manual
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 some tutorials and other documentation (most of it about GTK 2.x, but mostly still applicable). 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 Part V, “Migrating from Previous Versions of GTK”. 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 GInitiallyUnowned. For GObject note
specifically
For strings returned from functions, they will be declared "const"
if they should not be freed. Non-const strings should be
freed with |
|||||||||||
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
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 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
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 |
|||||||||||
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
The short checklist on how to use gettext is: call
#define _(x) gettext (x) #define N_(x) x #define C_(ctx,x) pgettext (ctx, x)
You use Code using these macros ends up looking like this: #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
With the convention that the macro #define _(x) dgettext (GETTEXT_PACKAGE, 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:
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
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
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, or
If you are using |
|||||||||||
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: gdk_surface_set_events (gdk_surface, GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK); while in C++ you must write: gdk_surface_set_events (gdk_surface, (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 https://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
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 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_cairo_show_layout (cr, layout); pango_font_description_free (fontdesc); g_object_unref (layout);
See also the Cairo Rendering section of Pango manual. |
|||||||||||
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
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);
See also the Layout Objects section of Pango manual. |
|||||||||||
1.14. |
Why are types not registered if I use their |
||||||||||
The
GLib provides the
|
|||||||||||
1.15. |
How do I create a transparent toplevel window ? |
||||||||||
Any toplevel window can be transparent. It is just a matter of setting a transparent background in the CSS style for it. |
|||||||||||
2. Which widget should I use... | |||||||||||
2.1. |
...for lists and trees? |
||||||||||
This question has different answers, depending on the size of the dataset and the required formatting flexibility. If you want to display a large amount of data in a uniform way, your best option is a GtkTreeView widget. See tree widget overview. A list is just a tree with no branches, so the treeview widget is used for lists as well. If you want to display a small amount of items, but need flexible formatting and widgetry inside the list, then you probably want to use a GtkListBox, which uses regular widgets for display. |
|||||||||||
2.2. |
...for multi-line text display or editing? |
||||||||||
See text widget overview — you should use the GtkTextView widget.
If you only have a small amount of text, GtkLabel may also be appropriate
of course. It can be made selectable with |
|||||||||||
2.3. |
...to display an image or animation? |
||||||||||
GTK has two widgets that are dedicated to displaying images. GtkImage, for small, fixed-size icons and GtkPicture for content images. Both 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 the “has-entry” property. |
|||||||||||
3. GtkWidget | |||||||||||
3.1. |
How do I change the color of a widget? |
||||||||||
The background color of a widget is determined by the CSS style that applies
to it. To change that, you can set style classes on the widget, and provide
custom CSS to change the appearance. Such CSS can be loaded with
|
|||||||||||
3.2. |
How do I change the font of a widget? |
||||||||||
If you want to make the text of a label larger, you can use
This is preferred for many apps because it's a relative size to the
user's chosen font size. See You can also change the font of a widget by putting .my-widget-class { font: Sans 30; }
in a CSS file, loading it with |
|||||||||||
3.3. |
How do I disable/ghost/desensitize a widget? |
||||||||||
In GTK a disabled widget is termed "insensitive."
See |
|||||||||||
4. GtkTextView | |||||||||||
4.1. |
How do I get the contents of the entire text widget as a string? |
||||||||||
See
|
|||||||||||
4.2. |
How do I make a text widget display its complete contents in a specific font? |
||||||||||
If you use
To ensure that all text has the desired appearance, use
|
|||||||||||
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
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 |
|||||||||||
5.2. |
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 |
|||||||||||
5.3. |
I can set data easily on my GtkTreeStore/GtkListStore models using
|
||||||||||
Both the GtkTreeStore and the GtkListStore implement the GtkTreeModel
interface. Consequentially, you can use any function this interface
implements. The easiest way to read a set of data back is to use
|
|||||||||||
5.4. |
How do I change the way that numbers are formatted by GtkTreeView? |
||||||||||
Use The following example demonstrates this:
|
|||||||||||
5.5. |
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 |
|||||||||||
6. Using cairo with GTK | |||||||||||
6.1. |
How do I use cairo to draw in GTK applications ? |
||||||||||
Use |
|||||||||||
6.2. |
Can I improve the performance of my application by using another backend of cairo (such as GL) ? |
||||||||||
No. Most drawing in GTK is not done via cairo anymore (but instead by the GL or Vulkan renderers of GSK).
If you use cairo for drawing your own widgets, If you are interested in using GL for your own drawing, see GtkGLArea. |
|||||||||||
6.3. |
Can I use cairo to draw on a GdkPixbuf ? |
||||||||||
No. The cairo image surface does not support the pixel format used by GdkPixbuf.
If you need to get cairo drawing into a format that can be displayed efficiently
by GTK, you may want to use an image surface and |
[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()
.