<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>
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 <link linkend="GObject">GObject</link> and
<link linkend="GtkObject">GtkObject</link>. For <link
linkend="GObject">GObject</link> note specifically <link
linkend="g-object-ref">g_object_ref()</link> and <link
linkend="g-object-unref">g_object_unref()</link>. <link
linkend="GtkObject">GtkObject</link> is a subclass of <link
linkend="GObject">GObject</link> 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 <link linkend="G-CONST-RETURN-CAPS">G_CONST_RETURN</link>) if they
should not be freed. Non-const strings should be freed with <link
linkend="g-free">g_free()</link>. 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>
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
<function>bindtextdomain()</function> so gettext can find the files
containing your translations, call <function>textdomain()</function>
to set the default translation domain, then call
<function>gettext()</function> 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 <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 the
translation.  <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 allows
them 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> macro
can be defined as:
<informalexample>
<programlisting>
  #define _(x) dgettext ("MyDomain", x)
</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 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 <link
linkend="gtk-image-new-from-file">gtk_image_new_from_file()</link>
<footnote><para> If the file load fails, <link
linkend="gtk-image-new-from-file">gtk_image_new_from_file()</link>
will display a "broken image" graphic &mdash to detect a failed load
yourself, use <link
linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>
directly then <link
linkend="gtk-image-new-from-pixbuf">gtk_image_new_from_pixbuf()</link>.
</para></footnote>. To load an image for another purpose, use <link
linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>.
To load an animation, use <link
linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file()</link>.
<link
linkend="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>


</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 you
should use the <link linkend="GtkTreeView">GtkTreeView</link> widget.
(A list is just a tree with no branches, so the tree widget is used
for lists as well.) Do not use the deprecated widgets <link
linkend="GtkTree">GtkTree</link> or <link
linkend="GtkCList">GtkCList</link>/<link
linkend="GtkCTree">GtkCTree</link> in newly-written code, they are
less 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 you
should use the <link linkend="GtkTextView">GtkTextView</link> widget.
Do not use the deprecated widget <link
linkend="GtkText">GtkText</link> in newly-written code, it has a
number of problems that are best avoided.
</para>
<para>
If you only have a small amount of text, <link
linkend="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 images
in 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 the
top of the image.
</para>
</answer>
</qandaentry>

<qandaentry>
<question><para>
...for presenting a set of mutually-exclusive choices, where Windows
would use a combo box?
</para></question>

<answer>
<para>
With GTK+, a <link linkend="GtkOptionMenu">GtkOptionMenu</link> is
recommended instead of a combo box, if the user is selecting from a
fixed set of options. That is, non-editable combo boxes are not
encouraged. <link linkend="GtkOptionMenu">GtkOptionMenu</link> is
much 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 <link
linkend="GtkOptionMenu">GtkOptionMenu</link> and <link
linkend="GtkCombo">GtkCombo</link> is planned.  This widget will be
themeable to look like either a combo box or the current option menu,
and will address some shortcomings in the <link
linkend="GtkCombo">GtkCombo</link> API.  <ulink
url="http://bugzilla.gnome.org/show_bug.cgi?id=50554">Bug
50554</ulink> tracks this issue, if you want to check status or post
comments.)
</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>,
<link linkend="gtk-widget-modify-bg">gtk_widget_modify_bg()</link>,
<link linkend="gtk-widget-modify-base">gtk_widget_modify_base()</link>,
and <link
linkend="gtk-widget-modify-text">gtk_widget_modify_text()</link>.  See
<link linkend="gtk-Resource-Files">GTK+ resource files</link> for more
discussion. You can also change widget color by installing a resource
file and parsing it with <link
linkend="gtk-rc-add-default-file">gtk_rc_add_default_file()</link>.
The advantage of a resource file is that users can then override the
color you've chosen.
</para>

<para>To change the background color for widgets such as <link
linkend="GtkLabel">GtkLabel</link> that have no background, place them
in a <link linkend="GtkEventBox">GtkEventBox</link> and set the
background of the event box.  
</para></answer>
</qandaentry>

<qandaentry>
<question><para>
How do I disable/ghost/desensitize a widget?
</para></question>

<answer><para> In GTK+ a disabled widget is termed "insensitive." See
<link
linkend="gtk-widget-set-sensitive">gtk_widget_set_sensitive()</link>.
</para></answer>
</qandaentry>

</qandadiv>


<qandadiv><title><link linkend="GtkTextView">GtkTextView</link></title>

<qandaentry>
<question><para>
How do I get the contents of the entire text widget as a string?
</para></question>

<answer><para>

See <link
          linkend="gtk-text-buffer-get-bounds">gtk_text_buffer_get_bounds()</link>
          and <link
          linkend="gtk-text-buffer-get-text">gtk_text_buffer_get_text()</link>
or <link
          linkend="gtk-text-iter-get-text">gtk_text_iter_get_text()</link>.
</para>
<para>
<informalexample><programlisting>
  GtkTextIter start, end;
  GtkTextBuffer *buffer;
  char *text;

  buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (text_view));
  gtk_text_buffer_get_bounds (buffer, &amp;start, &amp;end);
  text = gtk_text_iter_get_text (&amp;start, &amp;end);
  /* use text */
  g_free (text);
</programlisting></informalexample>
</para></answer>
</qandaentry>

</qandadiv>



<qandadiv><title><link linkend="GtkTreeView">GtkTreeView</link></title>

<qandaentry>
<question><para>
How do I associate some data with a row in the tree?
</para></question>

<answer>
<para>
Remember that the <link linkend="GtkTreeModel">GtkTreeModel</link>
columns don't necessarily have to be displayed. So you can put
non-user-visible data in your model just like any other data, and
retrieve it with <link
linkend="gtk-tree-model-get">gtk_tree_model_get()</link>.
See the <link linkend="TreeWidget">tree widget overview</link>.
</para>
</answer>
</qandaentry>

<qandaentry>
<question><para>
What's the #GtkTreeView equivalent of gtk_clist_find_row_from_data()?
</para></question>

<answer>
<para>
As there is no separate data column in the #GtkTreeModel, there's no
built in function to find the iter from data.  You can write a custom
searching function to walk the tree and find the data, or use
gtk_tree_model_foreach().
</para>
</answer>
</qandaentry>

<qandaentry>
<question><para>
How do I put an image and some text in the same column?
</para></question>

<answer>
<para>
You can pack more than one <link
linkend="GtkCellRenderer">GtkCellRenderer</link> into a single
<link linkend="GtkTreeViewColumn">GtkTreeViewColumn</link> using
<link
      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
linkend="GtkCellRendererPixbuf">GtkCellRendererPixbuf</link>
and a <link
linkend="GtkCellRendererText">GtkCellRendererText</link> into the
column.
</para>
</answer>
</qandaentry>

<qandaentry>
<question><para>
I can set data easily on my <link
		linkend="GtkTreeStore">GtkTreeStore</link>/<link
		linkend="GtkListStore">GtkListStore</link> models using  <link
linkend="gtk-tree-model-get">gtk_list_store_set()</link> and <link
linkend="gtk-tree-model-get">gtk_tree_store_set()</link>, but can't read
	      it back?
</para></question>

<answer>
<para>
Both the <link
		linkend="GtkTreeStore">GtkTreeStore</link> and the <link
		linkend="GtkListStore">GtkListStore</link> implement the
	      <link linkend="GtkTreeModel">GtkTreeModel</link>
		interface.  Consequentially, the can use any function
		this interface implements.  The easiest way to read a
		set of data back is to use
 <link
linkend="gtk-tree-model-get">gtk_tree_model_get()</link>.
</para>
</answer>
</qandaentry>

</qandadiv>



</qandaset>

</refsect1>

</refentry>
