2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
5 <refentry id="gtk-question-index" revision="1 Jan 2002">
7 <refentrytitle>Common Questions</refentrytitle>
8 <manvolnum>3</manvolnum>
9 <refmiscinfo>Common Questions</refmiscinfo>
13 <refname>Common Questions</refname>
15 Find answers to common questions in the GTK+ manual
20 <title>Questions and Answers</title>
23 This is an "index" of the reference manual organized by common "How do
24 I..." questions. If you aren't sure which documentation to read for
25 the question you have, this list is a good place to start.
30 <qandadiv><title>General</title>
34 How do I get started with GTK+?
38 The GTK+ <ulink url="http://www.gtk.org">website</ulink> offers a
39 <ulink url="http://www.gtk.org/tutorial">tutorial</ulink> and a
40 <ulink url="http://www.gtk.org/faq">FAQ</ulink>. More documentation ranging
41 from whitepapers to online books can be found at the
42 <ulink url="http://developer.gnome.org/doc">GNOME developer's site</ulink>.
43 After studying these materials you should be well prepared to come back to
44 this reference manual for details.
50 Where can I get help with GTK+, submit a bug report, or make a feature
57 See the <link linkend="gtk-resources">documentation on this topic</link>.
66 <question><para>How do I port from one GTK+
67 version to another?</para></question>
72 See the <link linkend="gtk-changes-2-0">list of incompatible changes
73 from 1.2 to 2.0</link>. Also, the <ulink
74 url="http://developer.gnome.org/dotplan/porting/">GNOME 2.0 porting
75 guide</ulink> on <ulink
76 url="http://developer.gnome.org">http://developer.gnome.org</ulink>
77 has some more detailed discussion of porting from 1.2 to 2.0.
78 You may also find useful information in the documentation for
79 specific widgets and functions.
83 If you have a question not covered in the manual, feel free to
84 ask on the mailing lists and please <ulink
85 url="http://bugzilla.gnome.org">file a bug report</ulink> against the
96 How does memory management work in GTK+? Should I free data returned
103 See the documentation for #GObject and #GtkObject. For #GObject note
104 specifically g_object_ref() and g_object_unref(). #GtkObject is a subclass
105 of #GObject so the same points apply, except that it has a "floating" state
106 (explained in its documentation).
110 For strings returned from functions, they will be declared "const" (using
111 #G_CONST_RETURN) if they should not be freed. Non-const strings should be
112 freed with g_free(). Arrays follow the same rule. (If you find an exception
113 to the rules, please report a bug to <ulink
114 url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.)
123 Why does my program leak memory, if I destroy a widget immediately
130 If <structname>GtkFoo</structname> isn't a toplevel window, then
131 <informalexample><programlisting>
132 foo = gtk_foo_new (<!-- -->);
133 gtk_widget_destroy (foo);
134 </programlisting></informalexample>
135 is a memory leak, because no one assumed the initial floating
136 reference. If you are using a widget and you aren't immediately
137 packing it into a container, then you probably want standard
138 reference counting, not floating reference counting.
142 To to get this, you must acquire a reference to the widget and drop the
143 floating reference (<quote>ref and sink</quote> in GTK+ parlance) after
145 <informalexample><programlisting>
146 foo = gtk_foo_new (<!-- -->);
148 gtk_object_sink (GTK_OBJECT (foo));
149 </programlisting></informalexample>
150 When you want to get rid of the widget, you must call gtk_widget_destroy()
151 to break any external connections to the widget before dropping your
153 <informalexample><programlisting>
154 gtk_widget_destroy (foo);
155 g_object_unref (foo);
156 </programlisting></informalexample>
157 When you immediately add a widget to a container, it takes care of
158 assuming the initial floating reference and you don't have to worry
159 about reference counting at all ... just call gtk_widget_destroy()
160 to get rid of the widget.
167 How do I use GTK+ with threads?
173 This is covered in the <link linkend="gdk-Threads">GDK threads
174 documentation</link>. See also the <link linkend="glib-Threads">GThread</link>
175 documentation for portable threading primitives.
184 How do I internationalize a GTK+ program?
189 Most people use <ulink url="http://www.gnu.org/software/gettext/">GNU
190 gettext</ulink>, already required in order to install GLib. On a UNIX
191 or Linux system with gettext installed, type <literal>info gettext</literal>
192 to read the documentation.
195 The short checklist on how to use gettext is: call bindtextdomain() so gettext
196 can find the files containing your translations, call textdomain() to set the
197 default translation domain, call bind_textdomain_codeset() to request that
198 all translated strings are returned in UTF-8, then call gettext() to look up
199 each string to be translated in the default domain.
200 Conventionally, people define macros as follows for convenience:
203 #define _(x) gettext (x)
207 You use N_() (N stands for no-op) to mark a string for translation in a
208 context where a function call to gettext() is not allowed, such as in an
210 You eventually have to call gettext() on the string to actually fetch the
211 translation. _() both marks the string for translation and actually
215 Nowadays, GLib provides the common shorthand macros in the header file
216 <filename>gi18n.h</filename>, so you don't have to define them yourself,
217 just include that header.
220 Code using these macros ends up looking like this:
223 #include <gi18n.h>
225 static const char *global_variable = N_("Translate this string");
233 label1 = gtk_label_new (_("Another string to translate"));
234 label2 = gtk_label_new (_(global_variable));
240 Libraries using gettext should use dgettext() instead of gettext(), which
241 allows them to specify the translation domain each time they ask for a
242 translation. Libraries should also avoid calling textdomain(), since they
243 will be specifying the domain instead of using the default. For dgettext()
244 the _() macro can be defined as:
247 #define _(x) dgettext ("MyDomain", x)
252 Again, GLib comes with the <filename>gi18n-lib.h</filename>, saving you the
253 trouble of defining the macros by hand. The macros in that header expect the
254 translation domain to be specified by the %GETTEXT_PACKAGE macro.
262 How do I use non-ASCII characters in GTK+ programs ?
268 GTK+ uses <ulink url="http://www.unicode.org">Unicode</ulink> (more exactly
269 UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a sequence of
270 one to six bytes and has a number of nice properties which make it a good
271 choice for working with Unicode text in C programs:
274 ASCII characters are encoded by their familiar ASCII codepoints.
277 ASCII characters never appear as part of any other character.
280 The zero byte doesn't occur as part of a character, so that UTF-8 strings
281 can be manipulated with the usual C library functions for handling
282 zero-terminated strings.
285 More information about Unicode and UTF-8 can be found in the
286 <ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode i
287 FAQ for Unix/Linux</ulink>.
288 GLib provides functions for converting strings between UTF-8 and other
289 encodings, see g_locale_to_utf8() and g_convert().
292 Text coming from external sources (e.g. files or user input), has to be
293 converted to UTF-8 before being handed over to GTK+. The following example
294 writes the content of a IS0-8859-1 encoded text file to
295 <literal>stdout</literal>:
296 <informalexample><programlisting>
297 gchar *text, *utf8_text;
299 GError *error = NULL;
301 if (g_file_get_contents (filename, &text, &length, NULL))
303 utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1",
304 NULL, NULL, &error);
307 fprintf ("Couldn't convert file %s to UTF-8\n", filename);
308 g_error_free (error);
314 fprintf (stderr, "Unable to read file %s\n", filename);
315 </programlisting></informalexample>
318 For string literals in the source code, there are several alternatives for
319 handling non-ASCII content:
321 <varlistentry><term>direct UTF-8</term>
323 If your editor and compiler are capable of handling UTF-8 encoded sources,
324 it is very convenient to simply use UTF-8 for string literals, since it allows
325 you to edit the strings in "wysiwyg". Note that choosing this option may
326 reduce the portability of your code.
330 <varlistentry><term>escaped UTF-8</term>
332 Even if your toolchain can't handle UTF-8 directly, you can still encode string
333 literals in UTF-8 by using octal or hexadecimal escapes like
334 <literal>\212</literal> or <literal>\xa8</literal> to
335 encode each byte. This is portable, but modifying the escaped strings is not
336 very convenient. Be careful when mixing hexadecimal escapes with ordinary text;
337 <literal>"\xa8abcd"</literal> is a string of length 1 !
341 <varlistentry><term>runtime conversion</term>
343 If the string literals can be represented in an encoding which your toolchain
344 can handle (e.g. IS0-8859-1), you can write your source files in that encoding
345 and use g_convert() to convert the strings to UTF-8 at runtime. Note that this
346 has some runtime overhead, so you may want to move the conversion out of inner
351 Here is an example showing the three approaches using the copyright sign
352 © which has Unicode and ISO-8859-1 codepoint 169 and is represented in
353 UTF-8 by the two bytes 194, 169:
354 <informalexample><programlisting>
355 g_print ("direct UTF-8: ©");
356 g_print ("escaped UTF-8: \302\251");
357 text = g_convert ("runtime conversion: ©", -1, "ISO-8859-1", "UTF-8", NULL, NULL, NULL);
360 </programlisting></informalexample>
363 If you are using gettext() to localize your application, you need to
364 call bind_textdomain_codeset() to ensure that translated strings are
365 returned in UTF-8 encoding.
372 How do I use GTK+ with C++?
377 There are two ways to approach this. The GTK+ header files use the subset
378 of C that's also valid C++, so you can simply use the normal GTK+ API
379 in a C++ program. Alternatively, you can use a "C++ binding"
380 such as <ulink url="http://gtkmm.sourceforge.net/">gtkmm</ulink>
381 which provides a native C++ API.
384 When using GTK+ directly, keep in mind that only functions can be
385 connected to signals, not methods. So you will need to use global
386 functions or "static" class functions for signal connections.
389 Another common issue when using GTK+ directly is that
390 C++ will not implicitly convert an integer to an enumeration.
391 This comes up when using bitfields; in C you can write the following
395 gdk_window_set_events (gdk_window,
396 GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
399 while in C++ you must write:
402 gdk_window_set_events (gdk_window,
403 (GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
406 There are very few functions that require this cast, however.
414 How do I use GTK+ with other non-C languages?
419 See the <ulink url="http://www.gtk.org/bindings.html">list of language
420 bindings</ulink> on <ulink
421 url="http://www.gtk.org">http://www.gtk.org</ulink>.
430 How do I load an image or animation from a file?
436 To load an image file straight into a display widget, use
437 gtk_image_new_from_file() <footnote><para> If the file load fails,
438 gtk_image_new_from_file() will display no image graphic — to detect
439 a failed load yourself, use gdk_pixbuf_new_from_file() directly, then
440 gtk_image_new_from_pixbuf().</para></footnote>.
441 To load an image for another purpose, use gdk_pixbuf_new_from_file(). To i
442 load an animation, use gdk_pixbuf_animation_new_from_file().
443 gdk_pixbuf_animation_new_from_file() can also load non-animated images, so
444 use it in combination with gdk_pixbuf_animation_is_static_image() to load a
445 file of unknown type.
448 To load an image or animation file asynchronously (without blocking), use
462 To draw a piece of text, use a Pango layout and gdk_draw_layout(),
463 using code like the following:
466 layout = gtk_widget_create_pango_layout (widget, text);
467 fontdesc = pango_font_description_from_string ("Luxi Mono 12");
468 pango_layout_set_font_description (layout, fontdesc);
469 gdk_draw_layout (..., layout);
470 pango_font_description_free (fontdesc);
471 g_object_unref (layout);
474 Do not use the deprecated #GdkFont and gdk_draw_text().
478 See also the "Text Handling in GTK 2" section of
479 <ulink url="http://developer.gnome.org/dotplan/porting/">Porting applications
480 to the GNOME 2.0 platform</ulink>.
489 How do I measure the size of a piece of text ?
495 To obtain the size of a piece of text, use a Pango layout and
496 pango_layout_get_pixel_size(), using code like the following:
499 layout = gtk_widget_create_pango_layout (widget, text);
500 fontdesc = pango_font_description_from_string ("Luxi Mono 12");
501 pango_layout_set_font_description (layout, fontdesc);
502 pango_layout_get_pixel_size (layout, &width, &height);
503 pango_font_description_free (fontdesc);
504 g_object_unref (layout);
507 Do not use the deprecated function gdk_text_width().
511 See also the "Text Handling in GTK 2" section of
512 <ulink url="http://developer.gnome.org/dotplan/porting/">Porting applications
513 to the GNOME 2.0 platform</ulink>.
521 Why are types not registered if I use their <literal>GTK_TYPE_BLAH</literal>
528 The <literal>GTK_TYPE_BLAH</literal> macros are defined as calls to
529 <literal>gtk_blah_get_type()</literal>, and the <literal>_get_type()</literal> i
530 functions are declared as %G_GNUC_CONST which allows the compiler to optimize
531 the call away if it appears that the value is not being used.
535 A common workaround for this problem is to store the result in a volatile
536 variable, which keeps the compiler from optimizing the call away.
537 <informalexample><programlisting>
538 volatile GType dummy = GTK_TYPE_BLAH;
539 </programlisting></informalexample>
547 How do I create a transparent toplevel window ?
553 To make a window transparent, it needs to use a visual which supports that.
554 This is done by getting the RGBA colormap of the screen with
555 gdk_screen_get_rgba_colormap() and setting it on the window. Note that
556 gdk_screen_get_rgba_colormap() will return %NULL if transparent windows
557 are not supported on the screen; also note that this may change from
558 screen to screen, so it needs to be repeated whenever the window is moved
559 to a different screen.
560 <informalexample><programlisting>
561 GdkColormap *colormap;
563 colormap = gdk_screen_get_rgba_colormap (screen);
565 colormap = gdk_screen_get_rgb_colormap (screen);
567 gtk_widget_set_colormap (widget, colormap);
568 </programlisting></informalexample>
569 One possibility to fill the alpha channel on the window is to use
570 gdk_draw_rgb_32_image().
573 Note that the presence of an RGBA visual is no guarantee that the
574 window will actually appear transparent on screen. On X11, this
575 requires a compositing manager to be running. See
576 gtk_widget_is_composited() for a way to find out if the alpha
577 channel will be respected.
584 <qandadiv><title>Which widget should I use...</title>
588 ...for lists and trees?
593 See <link linkend="TreeWidget">tree widget overview</link> — you
594 should use the #GtkTreeView widget. (A list is just a tree with no branches,
595 so the tree widget is used for lists as well.) Do not use the deprecated
596 widgets #GtkTree or #GtkCList/#GtkCTree in newly-written code, they are
597 less flexible and result in an inferior user interface.
604 ...for multi-line text display or editing?
609 See <link linkend="TextWidget">text widget overview</link> — you
610 should use the #GtkTextView widget. Do not use the deprecated widget #GtkText
611 in newly-written code, it has a number of problems that are best avoided.
614 If you only have a small amount of text, #GtkLabel may also be appropriate
615 of course. It can be made selectable with gtk_label_set_selectable(). For a
616 single-line text entry, see #GtkEntry.
624 ...to display an image or animation?
629 #GtkImage can display images in just about any format GTK+ understands.
630 You can also use #GtkDrawingArea if you need to do something more complex,
631 such as draw text or graphics over the top of the image.
638 ...for presenting a set of mutually-exclusive choices, where Windows
639 would use a combo box?
644 With GTK+, a #GtkComboBox is the recommended widget to use for this use case.
645 This widget looks like either a combo box or the current option menu, depending
646 on the current theme. If you need an editable text entry, use #GtkComboBoxEntry.
653 <qandadiv><title>GtkWidget</title>
657 How do I change the color of a widget?
661 See gtk_widget_modify_fg(), gtk_widget_modify_bg(), gtk_widget_modify_base(),
662 and gtk_widget_modify_text(). See <link linkend="gtk-Resource-Files">GTK+
663 resource files</link> for more discussion. You can also change widget color
664 by installing a resource file and parsing it with gtk_rc_add_default_file().
665 The advantage of a resource file is that users can then override the
669 <para>To change the background color for widgets such as #GtkLabel that have
670 no background, place them in a #GtkEventBox and set the background of the
677 How do I change the font of a widget?
681 This has several possible answers, depending on what exactly you want to
682 achieve. One option is gtk_widget_modify_font(). Note that this function
683 can be used to change only the font size, as in the following example:
685 PangoFontDesc *font_desc = pango_font_description_new (<!-- -->);
686 pango_font_description_set_size (font_desc, 40);
687 gtk_widget_modify_font (widget, font);
688 pango_font_description_free (font_desc);
692 If you want to make the text of a label larger, you can use
693 gtk_label_set_markup():
695 gtk_label_set_markup (label, "<big>big text</big>");
697 This is preferred for many apps because it's a relative size to the
698 user's chosen font size. See g_markup_escape_text() if you are
699 constructing such strings on the fly.
702 You can also change the font of a widget by putting
704 gtk-font-name = "Sans 30"
706 in a resource file and parsing it with gtk_rc_add_default_file().
707 The advantage of a resource file is that users can then override the font you
708 have chosen. See <link linkend="gtk-Resource-Files">GTK+ resource files</link>
716 How do I disable/ghost/desensitize a widget?
719 <answer><para> In GTK+ a disabled widget is termed "insensitive." See
720 gtk_widget_set_sensitive().
727 <qandadiv><title>GtkTextView</title>
731 How do I get the contents of the entire text widget as a string?
735 See gtk_text_buffer_get_bounds() and gtk_text_buffer_get_text()
736 or gtk_text_iter_get_text().
739 <informalexample><programlisting>
740 GtkTextIter start, end;
741 GtkTextBuffer *buffer;
744 buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (text_view));
745 gtk_text_buffer_get_bounds (buffer, &start, &end);
746 text = gtk_text_iter_get_text (&start, &end);
749 </programlisting></informalexample>
755 How do I make a text widget display its complete contents in a specific font?
759 If you use gtk_text_buffer_insert_with_tags() with appropriate tags to select
760 the font, the inserted text will have the desired appearance, but text typed
761 in by the user before or after the tagged block will appear in the default
765 To ensure that all text has the desired appearance, use gtk_widget_modify_font()
766 to change the default font for the widget.
773 How do I make a text view scroll to the end of the buffer automatically ?
779 A good way to keep a text buffer scrolled to the end is to place a
780 <link linkend="GtkTextMark">mark</link> at the end of the buffer, and
781 give it right gravity. The gravity has the effect that text inserted
782 at the mark gets inserted <emphasis>before</emphasis>, keeping the mark
787 To ensure that the end of the buffer remains visible, use
788 gtk_text_view_scroll_to_mark() to scroll to the mark after
793 The gtk-demo application contains an example of this technique.
801 <qandadiv><title>#GtkTreeView</title>
805 How do I associate some data with a row in the tree?
810 Remember that the #GtkTreeModel columns don't necessarily have to be displayed.
811 So you can put non-user-visible data in your model just like any other data,
812 and retrieve it with gtk_tree_model_get(). See the
813 <link linkend="TreeWidget">tree widget overview</link>.
820 What's the #GtkTreeView equivalent of gtk_clist_find_row_from_data()?
825 As there is no separate data column in the #GtkTreeModel, there's no
826 built in function to find the iter from data. You can write a custom
827 searching function to walk the tree and find the data, or use
828 gtk_tree_model_foreach().
835 How do I put an image and some text in the same column?
840 You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn
841 using gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end().
842 So pack both a #GtkCellRendererPixbuf and a #GtkCellRendererText into the
850 I can set data easily on my #GtkTreeStore/#GtkListStore models using
851 gtk_list_store_set() and gtk_tree_store_set(), but can't read it back?
856 Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel
857 interface. Consequentially, the can use any function this interface
858 implements. The easiest way to read a set of data back is to use
859 gtk_tree_model_get().
866 How do I change the way that numbers are formatted by #GtkTreeView?
869 Use gtk_tree_view_insert_column_with_data_func()
870 or gtk_tree_view_column_set_cell_data_func() and do the conversion from i
871 number to string yourself (with, say, g_strdup_printf()).
875 The following example demonstrates this:
876 <informalexample><programlisting>
883 GtkListStore *mycolumns;
884 GtkTreeView *treeview;
887 my_cell_double_to_text (GtkTreeViewColumn *tree_column,
888 GtkCellRenderer *cell,
889 GtkTreeModel *tree_model,
893 GtkCellRendererText *cell_text = (GtkCellRendererText *)cell;
897 /* Get the double value from the model. */
898 gtk_tree_model_get (tree_model, iter, (gint)data, &d, -1);
899 /* Now we can format the value ourselves. */
900 text = g_strdup_printf ("%.2f", d);
901 g_object_set (cell, "text", text, NULL);
906 set_up_new_columns (GtkTreeView *myview)
908 GtkCellRendererText *renderer;
909 GtkTreeViewColumn *column;
910 GtkListStore *mycolumns;
912 /* Create the data model and associate it with the given TreeView */
913 mycolumns = gtk_list_store_new (N_COLUMNS, G_TYPE_DOUBLE);
914 gtk_tree_view_set_model (myview, GTK_TREE_MODEL (mycolumns));
916 /* Create a GtkCellRendererText */
917 renderer = gtk_cell_renderer_text_new (<!-- -->);
919 /* Create a new column that has a title ("Example column"),
920 * uses the above created renderer that will render the double
921 * value into text from the associated model's rows.
923 column = gtk_tree_view_column_new (<!-- -->);
924 gtk_tree_view_column_set_title (column, "Example column");
925 renderer = gtk_cell_renderer_text_new (<!-- -->);
926 gtk_tree_view_column_pack_start (column, renderer, TRUE);
928 /* Append the new column after the GtkTreeView's previous columns. */
929 gtk_tree_view_append_column (GTK_TREE_VIEW (myview), column);
930 /* Since we created the column by hand, we can set it up for our
931 * needs, e.g. set its minimum and maximum width, etc.
933 /* Set up a custom function that will be called when the column content
934 * is rendered. We use the func_data pointer as an index into our
935 * model. This is convenient when using multi column lists.
937 gtk_tree_view_column_set_cell_data_func (column, renderer,
938 my_cell_double_to_text,
939 (gpointer)DOUBLE_COLUMN, NULL);
941 </programlisting></informalexample>
947 How do I hide the expander arrows in my tree view ?
951 Set the expander-column property of the tree view to a hidden column.
952 See gtk_tree_view_set_expander_column() and gtk_tree_view_column_set_visible().
958 <qandadiv><title>Using cairo with GTK+</title>
962 How do I use cairo to draw in GTK+ applications ?
966 Use gdk_cairo_create() to obtain a cairo context for drawing
967 on a GDK window or pixmap. See <link linkend="gdk-Cairo-Interaction">Cairo
968 Interaction</link> for some more useful functions.
974 I have created a cairo context with gdk_cairo_create(), but when I
975 later use it, my drawing does not show up. Why is that ?
980 All drawing in GTK+ is normally done in an expose handler, and GTK+
981 creates a temporary pixmap for double-buffering the drawing. If you
982 create a cairo context outside the expose handler, it is backed
983 by the GDK window itself, not the double-buffering pixmap. Consequently,
984 any drawing you do with that cairo context gets overwritten at the
985 end of the expose handler, when the double-buffering pixmap is copied
989 Possible solutions to this problem are:
992 Turn off double-buffering, with gtk_widget_set_double_buffered().
993 This is not ideal, since it can cause some flickering.
996 Create the cairo context inside the expose handler. If you do this,
997 gdk_create_cairo() arranges for it to be backed by the double-buffering
998 pixmap. This is the preferred solution, and is used throughout GTK+
1008 Can I improve the performance of my application by using the
1009 Glitz backend of cairo ?
1013 No. The GDK X11 backend uses the cairo X backend (and the other
1014 GDK backends use their respective native cairo backends). The
1015 GTK+ developers believe that the best way to improving the GDK
1016 drawing performance is to optimize the cairo X backend and the
1017 relevant code paths in the X server that is uses (mostly the
1024 Can I use cairo to draw on a #GdkPixbuf ?
1028 No, at least not yet. The cairo image surface does not support the
1029 pixel format used by GdkPixbuf.