<chapter id="gtk-question-index">
  <title>Common Questions</title>
  <para>
    This is an <quote>index</quote> of the reference manual organized by
    common <quote>How do I…</quote> questions. If you aren’t sure which
    documentation to read for the question you have, this list is a good
    place to start.
  </para>
  <sect1>
    <title>General Questions</title>
    <orderedlist numeration="arabic">
      <listitem>
        <para>
          How do I get started with GTK?
        </para>
        <para>
          The GTK <ulink url="https://www.gtk.org">website</ulink>
          offers some
          <ulink url="https://www.gtk.org/documentation.php">tutorials</ulink>
          and other documentation (most of it about GTK 2.x and 3.x, but
          still somewhat applicable). This reference manual also
          contains a introductory
          <link linkend="gtk-getting-started">Getting Started</link>
          part.
        </para>
        <para>
          More documentation ranging from whitepapers to online books
          can be found at the
          <ulink url="https://developer.gnome.org">GNOME developer’s
          site</ulink>. After studying these materials you should be
          well prepared to come back to this reference manual for
          details.
        </para>
      </listitem>
      <listitem>
        <para>
          Where can I get help with GTK, submit a bug report, or make a
          feature request?
        </para>
        <para>
          See the <link linkend="gtk-resources">documentation</link> on
          this topic.
        </para>
      </listitem>
      <listitem>
        <para>
          How do I port from one GTK version to another?
        </para>
        <para>
          See the <link linkend="migrating">migration guide</link>. You
          may also find useful information in the documentation for
          specific widgets and functions. If you have a question not
          covered in the manual, feel free to ask, and please
          <ulink url="https://gitlab.gnome.org/GNOME/gtk/issues/new">file
          a bug report</ulink> against the documentation.
        </para>
      </listitem>
      <listitem>
        <para>
          How does memory management work in GTK? Should I free data
          returned from functions?
        </para>
        <para>
          See the documentation for <link linkend="GObject"><type>GObject</type></link> and <link linkend="GInitiallyUnowned"><type>GInitiallyUnowned</type></link>. For
          <link linkend="GObject"><type>GObject</type></link> note specifically <link linkend="g-object-ref"><function>g_object_ref()</function></link> and
          <link linkend="g-object-unref"><function>g_object_unref()</function></link>. <link linkend="GInitiallyUnowned"><type>GInitiallyUnowned</type></link> is a subclass of <link linkend="GObject"><type>GObject</type></link>
          so the same points apply, except that it has a
          <quote>floating</quote> state (explained in its
          documentation).
        </para>
        <para>
          For strings returned from functions, they will be declared
          <quote>const</quote> if they should not be freed. Non-const
          strings should be freed with <link linkend="g-free"><function>g_free()</function></link>. Arrays follow the same
          rule. If you find an undocumented exception to the rules,
          please
          <ulink url="https://gitlab.gnome.org/GNOME/gtk/issues/new">file
          a bug report.</ulink>.
        </para>
        <para>
          The transfer annotations for gobject-introspection that are
          part of the documentation can provide useful hints for memory
          handling semantics as well.
        </para>
      </listitem>
      <listitem>
        <para>
          Why does my program leak memory, if I destroy a widget
          immediately after creating it ?
        </para>
        <para>
          If <literal>GtkFoo</literal> isn’t a toplevel window, then
        </para>
        <programlisting>
foo = <link linkend="gtk-foo-new"><function>gtk_foo_new()</function></link>;
g_object_unref (foo);
</programlisting>
        <para>
          is a memory leak, because no one assumed the initial floating
          reference (you will get a warning about this too). 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 get this, you must acquire a reference to the widget and
          drop the floating reference (<emphasis>ref and sink</emphasis>
          in GObject parlance) after creating it:
        </para>
        <programlisting>
foo = <link linkend="gtk-foo-new"><function>gtk_foo_new()</function></link>;
g_object_ref_sink (foo);
</programlisting>
        <para>
          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 remove
          the widget from the container to get rid of it.
        </para>
      </listitem>
      <listitem>
        <para>
          How do I use GTK with threads?
        </para>
        <para>
          GTK requires that all GTK API calls are made from the same
          thread in which <link linkend="gtk-init"><function>gtk_init()</function></link> was called (the <emphasis>main
          thread</emphasis>).
        </para>
        <para>
          If you want to take advantage of multi-threading in a GTK
          application, it is usually best to send long-running tasks to
          worker threads, and feed the results back to the main thread
          using <link linkend="g-idle-add"><function>g_idle_add()</function></link> or GAsyncQueue. GIO offers useful tools for
          such an approach such as GTask.
        </para>
      </listitem>
      <listitem>
        <para>
          How do I internationalize a GTK program?
        </para>
        <para>
          Most people use
          <ulink url="https://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
          <link linkend="bindtextdomain"><function>bindtextdomain()</function></link> so gettext can find the files containing your
          translations, call <link linkend="textdomain"><function>textdomain()</function></link> to set the default translation
          domain, call <link linkend="bind-textdomain-codeset"><function>bind_textdomain_codeset()</function></link> to request that all
          translated strings are returned in UTF-8, then call <link linkend="gettext"><function>gettext()</function></link>
          to look up each string to be translated in the default domain.
        </para>
        <para>
          <literal>gi18n.h</literal> provides the following shorthand
          macros for convenience. Conventionally, people define macros
          as follows for convenience:
        </para>
        <programlisting>
#define  _(x)     gettext (x)
#define N_(x)     x
#define C_(ctx,x) pgettext (ctx, x)
</programlisting>
        <para>
          You use <link linkend="N-:CAPS"><function>N_()</function></link> (N stands for no-op) to mark a string for
          translation in a location where a function call to <link linkend="gettext"><function>gettext()</function></link>
          is not allowed, such as in an array initializer. You
          eventually have to call <link linkend="gettext"><function>gettext()</function></link> on the string to actually
          fetch the translation. <emphasis>() both marks the string for
          translation and actually translates it. The C</emphasis>()
          macro (C stands for context) adds an additional context to the
          string that is marked for translation, which can help to
          disambiguate short strings that might need different
          translations in different parts of your program.
        </para>
        <para>
          Code using these macros ends up looking like this:
        </para>
        <programlisting>
#include &lt;gi18n.h&gt;

static const char *global_variable = N_(&quot;Translate this string&quot;);

static void
make_widgets (void)
{
  GtkWidget *label1;
  GtkWidget *label2;

  label1 = gtk_label_new (_(&quot;Another string to translate&quot;));
  label2 = gtk_label_new (_(global_variable));
...
</programlisting>
        <para>
          Libraries using gettext should use <link linkend="dgettext"><function>dgettext()</function></link> instead of
          <link linkend="gettext"><function>gettext()</function></link>, which allows them to specify the translation domain
          each time they ask for a translation. Libraries should also
          avoid calling <link linkend="textdomain"><function>textdomain()</function></link>, since they will be specifying the
          domain instead of using the default.
        </para>
        <para>
          With the convention that the macro
          <literal>GETTEXT_PACKAGE</literal> is defined to hold your
          libraries translation domain, <literal>gi18n-lib.h</literal>
          can be included to provide the following convenience:
        </para>
        <programlisting>
#define _(x) dgettext (GETTEXT_PACKAGE, x)
</programlisting>
      </listitem>
      <listitem>
        <para>
          How do I use non-ASCII characters in GTK programs ?
        </para>
        <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:
        </para>
        <itemizedlist spacing="compact">
          <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 string can be manipulated with the usual C
              library functions for handling zero-terminated strings.
            </para>
          </listitem>
        </itemizedlist>
        <para>
          More information about Unicode and UTF-8 can be found in the
          <ulink url="https://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8
          and Unicode FAQ</ulink>. GLib provides functions for
          converting strings between UTF-8 and other encodings, see
          <link linkend="g-locale-to-utf8"><function>g_locale_to_utf8()</function></link> and <link linkend="g-convert"><function>g_convert()</function></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>:
        </para>
        <programlisting>
char *text, *utf8_text;
gsize length;
GError *error = NULL;

if (g_file_get_contents (filename, &amp;amp;text, &amp;amp;length, NULL))
  {
    utf8_text = g_convert (text, length, &quot;UTF-8&quot;, &quot;ISO-8859-1&quot;,
                           NULL, NULL, &amp;error);
    if (error != NULL)
      {
        fprintf (&quot;Couldn't convert file <link linkend="s"><literal>s</literal></link> to UTF-8\n&quot;, filename);
        g_error_free (error);
      }
    else
      g_print (utf8_text);
  }
else
  fprintf (stderr, &quot;Unable to read file <link linkend="s"><literal>s</literal></link>\n&quot;, filename);
</programlisting>
        <para>
          For string literals in the source code, there are several
          alternatives for handling non-ASCII content:
        </para>
        <itemizedlist>
          <listitem>
            <para>
              Direct UTF-8
            </para>
            <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 <quote>wysiwyg</quote>. Note that choosing this
              option may reduce the portability of your code.
            </para>
          </listitem>
          <listitem>
            <para>
              Escaped UTF-8
            </para>
            <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; `<quote>8abcd</quote> is a string of
              length 1 !
            </para>
          </listitem>
          <listitem>
            <para>
              Runtime conversion
            </para>
            <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"><function>g_convert()</function></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>
        </itemizedlist>
        <para>
          Here is an example showing the three approaches using the
          copyright sign © which has Unicode and ISO-8859-1 codepoint
          169 and is represented in UTF-8 by the two bytes 194, 169, or
          <literal>&quot;\302\251&quot;</literal> as a string literal:
        </para>
        <programlisting>
g_print (&quot;direct UTF-8: ©&quot;);
g_print (&quot;escaped UTF-8: \302\251&quot;);
text = g_convert (&quot;runtime conversion: ©&quot;, -1,
                  &quot;ISO-8859-1&quot;, &quot;UTF-8&quot;, NULL, NULL, NULL);
g_print (text);
g_free (text);
</programlisting>
        <para>
          If you are using <link linkend="gettext"><function>gettext()</function></link> to localize your application, you
          need to call <link linkend="bind-textdomain-codeset"><function>bind_textdomain_codeset()</function></link> to ensure that
          translated strings are returned in UTF-8 encoding.
        </para>
      </listitem>
      <listitem>
        <para>
          How do I use GTK with C++?
        </para>
        <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 <quote>C++ binding</quote> such as
          <ulink url="https://www.gtkmm.org/">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 <quote>static</quote> 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:
        </para>
        <programlisting>
gdk_surface_set_events (gdk_surface,
                        GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
</programlisting>
        <para>
          while in C++ you must write:
        </para>
        <programlisting>
gdk_surface_set_events (gdk_surface,
                        (GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
</programlisting>
        <para>
          There are very few functions that require this cast, however.
        </para>
      </listitem>
      <listitem>
        <para>
          How do I use GTK with other non-C languages?
        </para>
        <para>
          See the list of
          <ulink url="https://www.gtk.org/language-bindings.php">language
          bindings</ulink> on the GTK
          <ulink url="https://www.gtk.org">website</ulink>.
        </para>
      </listitem>
      <listitem>
        <para>
          How do I load an image or animation from a file?
        </para>
        <para>
          To load an image file straight into a display widget, use
          <link linkend="gtk-image-new-from-file"><function>gtk_image_new_from_file()</function></link>. To load an image for another
          purpose, use <link linkend="gdk-texture-new-from-file"><function>gdk_texture_new_from_file()</function></link>. To load a video from
          a file, use <link linkend="gtk-media-file-new-for-file"><function>gtk_media_file_new_for_file()</function></link>.
        </para>
      </listitem>
      <listitem>
        <para>
          How do I draw text?
        </para>
        <para>
          To draw a piece of text onto a cairo surface, use a Pango
          layout and <link linkend="pango-cairo-show-layout"><function>pango_cairo_show_layout()</function></link>.
        </para>
        <programlisting>
layout = gtk_widget_create_pango_layout (widget, text);
fontdesc = pango_font_description_from_string (&quot;Luxi Mono 12&quot;);
pango_layout_set_font_description (layout, fontdesc);
pango_cairo_show_layout (cr, layout);
pango_font_description_free (fontdesc);
g_object_unref (layout);
</programlisting>
        <para>
          See also the
          <ulink url="https://developer.gnome.org/pango/stable/pango-Cairo-Rendering.html">Cairo
          Rendering</ulink> section of the
          <ulink url="https://developer.gnome.org/pango/stable/">Pango
          documentation</ulink>.
        </para>
        <para>
          To draw a piece of text in a widget <link linkend="snapshot"><function>snapshot()</function></link> implementation,
          use <link linkend="gtk-snapshot-append-layout"><function>gtk_snapshot_append_layout()</function></link>.
        </para>
      </listitem>
      <listitem>
        <para>
          How do I measure the size of a piece of text?
        </para>
        <para>
          To obtain the size of a piece of text, use a Pango layout and
          <link linkend="pango-layout-get-pixel-size"><function>pango_layout_get_pixel_size()</function></link>, using code like the following:
        </para>
        <programlisting>
layout = gtk_widget_create_pango_layout (widget, text);
fontdesc = pango_font_description_from_string (&quot;Luxi Mono 12&quot;);
pango_layout_set_font_description (layout, fontdesc);
pango_layout_get_pixel_size (layout, &amp;amp;width, &amp;amp;height);
pango_font_description_free (fontdesc);
g_object_unref (layout);
</programlisting>
        <para>
          See also the
          <ulink url="https://developer.gnome.org/pango/stable/pango-Layout-Objects.html">Layout
          Objects</ulink> section of the
          <ulink url="https://developer.gnome.org/pango/stable/">Pango
          documentation</ulink>.
        </para>
      </listitem>
      <listitem>
        <para>
          Why are types not registered if I use their
          <literal>GTK_TYPE_BLAH</literal> macro?
        </para>
        <para>
          The <link linkend="GTK-TYPE-BLAH:CAPS"><literal>GTK_TYPE_BLAH</literal></link> macros are defined as calls to
          <link linkend="gtk-blah-get-type"><function>gtk_blah_get_type()</function></link>, and the <literal><link linkend="get-type"><function>_get_type()</function></link></literal>
          functions are declared as <link linkend="G-GNUC-CONST:CAPS"><literal>G_GNUC_CONST</literal></link> which allows the
          compiler to optimize the call away if it appears that the
          value is not being used.
        </para>
        <para>
          GLib provides the <link linkend="g-type-ensure"><function>g_type_ensure()</function></link> function to work around this
          problem.
        </para>
        <programlisting>
g_type_ensure (GTK_TYPE_BLAH);
</programlisting>
      </listitem>
      <listitem>
        <para>
          How do I create a transparent toplevel window?
        </para>
        <para>
          Any toplevel window can be transparent. It is just a matter of
          setting a transparent background in the CSS style for it.
        </para>
      </listitem>
    </orderedlist>
  </sect1>
  <sect1>
    <title>Which widget should I use…</title>
    <orderedlist numeration="arabic">
      <listitem override="16">
        <para>
          …for lists and trees?
        </para>
        <para>
          This question has different answers, depending on the size of
          the dataset and the required formatting flexibility.
        </para>
        <para>
          If you want to display a large amount of data in a uniform
          way, your best option is a <link linkend="GtkTreeView"><type>GtkTreeView</type></link> widget. See the
          <link linkend="TreeWidget">tree widget overview</link>. A list
          is just a tree with no branches, so the treeview widget is
          used for lists as well.
        </para>
        <para>
          If you want to display a small amount of items, but need
          flexible formatting and widgetry inside the list, then you
          probably want to use a <link linkend="GtkListBox"><type>GtkListBox</type></link>, which uses regular widgets
          for display.
        </para>
      </listitem>
      <listitem>
        <para>
          …for multi-line text display or editing?
        </para>
        <para>
          See the <link linkend="TextWidget">text widget overview</link>
          – you should use the <link linkend="GtkTextView"><type>GtkTextView</type></link> widget.
        </para>
        <para>
          If you only have a small amount of text, <link linkend="GtkLabel"><type>GtkLabel</type></link> may also be
          appropriate of course. It can be made selectable with
          <link linkend="gtk-label-set-selectable"><function>gtk_label_set_selectable()</function></link>. For a single-line text entry, see
          <link linkend="GtkEntry"><type>GtkEntry</type></link>.
        </para>
      </listitem>
      <listitem>
        <para>
          …to display an image or animation?
        </para>
        <para>
          GTK has two widgets that are dedicated to displaying images.
          <link linkend="GtkImage"><type>GtkImage</type></link>, for small, fixed-size icons and <link linkend="GtkPicture"><type>GtkPicture</type></link> for
          content images.
        </para>
        <para>
          Both can display images in just about any format GTK
          understands. You can also use <link linkend="GtkDrawingArea"><type>GtkDrawingArea</type></link> if you need to
          do something more complex, such as draw text or graphics over
          the top of the image.
        </para>
        <para>
          Both GtkImage and GtkPicture can display animations and videos
          as well. To show an webm file, load it with the GtkMediaFile
          API and then use it as a paintable:
        </para>
        <programlisting>
mediafile = gtk_media_file_new_for_filename (&quot;example.webm&quot;);
picture = gtk_picture_new_for_paintable (GDK_PAINTABLE (mediafile));
</programlisting>
      </listitem>
      <listitem>
        <para>
          …for presenting a set of mutually-exclusive choices, where
          Windows would use a combo box?
        </para>
        <para>
          With GTK, a <link linkend="GtkComboBox"><type>GtkComboBox</type></link> is the recommended widget to use for
          this use case. If you need an editable text entry, use the
          <link linkend="GtkComboBox--has-entry"><type>“has-entry”</type></link> property.
        </para>
      </listitem>
    </orderedlist>
  </sect1>
  <sect1>
    <title>Questions about GtkWidget</title>
    <orderedlist numeration="arabic">
      <listitem override="20">
        <para>
          How do I change the color of a widget?
        </para>
        <para>
          The background color of a widget is determined by the CSS
          style that applies to it. To change that, you can set style
          classes on the widget, and provide custom CSS to change the
          appearance. Such CSS can be loaded with
          <link linkend="gtk-css-provider-load-from-file"><function>gtk_css_provider_load_from_file()</function></link> and its variants. See
          <link linkend="gtk-style-context-add-provider"><function>gtk_style_context_add_provider()</function></link>.
        </para>
      </listitem>
      <listitem>
        <para>
          How do I change the font of a widget?
        </para>
        <para>
          If you want to make the text of a label larger, you can use
          <link linkend="gtk-label-set-markup"><function>gtk_label_set_markup()</function></link>:
        </para>
        <programlisting>
gtk_label_set_markup (label, &quot;&lt;big&gt;big tex&lt;/big&gt;&quot;);
</programlisting>
        <para>
          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"><function>g_markup_escape_text()</function></link> if
          you are constructing such strings on the fly.
        </para>
        <para>
          You can also change the font of a widget by putting
        </para>
        <programlisting>
.my-widget-class {
  font: Sans 30;
}
</programlisting>
        <para>
          in a CSS file, loading it with
          <link linkend="gtk-css-provider-load-from-file"><function>gtk_css_provider_load_from_file()</function></link>, and adding the provider
          with <link linkend="gtk-style-context-add-provider-for-display"><function>gtk_style_context_add_provider_for_display()</function></link>. To
          associate this style information with your widget, set a style
          class on its <link linkend="GtkStyleContext"><type>GtkStyleContext</type></link> using
          <link linkend="gtk-style-context-add-class"><function>gtk_style_context_add_class()</function></link>. The advantage of this approach
          is that users can then override the font you have chosen. See
          the <link linkend="GtkStyleContext"><type>GtkStyleContext</type></link> documentation for more discussion.
        </para>
      </listitem>
      <listitem>
        <para>
          How do I disable/ghost/desensitize a widget?
        </para>
        <para>
          In GTK a disabled widget is termed
          <emphasis>insensitive</emphasis>. See
          <link linkend="gtk-widget-set-sensitive"><function>gtk_widget_set_sensitive()</function></link>.
        </para>
      </listitem>
    </orderedlist>
  </sect1>
  <sect1>
    <title>GtkTextView questions</title>
    <orderedlist numeration="arabic">
      <listitem override="23">
        <para>
          How do I get the contents of the entire text widget as a
          string?
        </para>
        <para>
          See <link linkend="gtk-text-buffer-get-bounds"><function>gtk_text_buffer_get_bounds()</function></link> and
          <link linkend="gtk-text-buffer-get-text"><function>gtk_text_buffer_get_text()</function></link> or <link linkend="gtk-text-iter-get-text"><function>gtk_text_iter_get_text()</function></link>.
        </para>
        <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>
      </listitem>
      <listitem>
        <para>
          How do I make a text widget display its complete contents in a
          specific font?
        </para>
        <para>
          If you use <link linkend="gtk-text-buffer-insert-with-tags"><function>gtk_text_buffer_insert_with_tags()</function></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>
      </listitem>
      <listitem>
        <para>
          How do I make a text view scroll to the end of the buffer
          automatically ?
        </para>
        <para>
          A good way to keep a text buffer scrolled to the end is to
          place a <link linkend="GtkTextMark">mark</link> at the end of
          the buffer, and give it right gravity. The gravity has the
          effect that text inserted at the mark gets inserted
          <emphasis>before</emphasis>, keeping the mark at the end.
        </para>
        <para>
          To ensure that the end of the buffer remains visible, use
          <link linkend="gtk-text-view-scroll-to-mark"><function>gtk_text_view_scroll_to_mark()</function></link> to scroll to the mark after
          inserting new text.
        </para>
        <para>
          The gtk-demo application contains an example of this
          technique.
        </para>
      </listitem>
    </orderedlist>
  </sect1>
  <sect1>
    <title>GtkTreeView questions</title>
    <orderedlist numeration="arabic">
      <listitem override="26">
        <para>
          How do I associate some data with a row in the tree?
        </para>
        <para>
          Remember that the <link linkend="GtkTreeModel"><type>GtkTreeModel</type></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"><function>gtk_tree_model_get()</function></link>. See the <link linkend="TreeWidget">tree
          widget overview</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          How do I put an image and some text in the same column?
        </para>
        <para>
          You can pack more than one <link linkend="GtkCellRenderer"><type>GtkCellRenderer</type></link> into a single
          <link linkend="GtkTreeViewColumn"><type>GtkTreeViewColumn</type></link> using <link linkend="gtk-tree-view-column-pack-start"><function>gtk_tree_view_column_pack_start()</function></link> or
          <link linkend="gtk-tree-view-column-pack-end"><function>gtk_tree_view_column_pack_end()</function></link>. So pack both a
          <link linkend="GtkCellRendererPixbuf"><type>GtkCellRendererPixbuf</type></link> and a <link linkend="GtkCellRendererText"><type>GtkCellRendererText</type></link> into the
          column.
        </para>
      </listitem>
      <listitem>
        <para>
          I can set data easily on my <link linkend="GtkTreeStore"><type>GtkTreeStore</type></link> or <link linkend="GtkListStore"><type>GtkListStore</type></link>
          models using <link linkend="gtk-list-store-set"><function>gtk_list_store_set()</function></link> and <link linkend="gtk-tree-store-set"><function>gtk_tree_store_set()</function></link>,
          but can’t read it back?
        </para>
        <para>
          Both the <link linkend="GtkTreeStore"><type>GtkTreeStore</type></link> and the <link linkend="GtkListStore"><type>GtkListStore</type></link> implement the
          <link linkend="GtkTreeModel"><type>GtkTreeModel</type></link> interface. As a consequence, you 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"><function>gtk_tree_model_get()</function></link>.
        </para>
      </listitem>
      <listitem>
        <para>
          How do I change the way that numbers are formatted by
          <link linkend="GtkTreeView"><type>GtkTreeView</type></link>?
        </para>
        <para>
          Use <link linkend="gtk-tree-view-insert-column-with-data-func"><function>gtk_tree_view_insert_column_with_data_func()</function></link> or
          <link linkend="gtk-tree-view-column-set-cell-data-func"><function>gtk_tree_view_column_set_cell_data_func()</function></link> and do the
          conversion from number to string yourself (with, say,
          <link linkend="g-strdup-printf"><function>g_strdup_printf()</function></link>).
        </para>
        <para>
          The following example demonstrates this:
        </para>
        <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;
  double d;
  char *text;

  /* Get the double value from the model. */
  gtk_tree_model_get (tree_model, iter, (int)data, &amp;d, -1);
  /* Now we can format the value ourselves. */
  text = g_strdup_printf (&quot;%.2f&quot;, d);
  g_object_set (cell, &quot;text&quot;, 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 = <link linkend="gtk-cell-renderer-text-new"><function>gtk_cell_renderer_text_new()</function></link>;

  /* Create a new column that has a title (&quot;Example column&quot;),
   * uses the above created renderer that will render the double
   * value into text from the associated model's rows.
   */
  column = <link linkend="gtk-tree-view-column-new"><function>gtk_tree_view_column_new()</function></link>;
  gtk_tree_view_column_set_title  (column, &quot;Example column&quot;);
  renderer = <link linkend="gtk-cell-renderer-text-new"><function>gtk_cell_renderer_text_new()</function></link>;
  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>
      </listitem>
      <listitem>
        <para>
          How do I hide the expander arrows in my tree view?
        </para>
        <para>
          Set the expander-column property of the tree view to a hidden
          column. See <link linkend="gtk-tree-view-set-expander-column"><function>gtk_tree_view_set_expander_column()</function></link> and
          <link linkend="gtk-tree-view-column-set-visible"><function>gtk_tree_view_column_set_visible()</function></link>.
        </para>
      </listitem>
    </orderedlist>
  </sect1>
  <sect1>
    <title>Using cairo with GTK</title>
    <orderedlist numeration="arabic">
      <listitem override="31">
        <para>
          How do I use cairo to draw in GTK applications?
        </para>
        <para>
          Use <link linkend="gtk-snapshot-append-cairo"><function>gtk_snapshot_append_cairo()</function></link> in your
          <link linkend="GtkWidgetClass.snapshot"><function>GtkWidgetClass.snapshot()</function></link> vfunc to obtain a cairo context and
          draw with that.
        </para>
      </listitem>
      <listitem>
        <para>
          Can I improve the performance of my application by using
          another backend of cairo (such as GL)?
        </para>
        <para>
          No. Most drawing in GTK is not done via cairo anymore (but
          instead by the GL or Vulkan renderers of GSK).
        </para>
        <para>
          If you use cairo for drawing your own widgets,
          <link linkend="gtk-snapshot-append-cairo"><function>gtk_snapshot_append_cairo()</function></link> will choose the most appropriate
          surface type for you.
        </para>
        <para>
          If you are interested in using GL for your own drawing, see
          <link linkend="GtkGLArea"><type>GtkGLArea</type></link>.
        </para>
      </listitem>
      <listitem>
        <para>
          Can I use cairo to draw on a <link linkend="GdkPixbuf"><type>GdkPixbuf</type></link>?
        </para>
        <para>
          No. The cairo image surface does not support the pixel format
          used by GdkPixbuf.
        </para>
        <para>
          If you need to get cairo drawing into a format that can be
          displayed efficiently by GTK, you may want to use an image
          surface and <link linkend="gdk-memory-texture-new"><function>gdk_memory_texture_new()</function></link>.
        </para>
      </listitem>
    </orderedlist>
  </sect1>
</chapter>
