<refentry id="gtk-question-index" revision="1 Jan 2002"><refmeta><refentrytitle>Common Questions</refentrytitle><manvolnum>3</manvolnum><refmiscinfo>Common Questions</refmiscinfo></refmeta><refnamediv><refname>Common Questions</refname><refpurpose>Find answers to common questions in the GTK+ manual</refpurpose></refnamediv><refsect1><title>Questions and Answers</title><para>This is an "index" of the reference manual organized by common "How doI..." questions. If you aren't sure which documentation to read forthe question you have, this list is a good place to start.</para><qandaset><qandadiv><title>General</title><qandaentry><question><para>How do I get started with GTK+?</para></question><answer><para>The GTK+ <ulink url="http://www.gtk.org">website</ulink> offers a <ulink url="http://www.gtk.org/tutorial">tutorial</ulink> and a <ulink url="http://www.gtk.org/faq">FAQ</ulink>. More documentation rangingfrom whitepapers to online books can be found at the<ulink url="http://developer.gnome.org/doc">GNOME developer's site</ulink>.After studying these materials you should be well prepared to come back tothis reference manual for details.</para></answer></qandaentry><qandaentry><question><para>Where can I get help with GTK+, submit a bug report, or make a feature request?</para></question><answer><para>See the <link linkend="gtk-resources">documentation on this topic</link>.</para></answer></qandaentry><qandaentry><question><para>How do I port from one GTK+version to another?</para></question><answer><para>See the <link linkend="gtk-changes-2-0">list of incompatible changesfrom 1.2 to 2.0</link>. Also, the <ulinkurl="http://developer.gnome.org/dotplan/porting/">GNOME 2.0 portingguide</ulink> on <ulinkurl="http://developer.gnome.org">http://developer.gnome.org</ulink>has some more detailed discussion of porting from 1.2 to 2.0.You may also find useful information in the documentation for specific widgets and functions.</para><para>If you have a question not covered in the manual, feel free toask on the mailing lists and please <ulinkurl="http://bugzilla.gnome.org">file a bug report</ulink> against thedocumentation.</para></answer></qandaentry><qandaentry><question><para>How does memory management work in GTK+? Should I free data returnedfrom functions?</para></question><answer><para>See the documentation for <link linkend="GObject">GObject</link> and<link linkend="GtkObject">GtkObject</link>. For <linklinkend="GObject">GObject</link> note specifically <linklinkend="g-object-ref">g_object_ref()</link> and <linklinkend="g-object-unref">g_object_unref()</link>. <linklinkend="GtkObject">GtkObject</link> is a subclass of <linklinkend="GObject">GObject</link> so the same points apply, except thatit has a "floating" state (explained in its documentation).</para><para>For strings returned from functions, they will be declared "const"(using <link linkend="G-CONST-RETURN-CAPS">G_CONST_RETURN</link>) if theyshould not be freed. Non-const strings should be freed with <linklinkend="g-free">g_free()</link>. Arrays follow the same rule.  (Ifyou find an exception to the rules, please report a bug to <ulinkurl="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.)</para></answer></qandaentry><qandaentry><question><para>Why does my program leak memory, if I destroy a widget immediately after creating it ?</para></question><answer><para>If <structname>GtkFoo</structname> isn't a toplevel window, then<informalexample><programlisting> foo = gtk_foo_new (<!-- -->); gtk_widget_destroy (foo);</programlisting></informalexample>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.</para><para>To to get this, you must acquire a reference to the widget and drop the floating reference (<quote>ref and sink</quote> in GTK+ parlance) after creating it:<informalexample><programlisting> foo = gtk_foo_new (<!-- -->); g_object_ref (foo);  gtk_object_sink (GTK_OBJECT (foo));</programlisting></informalexample>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:<informalexample><programlisting> gtk_widget_destroy (foo);  g_object_unref (foo); </programlisting></informalexample>When you immediately add a widget to a container, it takes care ofassuming the initial floating reference and you don't have to worryabout reference counting at all ... just call gtk_widget_destroy()to get rid of the widget.</para></answer></qandaentry><qandaentry><question><para>How do I use GTK+ with threads?</para></question><answer><para>This is covered in the <link linkend="gdk-Threads">GDK threads documentation</link>. See also the <link linkend="glib-Threads">GThread</link> documentation for portablethreading primitives.</para></answer></qandaentry><qandaentry><question><para>How do I internationalize a GTK+ program?</para></question><answer><para>Most people use <ulink url="http://www.gnu.org/software/gettext/">GNUgettext</ulink>, already required in order to install GLib. On a UNIXor Linux system with gettext installed, type <literal>infogettext</literal> to read the documentation.</para><para>The short checklist on how to use gettext is: call<function>bindtextdomain()</function> so gettext can find the filescontaining your translations, call <function>textdomain()</function>to set the default translation domain, then call<function>gettext()</function> to look up each string to be translatedin the default domain. Conventionally, people define macros asfollows for convenience:<informalexample><programlisting>  #define  _(x)  gettext (x)  #define N_(x)  x</programlisting></informalexample>You use <function>N_()</function> (N stands for no-op) to mark a string for translation in a context where a function call to <function>gettext()</function> is not allowed, such as in an array initializer. You eventually have to call<function>gettext()</function> on the string to actually fetch thetranslation.  <function>_()</function> both marks the string for translation and actually translates it.</para><para>Code using these macros ends up looking like this:<informalexample><programlisting> #include &lt;libintl.h&gt; #define  _(x)  gettext (x) #define N_(x)  x 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));...</programlisting></informalexample></para><para>Libraries using gettext should use <function>dgettext()</function>instead of <function>gettext()</function>, which allowsthem to specify the translation domain each time they ask for a translation. Libraries should also avoid calling <function>textdomain()</function>, since they'll be specifying the domain instead of using the default.For <function>dgettext()</function> the <function>_()</function> macrocan be defined as:<informalexample><programlisting>  #define _(x) dgettext ("MyDomain", x)</programlisting></informalexample></para></answer></qandaentry><qandaentry><question><para>How do I use non-ASCII characters in GTK+ programs ?</para></question><answer><para>GTK+ uses <ulink url="http://www.unicode.org">Unicode</ulink> (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:<itemizedlist><listitem><para>ASCII characters are encoded by their familiar ASCII codepoints.</para></listitem><listitem><para>ASCII characters never appear as part of any other character.</para></listitem><listitem><para>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.</para></listitem></itemizedlist>More information about Unicode and UTF-8 can be found in the <ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode FAQ for Unix/Linux</ulink>.GLib provides functions for converting strings between UTF-8 and other	      encodings, see <link linkend="g-locale-to-utf8">g_locale_to_utf8()</link> and <link		linkend="g-convert">g_convert()</link>.</para><para>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 <literal>stdout</literal>:<informalexample><programlisting>gchar *text, *utf8_text;gsize length;GError *error = NULL;if (g_file_get_contents (filename, &amp;text, &amp;length, NULL))   {     utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1",                             NULL, NULL, &amp;error);     if (error != NULL)       {         fprintf ("Couldn't convert file &percnt;s to UTF-8\n", filename);         g_error_free (error);       }     else       g_print (utf8_text);  }else   fprintf (stderr, "Unable to read file &percnt;s\n", filename);</programlisting></informalexample></para><para>For string literals in the source code, there are several alternatives for	      handling non-ASCII content:<variablelist><varlistentry><term>direct UTF-8</term><listitem><para>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 allowsyou to edit the strings in "wysiwyg". Note that choosing this option may