question_index.sgml

This GTK+ version 2.12.3. GTK+ is a multi-platform toolkit for creating graphical user interfaces.

<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 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.
</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 ranging
from 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 to
this 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 changes
from 1.2 to 2.0</link>. Also, the <ulink
url="http://developer.gnome.org/dotplan/porting/">GNOME 2.0 porting
guide</ulink> on <ulink
url="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 to
ask on the mailing lists and please <ulink
url="http://bugzilla.gnome.org">file a bug report</ulink> against the
documentation.
</para>

</answer>

</qandaentry>


<qandaentry>
<question><para>
How does memory management work in GTK+? Should I free data returned
from functions?
</para></question>

<answer>

<para>
See the documentation for #GObject and #GtkObject. For #GObject note 
specifically g_object_ref() and g_object_unref(). #GtkObject is a subclass 
of #GObject so the same points apply, except that it has a "floating" state 
(explained in its documentation).
</para>

<para>
For strings returned from functions, they will be declared "const" (using 
#G_CONST_RETURN) if they should not be freed. Non-const strings should be 
freed with g_free(). Arrays follow the same rule.  (If you find an exception 
to the rules, please report a bug to <ulink 
url="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 of
assuming the initial floating reference and you don't have to worry
about 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 portable threading 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/">GNU
gettext</ulink>, already required in order to install GLib. On a UNIX
or Linux system with gettext installed, type <literal>info gettext</literal> 
to read the documentation.
</para>
<para>
The short checklist on how to use gettext is: call bindtextdomain() so gettext 
can find the files containing your translations, call textdomain() to set the 
default translation domain, then call gettext() to look up each string to be 
translated in the default domain. Conventionally, people define macros as
follows for convenience:
<informalexample>
<programlisting>
  #define  _(x)  gettext (x)
  #define N_(x)  x
</programlisting>
</informalexample>
You use N_() (N stands for no-op) to mark a string for translation in a 
context where a function call to gettext() is not allowed, such as in an 
array initializer. 
You eventually have to call gettext() on the string to actually fetch the
translation.  _() both marks the string for translation and actually 
translates it.
</para>
<para>
Nowadays, GLib provides the common shorthand macros in the header file
<filename>gi18n.h</filename>, so you don't have to define them yourself, 
just include that header.
</para>
<para>
Code using these macros ends up looking like this:
<informalexample>
<programlisting>
 #include &lt;gi18n.h&gt;

 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 dgettext() instead of gettext(), which 
allows them to specify the translation domain each time they ask for a 
translation. Libraries should also avoid calling textdomain(), since they
will be specifying the domain instead of using the default. For dgettext() 
the _() macro can be defined as:
<informalexample>
<programlisting>
  #define _(x) dgettext ("MyDomain", x)
</programlisting>
</informalexample>
</para>
<para>
Again, GLib comes with the <filename>gi18n-lib.h</filename>, saving you the 
trouble of defining the macros by hand. The macros in that header expect the 
translation domain to be specified by the %GETTEXT_PACKAGE macro. 
</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 i
FAQ for Unix/Linux</ulink>.
GLib provides functions for converting strings between UTF-8 and other
encodings, see g_locale_to_utf8() and g_convert().
</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 allows
you to edit the strings in "wysiwyg". Note that choosing this option may 
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 string
literals in UTF-8 by using octal or hexadecimal escapes like 
<literal>\212</literal> or <literal>\xa8</literal> to
encode each byte. This is portable, but modifying the escaped strings is not
very 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 toolchain
can handle (e.g. IS0-8859-1), you can write your source files in that encoding
and use g_convert() to convert the strings to UTF-8 at runtime. Note that this 
has some runtime overhead, so you may want to move 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 in
UTF-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 native C++ API.
</para>
<para>
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.
</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 following
code:
<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 language
bindings</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 
gtk_image_new_from_file() <footnote><para> If the file load fails, 
gtk_image_new_from_file() will display no image graphic &mdash; to detect 
a failed load yourself, use gdk_pixbuf_new_from_file() directly, then 
gtk_image_new_from_pixbuf().</para></footnote>. 
To load an image for another purpose, use gdk_pixbuf_new_from_file(). To i
load an animation, use gdk_pixbuf_animation_new_from_file().
gdk_pixbuf_animation_new_from_file() can also load non-animated images, so 
use it in combination with gdk_pixbuf_animation_is_static_image() to load a 
file of unknown type. 
</para>
<para>
To load an image or animation file asynchronously (without blocking), use 
#GdkPixbufLoader.
</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 gdk_draw_layout(), 
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 #GdkFont and gdk_draw_text().
</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 
pango_layout_get_pixel_size(), 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 gdk_text_width().
</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>