reduce the portability of your code.  </para></listitem></varlistentry><varlistentry><term>escaped UTF-8</term><listitem><para>Even if your toolchain can't handle UTF-8 directly, you can still encode stringliterals in UTF-8 by using octal or hexadecimal escapes like <literal>\212</literal> or <literal>\xa8</literal> toencode each byte. This is portable, but modifying the escaped strings is notvery convenient. Be careful when mixing hexadecimal escapes with ordinary text;<literal>"\xa8abcd"</literal> is a string of length 1 !</para></listitem></varlistentry><varlistentry><term>runtime conversion</term><listitem><para>If the string literals can be represented in an encoding which your toolchaincan handle (e.g. IS0-8859-1), you can write your source files in that encodingand use <link linkend="g-convert">g_convert()</link> to convert the strings to UTF-8 at runtime. Note that this has some runtime overhead, so you may want tomove the conversion out of inner loops.</para></listitem></varlistentry></variablelist>Here is an example showing the three approaches using the copyright sign &copy; which has Unicode and ISO-8859-1 codepoint 169 and is represented inUTF-8 by the two bytes 194, 169:<informalexample><programlisting>g_print ("direct UTF-8: &copy;");g_print ("escaped UTF-8: \302\251");text = g_convert ("runtime conversion: &copy;", -1, "ISO-8859-1", "UTF-8", NULL, NULL, NULL);g_print(text);g_free (text);</programlisting></informalexample></para></answer></qandaentry><qandaentry><question><para>How do I use GTK+ with C++?</para></question><answer><para>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 <ulink url="http://gtkmm.sourceforge.net/">gtkmm</ulink>which provides a C++-native API.</para><para>When using GTK+ directly, keep in mind that only functions can beconnected to signals, not methods. So you will need to use globalfunctions or "static" class functions for signal connections.</para><para>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 followingcode:<informalexample><programlisting>  gdk_window_set_events (gdk_window,                          GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);</programlisting></informalexample>while in C++ you must write:<informalexample><programlisting>  gdk_window_set_events (gdk_window,                          (GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);</programlisting></informalexample>There are very few functions that require this cast, however.</para></answer></qandaentry><qandaentry><question><para>How do I use GTK+ with other non-C languages?</para></question><answer><para>See the <ulink url="http://www.gtk.org/bindings.html">list of languagebindings</ulink> on <ulink                           url="http://www.gtk.org">http://www.gtk.org</ulink>.</para></answer></qandaentry><qandaentry><question><para>How do I load an image or animation from a file?</para></question><answer><para>To load an image file straight into a display widget, use <linklinkend="gtk-image-new-from-file">gtk_image_new_from_file()</link><footnote><para> If the file load fails, <linklinkend="gtk-image-new-from-file">gtk_image_new_from_file()</link>will display a "broken image" graphic &mdash; to detect a failed loadyourself, use <linklinkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>directly then <linklinkend="gtk-image-new-from-pixbuf">gtk_image_new_from_pixbuf()</link>.</para></footnote>. To load an image for another purpose, use <linklinkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>.To load an animation, use <linklinkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file()</link>.<linklinkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file()</link>can also load non-animated images, so use it in combination with <link      linkend="gdk-pixbuf-animation-is-static-image">gdk_pixbuf_animation_is_static_image()</link> to load a file of unknown type. </para><para>To load an image or animation file asynchronously (without blocking), use <link linkend="GdkPixbufLoader">GdkPixbufLoader</link>.</para></answer></qandaentry><qandaentry><question><para>How do I draw text ?</para></question><answer><para>To draw a piece of text, use a Pango layout and <link linkend="gdk-draw-layout">gdk_draw_layout()</link>, using code like the following:<informalexample><programlisting> 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);</programlisting></informalexample>Do not use the deprecated <link linkend="GdkFont">GdkFont</link> and <link linkend="gdk-draw-text">gdk_draw_text()</link>.</para><para>See also the "Text Handling in GTK 2" section of <ulink url="http://developer.gnome.org/dotplan/porting/">Porting applications to the GNOME 2.0 platform</ulink>.</para></answer></qandaentry><qandaentry><question><para>How do I measure the size of a piece of text ?</para></question><answer><para>To obtain the size of a piece of text, use a Pango layout and <link		linkend="pango-layout-get-pixel-size">pango_layout_get_pixel_size()</link>, using code like the following:<informalexample><programlisting> 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, &amp;width, &amp;height); pango_font_description_free (fontdesc); g_object_unref (layout);</programlisting></informalexample>Do not use the deprecated function <link linkend="gdk-text-width">gdk_text_width()</link>.</para><para>See also the "Text Handling in GTK 2" section of <ulink url="http://developer.gnome.org/dotplan/porting/">Porting applications to the GNOME 2.0 platform</ulink>.</para></answer></qandaentry><qandaentry><question><para>Why are types not registered if I use their <literal>GTK_TYPE_BLAH</literal> macro ?</para></question><answer><para>The <literal>GTK_TYPE_BLAH</literal> macros are defined as calls to <literal>gtk_blah_get_type()</literal>, and the <literal>_get_type()</literal> functionsare declared as <literal>G_GNUC_CONST</literal> which allows the compiler to optimizethe call away if it appears that the value is not being used.</para><para>A common workaround for this problem is to store the result in a volatile variable,which keeps the compiler from optimizing the call away.<informalexample><programlisting>volatile GType dummy = GTK_TYPE_BLAH;</programlisting></informalexample></para></answer></qandaentry></qandadiv><qandadiv><title>Which widget should I use...</title><qandaentry><question><para>...for lists and trees?</para></question><answer><para>See <link linkend="TreeWidget">tree widget overview</link> &mdash; youshould use the <link linkend="GtkTreeView">GtkTreeView</link> widget.(A list is just a tree with no branches, so the tree widget is usedfor lists as well.) Do not use the deprecated widgets <linklinkend="GtkTree">GtkTree</link> or <linklinkend="GtkCList">GtkCList</link>/<linklinkend="GtkCTree">GtkCTree</link> in newly-written code, they areless flexible and result in an inferior user interface.</para></answer></qandaentry><qandaentry><question><para>...for multi-line text display or editing?</para></question><answer><para>See <link linkend="TextWidget">text widget overview</link> &mdash; youshould use the <link linkend="GtkTextView">GtkTextView</link> widget.Do not use the deprecated widget <linklinkend="GtkText">GtkText</link> in newly-written code, it has anumber of problems that are best avoided.</para><para>If you only have a small amount of text, <linklinkend="GtkLabel">GtkLabel</link> may also be appropriate of course.It can be made selectable with <link linkend="gtk-label-set-selectable">gtk_label_set_selectable()</link>. For a single-line text entry, see <link linkend="GtkEntry">GtkEntry</link>.</para></answer></qandaentry><qandaentry><question><para>...to display an image or animation?</para></question><answer><para><link linkend="GtkImage">GtkImage</link> can display imagesin just about any format GTK+ understands. You can also use <link linkend="GtkDrawingArea">GtkDrawingArea</link> if you need to do something more complex, such as draw text or graphics over thetop of the image.</para></answer></qandaentry><qandaentry><question><para>...for presenting a set of mutually-exclusive choices, where Windowswould use a combo box?</para></question><answer><para>With GTK+, a <link linkend="GtkOptionMenu">GtkOptionMenu</link> isrecommended instead of a combo box, if the user is selecting from afixed set of options. That is, non-editable combo boxes are notencouraged. <link linkend="GtkOptionMenu">GtkOptionMenu</link> ismuch easier to use than <link linkend="GtkCombo">GtkCombo</link>as well. Use <link linkend="GtkCombo">GtkCombo</link> only when you need the editable text entry.</para><para>(As a future enhancement to GTK+, a new widget to replace <linklinkend="GtkOptionMenu">GtkOptionMenu</link> and <linklinkend="GtkCombo">GtkCombo</link> is planned.  This widget will bethemeable to look like either a combo box or the current option menu,and will address some shortcomings in the <linklinkend="GtkCombo">GtkCombo</link> API.  <ulinkurl="http://bugzilla.gnome.org/show_bug.cgi?id=50554">Bug50554</ulink> tracks this issue, if you want to check status or postcomments.)</para></answer></qandaentry></qandadiv><qandadiv><title><link linkend="GtkWidget">GtkWidget</link></title><qandaentry><question><para>How do I change the color of a widget?</para></question><answer><para>See <link linkend="gtk-widget-modify-fg">gtk_widget_modify_fg()</link>,