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

<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> functions
are declared as <literal>G_GNUC_CONST</literal> which allows the compiler to optimize
the 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>
</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 change the font of a widget?
</para></question>

<answer><para>
This has several possible answers, depending on what exactly you want to
achieve. One option is <link
linkend="gtk-widget-modify-font">gtk_widget_modify_font()</link>. Note that this function can be used to change only the font size, as in the following example:
<programlisting>
 PangoFontDesc *font_desc = pango_font_description_new ();
 pango_font_description_set_size (font_desc, 40);
 gtk_widget_modify_font (widget, font);
 pango_font_description_free (font_desc);
</programlisting>
</para>
<para>
If you want to make the text of a label larger, you can use <link
linkend="gtk-label-set-markup">gtk_label_set_markup()</link>:
<programlisting>
gtk_label_set_markup (label, "&lt;big&gt;big text&lt;/big&gt;");
</programlisting>
This is preferred for many apps because it's a relative size to the 
user's chosen font size. See <link 
linkend="g-markup-escape-text">g_markup_escape_text()</link> 
if you are constructing such strings on the fly.
</para>
<para>
You can also change the font of a widget by putting
<programlisting>
 gtk-font-name = "Sans 30"
</programlisting>
in 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
font you've chosen. See
<link linkend="gtk-Resource-Files">GTK+ resource files</link> for more
discussion. 
</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>

<qandaentry>
<question><para>
How do I make a text widget display its complete contents in a specific font?
</para></question>

<answer><para>
If you use <link
	      linkend="gtk-text-buffer-insert-with-tags">gtk_text_buffer_insert_with_tags()</link> with appropriate tags to select the font, the inserted text will have the desired appearance, but text typed in by the user before or after the tagged block will appear in the default style. 
</para>
<para>
To ensure that all text has the desired appearance, use <link
		linkend="gtk-widget-modify-font">gtk_widget_modify_font()</link> to change the default font for the widget.
</para></answer>
</qandaentry>

<qandaentry>
<question>
<para>
How do I make a text view scroll to the end of the buffer automatically ?
</para>
</question>

<answer>
<para>
The "insert" <link linkend="GtkTextMark">mark</link> marks the insertion point
where <link linkend="gtk-text-buffer-insert">gtk_text_buffer_insert()</link>
inserts new text into the buffer. The text is inserted 
<emphasis>before</emphasis> the "insert" mark, so that it generally stays 
at the end of the buffer. If it gets explicitly moved to some other position, 
e.g. when the user selects some text, 
use <link linkend="gtk-text-buffer-move-mark">gtk_text_buffer_move_mark()</link>
to set it to the desired location before inserting more text. 
The "insert" mark of a buffer can be obtained with <link
linkend="gtk-text-buffer-get-insert">gtk_text_buffer_get_insert()</link>.
</para>

<para> 
To ensure that the end of the buffer remains visible, use
<link
		linkend="gtk-text-view-scroll-to-mark">gtk_text_view_scroll_to_mark()</link> to scroll to the "insert" mark after inserting new text.
</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 <link linkend="GtkTreeView">GtkTreeView</link> equivalent of 
<link linkend="gtk-clist-find-row-from-data">gtk_clist_find_row_from_data()</link>?
</para></question>

<answer>
<para>
As there is no separate data column in the <link linkend="GtkTreeModel">GtkTreeModel</link>, 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
<link linkend="gtk-tree-model-foreach">gtk_tree_model_foreach()</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>

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

<qandaentry>
<question><para>
How do I change the way that numbers are formatted by <link linkend="GtkTreeView">GtkTreeView</link>?
</para></question>
<answer><para>
Use <link linkend="gtk-tree-view-insert-column-with-data-func">gtk_tree_view_insert_column_with_data_func()</link> 
or <link linkend="gtk-tree-view-column-set-cell-data-func">gtk_tree_view_column_set_cell_data_func()</link>
and do the conversion from number to string yourself (with, say, 
<link linkend="g-strdup-printf">g_strdup_printf()</link>).
</para>

<para>
The following example demonstrates this:
<informalexample><programlisting>
enum 
{
  DOUBLE_COLUMN,
  N_COLUMNS
};

GtkListStore *mycolumns;
GtkTreeView *treeview;

void 
my_cell_double_to_text (GtkTreeViewColumn *tree_column,
	                GtkCellRenderer   *cell, 
                        GtkTreeModel      *tree_model,
	                GtkTreeIter       *iter, 
                        gpointer           data)
{
  GtkCellRendererText *cell_text = (GtkCellRendererText *)cell;
  gdouble d;
  gchar *text;

  /* Get the double value from the model. */
  gtk_tree_model_get (tree_model, iter, (gint)data, &amp;d, -1);
  /* Now we can format the value ourselves. */
  text = g_strdup_printf ("&percnt;.2f", d);
  g_object_set (cell, "text", text, NULL);
  g_free (text);
}

void 
set_up_new_columns (GtkTreeView *myview)
{
  GtkCellRendererText *renderer;
  GtkTreeViewColumn *column;
  GtkListStore *mycolumns;

  /* Create the data model and associate it with the given TreeView */
  mycolumns = gtk_list_store_new (N_COLUMNS, G_TYPE_DOUBLE);
  gtk_tree_view_set_model (myview, GTK_TREE_MODEL (mycolumns));

  /* Create a GtkCellRendererText */
  renderer = gtk_cell_renderer_text_new ();

  /* Create a new column that has a title ("Example column"),
   * uses the above created renderer that will render the double
   * value into text from the associated model's rows. 
   */
  column = gtk_tree_view_column_new ();
  gtk_tree_view_column_set_title  (column, "Example column");
  renderer = gtk_cell_renderer_text_new ();
  gtk_tree_view_column_pack_start (column, renderer, TRUE);

  /* Append the new column after the GtkTreeView's previous columns. */
  gtk_tree_view_append_column (GTK_TREE_VIEW (myview), column);
  /* Since we created the column by hand, we can set it up for our
   * needs, e.g. set its minimum and maximum width, etc.
   */
  /* Set up a custom function that will be called when the column content
   * is rendered. We use the func_data pointer as an index into our
   * model. This is convenient when using multi column lists. 
   */
  gtk_tree_view_column_set_cell_data_func (column, renderer,
	                                   my_cell_double_to_text, 
                                           (gpointer)DOUBLE_COLUMN, NULL);
}
</programlisting></informalexample>
</para></answer>
</qandaentry>

</qandadiv>



</qandaset>

</refsect1>

</refentry>