1 <refentry id="gtk-question-index" revision="1 Jan 2002">
3 <refentrytitle>Common Questions</refentrytitle>
4 <manvolnum>3</manvolnum>
5 <refmiscinfo>Common Questions</refmiscinfo>
9 <refname>Common Questions</refname>
11 Find answers to common questions in the GTK+ manual
16 <title>Questions and Answers</title>
19 This is an "index" of the reference manual organized by common "How do
20 I..." questions. If you aren't sure which documentation to read for
21 the question you have, this list is a good place to start.
26 <qandadiv><title>General</title>
30 Where can I get help with GTK+, submit a bug report, or make a feature
37 See the <link linkend="gtk-resources">documentation on this topic</link>.
46 <question><para>How do I port from one GTK+
47 version to another?</para></question>
52 See the <link linkend="gtk-changes-2-0">list of incompatible changes
53 from 1.2 to 2.0</link>. Also, the <ulink
54 url="http://developer.gnome.org/dotplan/porting/">GNOME 2.0 porting
55 guide</ulink> on <ulink
56 url="http://developer.gnome.org">http://developer.gnome.org</ulink>
57 has some more detailed discussion of porting from 1.2 to 2.0.
58 You may also find useful information in the documentation for
59 specific widgets and functions.
63 If you have a question not covered in the manual, feel free to
64 ask on the mailing lists and please <ulink
65 url="http://bugzilla.gnome.org">file a bug report</ulink> against the
76 How does memory management work in GTK+? Should I free data returned
83 See the documentation for <link linkend="GObject">GObject</link> and
84 <link linkend="GtkObject">GtkObject</link>. For <link
85 linkend="GObject">GObject</link> note specifically <link
86 linkend="g-object-ref">g_object_ref()</link> and <link
87 linkend="g-object-unref">g_object_unref()</link>. <link
88 linkend="GtkObject">GtkObject</link> is a subclass of <link
89 linkend="GObject">GObject</link> so the same points apply, except that
90 it has a "floating" state (explained in its documentation).
94 For strings returned from functions, they will be declared "const"
95 (using <link linkend="G-CONST-RETURN-CAPS">G_CONST_RETURN</link>) if they
96 should not be freed. Non-const strings should be freed with <link
97 linkend="g-free">g_free()</link>. Arrays follow the same rule. (If
98 you find an exception to the rules, please report a bug to <ulink
99 url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.)
109 How do I use GTK+ with threads?
115 This is covered in the
116 <link linkend="gdk-Threads">GDK threads documentation</link>.
117 See also the <link linkend="glib-Threads">GThread</link> documentation for portable
118 threading primitives.
127 How do I internationalize a GTK+ program?
132 Most people use <ulink url="http://www.gnu.org/software/gettext/">GNU
133 gettext</ulink>, already required in order to install GLib. On a UNIX
134 or Linux system with gettext installed, type <literal>info
135 gettext</literal> to read the documentation.
138 The short checklist on how to use gettext is: call
139 <function>bindtextdomain()</function> so gettext can find the files
140 containing your translations, call <function>textdomain()</function>
141 to set the default translation domain, then call
142 <function>gettext()</function> to look up each string to be translated
143 in the default domain. Conventionally, people define macros as
144 follows for convenience:
147 #define _(x) gettext (x)
151 You use <function>N_()</function> (N stands for no-op) to mark
152 a string for translation in a context where a function call
153 to <function>gettext()</function> is not allowed, such as in
154 an array initializer. You eventually have to call
155 <function>gettext()</function> on the string to actually fetch the
156 translation. <function>_()</function> both marks the string for
157 translation and actually translates it.
160 Code using these macros ends up looking like this:
163 #include <libintl.h>
165 #define _(x) gettext (x)
168 static const char *global_variable = N_("Translate this string");
176 label1 = gtk_label_new (_("Another string to translate"));
177 label2 = gtk_label_new (_(global_variable));
183 Libraries using gettext should use <function>dgettext()</function>
184 instead of <function>gettext()</function>, which allows
185 them to specify the translation domain each time they
186 ask for a translation. Libraries should also avoid calling
187 <function>textdomain()</function>, since they'll be specifying
188 the domain instead of using the default.
189 For <function>dgettext()</function> the <function>_()</function> macro
193 #define _(x) dgettext ("MyDomain", x)
203 How do I use non-ASCII characters in GTK+ programs ?
209 GTK+ uses <ulink url="http://www.unicode.org">Unicode</ulink> (more exactly
210 UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a
211 sequence of one to six bytes and has a number of nice
212 properties which make it a good choice for working with Unicode
216 ASCII characters are encoded by their familiar ASCII codepoints.
219 ASCII characters never appear as part of any other character.
222 The zero byte doesn't occur as part of a character, so that UTF-8 strings can
223 be manipulated with the usual C library functions for
224 handling zero-terminated strings.
227 More information about Unicode and UTF-8 can be found in the
228 <ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode FAQ for Unix/Linux</ulink>.
229 GLib provides functions for converting strings between UTF-8 and other
231 <link linkend="g-locale-to-utf8">g_locale_to_utf8()</link> and <link
232 linkend="g-convert">g_convert()</link>.
235 Text coming from external sources (e.g. files or user input), has to be
236 converted to UTF-8 before being handed over to GTK+. The
237 following example writes the content of a IS0-8859-1 encoded text
238 file to <literal>stdout</literal>:
239 <informalexample><programlisting>
240 gchar *text, *utf8_text;
242 GError *error = NULL;
244 if (g_file_get_contents (filename, &text, &length, NULL))
246 utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1",
247 NULL, NULL, &error);
250 fprintf ("Couldn't convert file %s to UTF-8\n", filename);
251 g_error_free (error);
257 fprintf (stderr, "Unable to read file %s\n", filename);
258 </programlisting></informalexample>
261 For string literals in the source code, there are several alternatives for
262 handling non-ASCII content:
264 <varlistentry><term>direct UTF-8</term>
266 If your editor and compiler are capable of handling UTF-8 encoded sources,
267 it is very convenient to simply use UTF-8 for string literals, since it allows
268 you to edit the strings in "wysiwyg". Note that choosing this option may
269 reduce the portability of your code.
273 <varlistentry><term>escaped UTF-8</term>
275 Even if your toolchain can't handle UTF-8 directly, you can still encode string
276 literals in UTF-8 by using octal or hexadecimal escapes like
277 <literal>\212</literal> or <literal>\xa8</literal> to
278 encode each byte. This is portable, but modifying the escaped strings is not
279 very convenient. Be careful when mixing hexadecimal escapes with ordinary text;
280 <literal>"\xa8abcd"</literal> is a string of length 1 !
284 <varlistentry><term>runtime conversion</term>
286 If the string literals can be represented in an encoding which your toolchain
287 can handle (e.g. IS0-8859-1), you can write your source files in that encoding
288 and use <link linkend="g-convert">g_convert()</link> to convert the strings to
289 UTF-8 at runtime. Note that this has some runtime overhead, so you may want to
290 move the conversion out of inner loops.
294 Here is an example showing the three approaches using the copyright sign
295 © which has Unicode and ISO-8859-1 codepoint 169 and is represented in
296 UTF-8 by the two bytes 194, 169:
297 <informalexample><programlisting>
298 g_print ("direct UTF-8: ©");
299 g_print ("escaped UTF-8: \302\251");
300 text = g_convert ("runtime conversion: ©", -1, "ISO-8859-1", "UTF-8", NULL, NULL, NULL);
303 </programlisting></informalexample>
310 How do I use GTK+ with C++?
315 There are two ways to approach this. The GTK+ header files use the subset
316 of C that's also valid C++, so you can simply use the normal GTK+ API
317 in a C++ program. Alternatively, you can use a "C++ binding"
318 such as <ulink url="http://gtkmm.sourceforge.net/">gtkmm</ulink>
319 which provides a C++-native API.
322 When using GTK+ directly, keep in mind that only functions can be
323 connected to signals, not methods. So you will need to use global
324 functions or "static" class functions for signal connections.
327 Another common issue when using GTK+ directly is that
328 C++ will not implicitly convert an integer to an enumeration.
329 This comes up when using bitfields; in C you can write the following
333 gdk_window_set_events (gdk_window,
334 GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
337 while in C++ you must write:
340 gdk_window_set_events (gdk_window,
341 (GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
344 There are very few functions that require this cast, however.
352 How do I use GTK+ with other non-C languages?
357 See the <ulink url="http://www.gtk.org/bindings.html">list of language
358 bindings</ulink> on <ulink
359 url="http://www.gtk.org">http://www.gtk.org</ulink>.
368 How do I load an image or animation from a file?
374 To load an image file straight into a display widget, use <link
375 linkend="gtk-image-new-from-file">gtk_image_new_from_file()</link>
376 <footnote><para> If the file load fails, <link
377 linkend="gtk-image-new-from-file">gtk_image_new_from_file()</link>
378 will display a "broken image" graphic — to detect a failed load
380 linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>
382 linkend="gtk-image-new-from-pixbuf">gtk_image_new_from_pixbuf()</link>.
383 </para></footnote>. To load an image for another purpose, use <link
384 linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>.
385 To load an animation, use <link
386 linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file()</link>.
388 linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file()</link>
389 can also load non-animated images, so use it in combination with
391 linkend="gdk-pixbuf-animation-is-static-image">gdk_pixbuf_animation_is_static_image()</link> to load a file of unknown type.
394 To load an image or animation file asynchronously (without blocking), use
395 <link linkend="GdkPixbufLoader">GdkPixbufLoader</link>.
408 To draw a piece of text, use a Pango layout and
409 <link linkend="gdk-draw-layout">gdk_draw_layout()</link>,
410 using code like the following:
413 layout = gtk_widget_create_pango_layout (widget, text);
414 fontdesc = pango_font_description_from_string ("Luxi Mono 12");
415 pango_layout_set_font_description (layout, fontdesc);
416 gdk_draw_layout (..., layout);
417 pango_font_description_free (fontdesc);
418 g_object_unref (layout);
421 Do not use the deprecated <link linkend="GdkFont">GdkFont</link> and <link linkend="gdk-draw-text">gdk_draw_text()</link>.
425 See also the "Text Handling in GTK 2" section of
426 <ulink url="http://developer.gnome.org/dotplan/porting/">Porting applications
427 to the GNOME 2.0 platform</ulink>.
436 How do I measure the size of a piece of text ?
442 To obtain the size of a piece of text, use a Pango layout and
444 linkend="pango-layout-get-pixel-size">pango_layout_get_pixel_size()</link>,
445 using code like the following:
448 layout = gtk_widget_create_pango_layout (widget, text);
449 fontdesc = pango_font_description_from_string ("Luxi Mono 12");
450 pango_layout_set_font_description (layout, fontdesc);
451 pango_layout_get_pixel_size (layout, &width, &height);
452 pango_font_description_free (fontdesc);
453 g_object_unref (layout);
456 Do not use the deprecated function <link linkend="gdk-text-width">gdk_text_width()</link>.
460 See also the "Text Handling in GTK 2" section of
461 <ulink url="http://developer.gnome.org/dotplan/porting/">Porting applications
462 to the GNOME 2.0 platform</ulink>.
470 How do I make a text view scroll to the end of the buffer automatically ?
476 The "insert" <link linkend="GtkTextMark">mark</link> marks the insertion point
477 where <link linkend="gtk-text-buffer-insert">gtk_text_buffer_insert()</link>
478 inserts new text into the buffer. The text is inserted
479 <emphasis>before</emphasis> the "insert" mark, so that it generally stays
480 at the end of the buffer. If it gets explicitly moved to some other position,
481 e.g. when the user selects some text,
482 use <link linkend="gtk-text-buffer-move-mark">gtk_text_buffer_move_mark()</link>
483 to set it to the desired location before inserting more text.
484 The "insert" mark of a buffer can be obtained with <link
485 linkend="gtk-text-buffer-get-insert">gtk_text_buffer_get_insert()</link>.
489 To ensure that the end of the buffer remains visible, use
491 linkend="gtk-text-view-scroll-to-mark">gtk_text_view_scroll_to_mark()</link> to scroll to the "insert" mark after inserting new text.
497 <qandadiv><title>Which widget should I use...</title>
501 ...for lists and trees?
506 See <link linkend="TreeWidget">tree widget overview</link> — you
507 should use the <link linkend="GtkTreeView">GtkTreeView</link> widget.
508 (A list is just a tree with no branches, so the tree widget is used
509 for lists as well.) Do not use the deprecated widgets <link
510 linkend="GtkTree">GtkTree</link> or <link
511 linkend="GtkCList">GtkCList</link>/<link
512 linkend="GtkCTree">GtkCTree</link> in newly-written code, they are
513 less flexible and result in an inferior user interface.
520 ...for multi-line text display or editing?
525 See <link linkend="TextWidget">text widget overview</link> — you
526 should use the <link linkend="GtkTextView">GtkTextView</link> widget.
527 Do not use the deprecated widget <link
528 linkend="GtkText">GtkText</link> in newly-written code, it has a
529 number of problems that are best avoided.
532 If you only have a small amount of text, <link
533 linkend="GtkLabel">GtkLabel</link> may also be appropriate of course.
534 It can be made selectable with <link linkend="gtk-label-set-selectable">
535 gtk_label_set_selectable()</link>. For a single-line text entry,
536 see <link linkend="GtkEntry">GtkEntry</link>.
544 ...to display an image or animation?
549 <link linkend="GtkImage">GtkImage</link> can display images
550 in just about any format GTK+ understands. You can also
551 use <link linkend="GtkDrawingArea">GtkDrawingArea</link> if you need
552 to do something more complex, such as draw text or graphics over the
560 ...for presenting a set of mutually-exclusive choices, where Windows
561 would use a combo box?
566 With GTK+, a <link linkend="GtkOptionMenu">GtkOptionMenu</link> is
567 recommended instead of a combo box, if the user is selecting from a
568 fixed set of options. That is, non-editable combo boxes are not
569 encouraged. <link linkend="GtkOptionMenu">GtkOptionMenu</link> is
570 much easier to use than <link linkend="GtkCombo">GtkCombo</link>
571 as well. Use <link linkend="GtkCombo">GtkCombo</link> only when you
572 need the editable text entry.
575 (As a future enhancement to GTK+, a new widget to replace <link
576 linkend="GtkOptionMenu">GtkOptionMenu</link> and <link
577 linkend="GtkCombo">GtkCombo</link> is planned. This widget will be
578 themeable to look like either a combo box or the current option menu,
579 and will address some shortcomings in the <link
580 linkend="GtkCombo">GtkCombo</link> API. <ulink
581 url="http://bugzilla.gnome.org/show_bug.cgi?id=50554">Bug
582 50554</ulink> tracks this issue, if you want to check status or post
590 <qandadiv><title><link linkend="GtkWidget">GtkWidget</link></title>
594 How do I change the color of a widget?
598 See <link linkend="gtk-widget-modify-fg">gtk_widget_modify_fg()</link>,
599 <link linkend="gtk-widget-modify-bg">gtk_widget_modify_bg()</link>,
600 <link linkend="gtk-widget-modify-base">gtk_widget_modify_base()</link>,
602 linkend="gtk-widget-modify-text">gtk_widget_modify_text()</link>. See
603 <link linkend="gtk-Resource-Files">GTK+ resource files</link> for more
604 discussion. You can also change widget color by installing a resource
605 file and parsing it with <link
606 linkend="gtk-rc-add-default-file">gtk_rc_add_default_file()</link>.
607 The advantage of a resource file is that users can then override the
611 <para>To change the background color for widgets such as <link
612 linkend="GtkLabel">GtkLabel</link> that have no background, place them
613 in a <link linkend="GtkEventBox">GtkEventBox</link> and set the
614 background of the event box.
620 How do I disable/ghost/desensitize a widget?
623 <answer><para> In GTK+ a disabled widget is termed "insensitive." See
625 linkend="gtk-widget-set-sensitive">gtk_widget_set_sensitive()</link>.
632 <qandadiv><title><link linkend="GtkTextView">GtkTextView</link></title>
636 How do I get the contents of the entire text widget as a string?
642 linkend="gtk-text-buffer-get-bounds">gtk_text_buffer_get_bounds()</link>
644 linkend="gtk-text-buffer-get-text">gtk_text_buffer_get_text()</link>
646 linkend="gtk-text-iter-get-text">gtk_text_iter_get_text()</link>.
649 <informalexample><programlisting>
650 GtkTextIter start, end;
651 GtkTextBuffer *buffer;
654 buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (text_view));
655 gtk_text_buffer_get_bounds (buffer, &start, &end);
656 text = gtk_text_iter_get_text (&start, &end);
659 </programlisting></informalexample>
665 How do I make a text widget display its complete contents in a specific font?
670 linkend="gtk-text-buffer-insert-with-tags">gtk_text_buffer_insert_with_tags()</link> 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.
673 To ensure that all text has the desired appearance, use <link
674 linkend="gtk-widget-modify-font">gtk_widget_modify_font()</link> to change the default font for the widget.
681 <qandadiv><title><link linkend="GtkTreeView">GtkTreeView</link></title>
685 How do I associate some data with a row in the tree?
690 Remember that the <link linkend="GtkTreeModel">GtkTreeModel</link>
691 columns don't necessarily have to be displayed. So you can put
692 non-user-visible data in your model just like any other data, and
693 retrieve it with <link
694 linkend="gtk-tree-model-get">gtk_tree_model_get()</link>.
695 See the <link linkend="TreeWidget">tree widget overview</link>.
702 What's the <link linkend="GtkTreeView">GtkTreeView</link> equivalent of
703 <link linkend="gtk-clist-find-row-from-data">gtk_clist_find_row_from_data()</link>?
708 As there is no separate data column in the <link linkend="GtkTreeModel">GtkTreeModel</link>, there's no
709 built in function to find the iter from data. You can write a custom
710 searching function to walk the tree and find the data, or use
711 <link linkend="gtk-tree-model-foreach">gtk_tree_model_foreach()</link>.
718 How do I put an image and some text in the same column?
723 You can pack more than one <link
724 linkend="GtkCellRenderer">GtkCellRenderer</link> into a single
725 <link linkend="GtkTreeViewColumn">GtkTreeViewColumn</link> using
727 linkend="gtk-tree-view-column-pack-start">gtk_tree_view_column_pack_start()</link> or <link linkend="gtk-tree-view-column-pack-end">gtk_tree_view_column_pack_end()</link>. So pack both a <link
728 linkend="GtkCellRendererPixbuf">GtkCellRendererPixbuf</link>
730 linkend="GtkCellRendererText">GtkCellRendererText</link> into the
738 I can set data easily on my <link
739 linkend="GtkTreeStore">GtkTreeStore</link>/<link
740 linkend="GtkListStore">GtkListStore</link> models using <link
741 linkend="gtk-tree-model-get">gtk_list_store_set()</link> and <link
742 linkend="gtk-tree-model-get">gtk_tree_store_set()</link>, but can't read
749 linkend="GtkTreeStore">GtkTreeStore</link> and the <link
750 linkend="GtkListStore">GtkListStore</link> implement the
751 <link linkend="GtkTreeModel">GtkTreeModel</link>
752 interface. Consequentially, the can use any function
753 this interface implements. The easiest way to read a
754 set of data back is to use
756 linkend="gtk-tree-model-get">gtk_tree_model_get()</link>.
763 How do I change the way that numbers are formatted by <link linkend="GtkTreeView">GtkTreeView</link>?
766 Use <link linkend="gtk-tree-view-insert-column-with-data-func">gtk_tree_view_insert_column_with_data_func()</link>
767 or <link linkend="gtk-tree-view-column-set-cell-data-func">gtk_tree_view_column_set_cell_data_func()</link>
768 and do the conversion from number to string yourself (with, say,
769 <link linkend="g-strdup-printf">g_strdup_printf()</link>).
773 The following example demonstrates this:
774 <informalexample><programlisting>
781 GtkListStore *mycolumns;
782 GtkTreeView *treeview;
785 my_cell_double_to_text (GtkTreeViewColumn *tree_column,
786 GtkCellRenderer *cell,
787 GtkTreeModel *tree_model,
791 GtkCellRendererText *cell_text = (GtkCellRendererText *)cell;
795 /* Get the double value from the model. */
796 gtk_tree_model_get (tree_model, iter, (gint)data, &d, -1);
797 /* Now we can format the value ourselves. */
798 text = g_strdup_printf ("%.2f", d);
799 g_object_set (cell, "text", text, NULL);
804 set_up_new_columns (GtkTreeView *myview)
806 GtkCellRendererText *renderer;
807 GtkTreeViewColumn *column;
808 GtkListStore *mycolumns;
810 /* Create the data model and associate it with the given TreeView */
811 mycolumns = gtk_list_store_new (N_COLUMNS, G_TYPE_DOUBLE);
812 gtk_tree_view_set_model (myview, GTK_TREE_MODEL (mycolumns));
814 /* Create a GtkCellRendererText */
815 renderer = gtk_cell_renderer_text_new ();
817 /* Create a new column that has a title ("Example column"),
818 * uses the above created renderer that will render the double
819 * value into text from the associated model's rows.
821 column = gtk_tree_view_column_new ();
822 gtk_tree_view_column_set_title (column, "Example column");
823 renderer = gtk_cell_renderer_text_new ();
824 gtk_tree_view_column_pack_start (column, renderer, TRUE);
826 /* Append the new column after the GtkTreeView's previous columns. */
827 gtk_tree_view_append_column (GTK_TREE_VIEW (myview), column);
828 /* Since we created the column by hand, we can set it up for our
829 * needs, e.g. set its minimum and maximum width, etc.
831 /* Set up a custom function that will be called when the column content
832 * is rendered. We use the func_data pointer as an index into our
833 * model. This is convenient when using multi column lists.
835 gtk_tree_view_column_set_cell_data_func (column, renderer,
836 my_cell_double_to_text,
837 (gpointer)DOUBLE_COLUMN, NULL);
839 </programlisting></informalexample>