path: root/docs/reference/gtk/question_index.sgml

<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 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>
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>

</qandadiv>



</qandaset>

</refsect1>

</refentry>