|
Server : Apache/2.2.17 (Unix) mod_ssl/2.2.17 OpenSSL/0.9.8e-fips-rhel5 DAV/2 PHP/5.2.17 System : Linux localhost 2.6.18-419.el5 #1 SMP Fri Feb 24 22:47:42 UTC 2017 x86_64 User : nobody ( 99) PHP Version : 5.2.17 Disable Function : NONE Directory : /usr/share/gtk-doc/html/gtk/ |
Upload File : |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Common Questions</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
<link rel="start" href="index.html" title="GTK+ Reference Manual">
<link rel="up" href="gtk.html" title="Part I. GTK+ Overview">
<link rel="prev" href="gtk-resources.html" title="Mailing lists and bug reports">
<link rel="next" href="gtkbase.html" title="Part II. GTK+ Core Reference">
<meta name="generator" content="GTK-Doc V1.6 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="part" href="gtk.html" title="Part I. GTK+ Overview">
<link rel="part" href="gtkbase.html" title="Part II. GTK+ Core Reference">
<link rel="part" href="gtkobjects.html" title="Part III. GTK+ Widgets and Objects">
<link rel="chapter" href="ch01.html" title="Object Hierarchy">
<link rel="chapter" href="ch02.html" title="Widget Gallery">
<link rel="chapter" href="WindowWidgets.html" title="Windows">
<link rel="chapter" href="DisplayWidgets.html" title="Display Widgets">
<link rel="chapter" href="ButtonWidgets.html" title="Buttons and Toggles">
<link rel="chapter" href="NumericEntry.html" title="Numeric/Text Data Entry">
<link rel="chapter" href="TextWidgetObjects.html" title="Multiline Text Editor">
<link rel="chapter" href="TreeWidgetObjects.html" title="Tree, List and Icon Grid Widgets">
<link rel="chapter" href="MenusAndCombos.html" title="Menus, Combo Box, Toolbar">
<link rel="chapter" href="Actions.html" title="Action-based menus and toolbars">
<link rel="chapter" href="SelectorWidgets.html" title="Selectors (File/Font/Color/Input Devices)">
<link rel="chapter" href="LayoutContainers.html" title="Layout Containers">
<link rel="chapter" href="Ornaments.html" title="Ornaments">
<link rel="chapter" href="ScrollingWidgets.html" title="Scrolling">
<link rel="chapter" href="Printing.html" title="Printing">
<link rel="chapter" href="MiscObjects.html" title="Miscellaneous">
<link rel="chapter" href="AbstractObjects.html" title="Abstract Base Classes">
<link rel="chapter" href="PlugSocket.html" title="Cross-process Embedding">
<link rel="chapter" href="SpecialObjects.html" title="Special-purpose features">
<link rel="chapter" href="RecentDocuments.html" title="Recently Used Documents">
<link rel="chapter" href="DeprecatedObjects.html" title="Deprecated">
<link rel="part" href="migrating.html" title="Part IV. Migrating from Previous Versions of GTK+">
<link rel="chapter" href="gtk-migrating-checklist.html" title="Migration Checklist">
<link rel="chapter" href="gtk-migrating-GtkFileChooser.html" title="Migrating from GtkFileSelection to GtkFileChooser">
<link rel="chapter" href="gtk-migrating-GtkAction.html" title="Migrating from old menu and toolbar systems to GtkAction">
<link rel="chapter" href="gtk-migrating-GtkComboBox.html" title="Migrating from GtkOptionMenu and GtkCombo to GtkComboBox and
GtkComboBoxEntry">
<link rel="chapter" href="gtk-migrating-GtkIconView.html" title="Migrating from GnomeIconList to GtkIconView">
<link rel="chapter" href="gtk-migrating-GtkAboutDialog.html" title="Migrating from GnomeAbout to GtkAboutDialog">
<link rel="chapter" href="gtk-migrating-GtkColorButton.html" title="Migrating from GnomeColorPicker to GtkColorButton">
<link rel="chapter" href="gtk-migrating-GtkAssistant.html" title="Migrating from GnomeDruid to GtkAssistant">
<link rel="chapter" href="gtk-migrating-GtkRecentChooser.html" title="Migrating from EggRecent to GtkRecentChooser">
<link rel="chapter" href="gtk-migrating-GtkLinkButton.html" title="Migrating from GnomeHRef to GtkLinkButton">
<link rel="part" href="pt05.html" title="Part V. GTK+ Tools">
<link rel="glossary" href="glossary.html" title="Glossary">
<link rel="index" href="ix01.html" title="Index">
<link rel="index" href="ix02.html" title="Index of deprecated symbols">
<link rel="index" href="ix03.html" title="Index of new symbols in 2.2">
<link rel="index" href="ix04.html" title="Index of new symbols in 2.4">
<link rel="index" href="ix05.html" title="Index of new symbols in 2.6">
<link rel="index" href="ix06.html" title="Index of new symbols in 2.8">
<link rel="index" href="ix07.html" title="Index of new symbols in 2.10">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="gtk-resources.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="gtk.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GTK+ Reference Manual</th>
<td><a accesskey="n" href="gtkbase.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry" lang="en">
<a name="gtk-question-index"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle">Common Questions</span></h2>
<p>Common Questions —
Find answers to common questions in the GTK+ manual
</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsect1" lang="en">
<a name="id2559082"></a><h2>Questions and Answers</h2>
<p>
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.
</p>
<div class="qandaset"><table border="0" summary="Q and A Set">
<col align="left" width="1%">
<tbody>
<tr class="qandadiv"><td align="left" valign="top" colspan="2">
<a name="id2559833"></a><h5 class="title">
<a name="id2559833"></a>1. General</h5>
</td></tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2559837"></a><a name="id2559839"></a><b>1.1.</b>
</td>
<td align="left" valign="top"><p>
How do I get started with GTK+?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p>
The GTK+ <a href="http://www.gtk.org" target="_top">website</a> offers a
<a href="http://www.gtk.org/tutorial" target="_top">tutorial</a> and a
<a href="http://www.gtk.org/faq" target="_top">FAQ</a>. More documentation ranging
from whitepapers to online books can be found at the
<a href="http://developer.gnome.org/doc" target="_top">GNOME developer's site</a>.
After studying these materials you should be well prepared to come back to
this reference manual for details.
</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2559877"></a><a name="id2559879"></a><b>1.2.</b>
</td>
<td align="left" valign="top"><p>
Where can I get help with GTK+, submit a bug report, or make a feature
request?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p>
See the <a href="gtk-resources.html" title="Mailing lists and bug reports">documentation on this topic</a>.
</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2559900"></a><a name="id2559902"></a><b>1.3.</b>
</td>
<td align="left" valign="top"><p>How do I port from one GTK+
version to another?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
See the <a href="gtk-changes-2-0.html" title="Changes from 1.2 to 2.0">list of incompatible changes
from 1.2 to 2.0</a>. Also, the <a href="http://developer.gnome.org/dotplan/porting/" target="_top">GNOME 2.0 porting
guide</a> on <a href="http://developer.gnome.org" target="_top">http://developer.gnome.org</a>
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.
</p>
<p>
If you have a question not covered in the manual, feel free to
ask on the mailing lists and please <a href="http://bugzilla.gnome.org" target="_top">file a bug report</a> against the
documentation.
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2559951"></a><a name="id2559954"></a><b>1.4.</b>
</td>
<td align="left" valign="top"><p>
How does memory management work in GTK+? Should I free data returned
from functions?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
See the documentation for <a
href="../gobject/gobject-The-Base-Object-Type.html#GObject"
><span class="type">GObject</span></a> and <a href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a>. For <a
href="../gobject/gobject-The-Base-Object-Type.html#GObject"
><span class="type">GObject</span></a> note specifically
<a
href="../gobject/gobject-The-Base-Object-Type.html#g-object-ref"
><code class="function">g_object_ref()</code></a> and <a
href="../gobject/gobject-The-Base-Object-Type.html#g-object-unref"
><code class="function">g_object_unref()</code></a>. <a href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> is a subclass of <a
href="../gobject/gobject-The-Base-Object-Type.html#GObject"
><span class="type">GObject</span></a> so the
same points apply, except that it has a "floating" state (explained in its
documentation).
</p>
<p>
For strings returned from functions, they will be declared "const" (using
<a
href="../glib/glib-Standard-Macros.html#G-CONST-RETURN:CAPS"
><span class="type">G_CONST_RETURN</span></a>) if they should not be freed. Non-const strings should be freed
with <a
href="../glib/glib-Memory-Allocation.html#g-free"
><code class="function">g_free()</code></a>. Arrays follow the same rule. (If you find an exception to the rules,
please report a bug to <a href="http://bugzilla.gnome.org" target="_top">http://bugzilla.gnome.org</a>.)
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2560068"></a><a name="id2560070"></a><b>1.5.</b>
</td>
<td align="left" valign="top"><p>
Why does my program leak memory, if I destroy a widget immediately
after creating it ?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
If <span class="structname">GtkFoo</span> isn't a toplevel window, then
</p>
<div class="informalexample"><pre class="programlisting">
foo = gtk_foo_new ();
gtk_widget_destroy (foo);
</pre></div>
<p>
is a memory leak, because no one assumed the initial floating
reference. If you are using a widget and you aren't immediately
packing it into a container, then you probably want standard
reference counting, not floating reference counting.
</p>
<p>
To to get this, you must acquire a reference to the widget and drop the floating
reference (“<span class="quote">ref and sink</span>” in GTK+ parlance) after creating it:
</p>
<div class="informalexample"><pre class="programlisting">
foo = gtk_foo_new ();
g_object_ref (foo);
gtk_object_sink (GTK_OBJECT (foo));
</pre></div>
<p>
When you want to get rid of the widget, you must call <a href="GtkWidget.html#gtk-widget-destroy"><code class="function">gtk_widget_destroy()</code></a>
to break any external connections to the widget before dropping your
reference:
</p>
<div class="informalexample"><pre class="programlisting">
gtk_widget_destroy (foo);
g_object_unref (foo);
</pre></div>
<p>
When you immediately add a widget to a container, it takes care of
assuming the initial floating reference and you don't have to worry
about reference counting at all ... just call <a href="GtkWidget.html#gtk-widget-destroy"><code class="function">gtk_widget_destroy()</code></a>
to get rid of the widget.
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2560161"></a><a name="id2560163"></a><b>1.6.</b>
</td>
<td align="left" valign="top"><p>
How do I use GTK+ with threads?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p>
This is covered in the
<a
href="../gdk/gdk-Threads.html"
>GDK threads documentation</a>.
See also the <a
href="../glib/glib-Threads.html"
>GThread</a> documentation for portable
threading primitives.
</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2560193"></a><a name="id2560195"></a><b>1.7.</b>
</td>
<td align="left" valign="top"><p>
How do I internationalize a GTK+ program?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
Most people use <a href="http://www.gnu.org/software/gettext/" target="_top">GNU
gettext</a>, already required in order to install GLib. On a UNIX
or Linux system with gettext installed, type <code class="literal">info
gettext</code> to read the documentation.
</p>
<p>
The short checklist on how to use gettext is: call <a
href="../libbonobo/libbonobo-bonobo-i18n.html#bindtextdomain"
><code class="function">bindtextdomain()</code></a> so gettext
can find the files containing your translations, call <a
href="../libbonobo/libbonobo-bonobo-i18n.html#textdomain"
><code class="function">textdomain()</code></a> to set the
default translation domain, then call <a
href="../libbonobo/libbonobo-bonobo-i18n.html#gettext"
><code class="function">gettext()</code></a> to look up each string to be
translated in the default domain. Conventionally, people define macros as
follows for convenience:
</p>
<div class="informalexample"><pre class="programlisting">
<span class="type">define</span> _(x) gettext (x)
<span class="type">define</span> N_(x) x
</pre></div>
<p>
You use <a
href="../libbonobo/libbonobo-bonobo-i18n.html#N-:CAPS"
><code class="function">N_()</code></a> (N stands for no-op) to mark a string for translation in a context
where a function call to <a
href="../libbonobo/libbonobo-bonobo-i18n.html#gettext"
><code class="function">gettext()</code></a> is not allowed, such as in an array initializer.
You eventually have to call <a
href="../libbonobo/libbonobo-bonobo-i18n.html#gettext"
><code class="function">gettext()</code></a> on the string to actually fetch the
translation. <a
href="../libbonobo/libbonobo-bonobo-i18n.html#gettext-macro"
><code class="function">_()</code></a> both marks the string for translation and actually translates it.
</p>
<p>
Nowadays, GLib provides the common shorthand macros in the header file
<code class="filename">gi18n.h</code>, so you don't have to define them yourself, just
include that header.
</p>
<p>
Code using these macros ends up looking like this:
</p>
<div class="informalexample"><pre class="programlisting">
<span class="type">include</span> <gi18n.h>
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));
...
</pre></div>
<p>
</p>
<p>
Libraries using gettext should use <a
href="../libbonobo/libbonobo-bonobo-i18n.html#dgettext"
><code class="function">dgettext()</code></a> instead of <a
href="../libbonobo/libbonobo-bonobo-i18n.html#gettext"
><code class="function">gettext()</code></a>, which allows
them to specify the translation domain each time they ask for a translation. Libraries
should also avoid calling <a
href="../libbonobo/libbonobo-bonobo-i18n.html#textdomain"
><code class="function">textdomain()</code></a>, since they'll be specifying the domain instead
of using the default.For <a
href="../libbonobo/libbonobo-bonobo-i18n.html#dgettext"
><code class="function">dgettext()</code></a> the <a
href="../libbonobo/libbonobo-bonobo-i18n.html#gettext-macro"
><code class="function">_()</code></a> macro can be defined as:
</p>
<div class="informalexample"><pre class="programlisting">
<span class="type">define</span> _(x) dgettext ("MyDomain", x)
</pre></div>
<p>
</p>
<p>
Again, GLib comes with the <code class="filename">gi18n-lib.h</code>, saving you the trouble
of defining the macros by hand. The macros in that header expect the translation
domain to be specified by the <code class="literal">GETTEXT_PACKAGE</code> macro.
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2560487"></a><a name="id2560489"></a><b>1.8.</b>
</td>
<td align="left" valign="top"><p>
How do I use non-ASCII characters in GTK+ programs ?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
GTK+ uses <a href="http://www.unicode.org" target="_top">Unicode</a> (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:
</p>
<div class="itemizedlist"><ul type="disc">
<li><p>
ASCII characters are encoded by their familiar ASCII codepoints.
</p></li>
<li><p>
ASCII characters never appear as part of any other character.
</p></li>
<li><p>
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.
</p></li>
</ul></div>
<p>
More information about Unicode and UTF-8 can be found in the
<a href="http://www.cl.cam.ac.uk/~mgk25/unicode.html" target="_top">UTF-8 and Unicode FAQ for Unix/Linux</a>.
GLib provides functions for converting strings between UTF-8 and other
encodings, see <a
href="../glib/glib-Character-Set-Conversion.html#g-locale-to-utf8"
><code class="function">g_locale_to_utf8()</code></a> and <a
href="../glib/glib-Character-Set-Conversion.html#g-convert"
><code class="function">g_convert()</code></a>.
</p>
<p>
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 <code class="literal">stdout</code>:
</p>
<div class="informalexample"><pre class="programlisting">
gchar *text, *utf8_text;
gsize length;
GError *error = NULL;
if (g_file_get_contents (filename, &text, &length, NULL))
{
utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1",
NULL, NULL, &error);
if (error != NULL)
{
fprintf ("Couldn't convert file %s to UTF-8\n", filename);
g_error_free (error);
}
else
g_print (utf8_text);
}
else
fprintf (stderr, "Unable to read file %s\n", filename);
</pre></div>
<p>
</p>
<p>
For string literals in the source code, there are several alternatives for
handling non-ASCII content:
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term">direct UTF-8</span></td>
<td><p>
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.
</p></td>
</tr>
<tr>
<td>
<span class="term">escaped UTF-8</span></td>
<td><p>
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
<code class="literal">\212</code> or <code class="literal">\xa8</code> 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;
<code class="literal">"\xa8abcd"</code> is a string of length 1 !
</p></td>
</tr>
<tr>
<td>
<span class="term">runtime conversion</span></td>
<td><p>
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 <a
href="../glib/glib-Character-Set-Conversion.html#g-convert"
><code class="function">g_convert()</code></a> 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.
</p></td>
</tr>
</tbody>
</table></div>
<p>
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:
</p>
<div class="informalexample"><pre class="programlisting">
g_print ("direct UTF-8: ©");
g_print ("escaped UTF-8: \302\251");
text = g_convert ("runtime conversion: ©", -1, "ISO-8859-1", "UTF-8", NULL, NULL, NULL);
g_print(text);
g_free (text);
</pre></div>
<p>
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2560692"></a><a name="id2560694"></a><b>1.9.</b>
</td>
<td align="left" valign="top"><p>
How do I use GTK+ with C++?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
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 <a href="http://gtkmm.sourceforge.net/" target="_top">gtkmm</a>
which provides a C++-native API.
</p>
<p>
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.
</p>
<p>
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:
</p>
<div class="informalexample"><pre class="programlisting">
gdk_window_set_events (gdk_window,
GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
</pre></div>
<p>
while in C++ you must write:
</p>
<div class="informalexample"><pre class="programlisting">
gdk_window_set_events (gdk_window,
(GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
</pre></div>
<p>
There are very few functions that require this cast, however.
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2560756"></a><a name="id2560759"></a><b>1.10.</b>
</td>
<td align="left" valign="top"><p>
How do I use GTK+ with other non-C languages?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p>
See the <a href="http://www.gtk.org/bindings.html" target="_top">list of language
bindings</a> on <a href="http://www.gtk.org" target="_top">http://www.gtk.org</a>.
</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2560784"></a><a name="id2560786"></a><b>1.11.</b>
</td>
<td align="left" valign="top"><p>
How do I load an image or animation from a file?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
To load an image file straight into a display widget, use <a href="GtkImage.html#gtk-image-new-from-file"><code class="function">gtk_image_new_from_file()</code></a>
<sup>[<a name="id2560808" href="#ftn.id2560808">1</a>]</sup>.
To load an image for another purpose, use <a
href="../gdk-pixbuf/gdk-pixbuf-file-loading.html#gdk-pixbuf-new-from-file"
><code class="function">gdk_pixbuf_new_from_file()</code></a>. To load an
animation, use <a
href="../gdk-pixbuf/gdk-pixbuf-animation.html#gdk-pixbuf-animation-new-from-file"
><code class="function">gdk_pixbuf_animation_new_from_file()</code></a>.
<a
href="../gdk-pixbuf/gdk-pixbuf-animation.html#gdk-pixbuf-animation-new-from-file"
><code class="function">gdk_pixbuf_animation_new_from_file()</code></a> can also load non-animated images, so use it
in combination with <a
href="../gdk-pixbuf/gdk-pixbuf-animation.html#gdk-pixbuf-animation-is-static-image"
><code class="function">gdk_pixbuf_animation_is_static_image()</code></a> to load a file of unknown
type.
</p>
<p>
To load an image or animation file asynchronously (without blocking), use
<a
href="../gdk-pixbuf/GdkPixbufLoader.html"
><span class="type">GdkPixbufLoader</span></a>.
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2560915"></a><a name="id2560917"></a><b>1.12.</b>
</td>
<td align="left" valign="top"><p>
How do I draw text ?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
To draw a piece of text, use a Pango layout and <a
href="../gdk/gdk-Drawing-Primitives.html#gdk-draw-layout"
><code class="function">gdk_draw_layout()</code></a>,
using code like the following:
</p>
<div class="informalexample"><pre class="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);
</pre></div>
<p>
Do not use the deprecated <a
href="../gdk/gdk-Fonts.html#GdkFont"
><span class="type">GdkFont</span></a> and <a
href="../gdk/gdk-Drawing-Primitives.html#gdk-draw-text"
><code class="function">gdk_draw_text()</code></a>.
</p>
<p>
See also the "Text Handling in GTK 2" section of
<a href="http://developer.gnome.org/dotplan/porting/" target="_top">Porting applications
to the GNOME 2.0 platform</a>.
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2560988"></a><a name="id2560990"></a><b>1.13.</b>
</td>
<td align="left" valign="top"><p>
How do I measure the size of a piece of text ?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
To obtain the size of a piece of text, use a Pango layout and
<a
href="../pango/pango-Layout-Objects.html#pango-layout-get-pixel-size"
><code class="function">pango_layout_get_pixel_size()</code></a>, using code like the following:
</p>
<div class="informalexample"><pre class="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, &width, &height);
pango_font_description_free (fontdesc);
g_object_unref (layout);
</pre></div>
<p>
Do not use the deprecated function <a
href="../gdk/gdk-Fonts.html#gdk-text-width"
><code class="function">gdk_text_width()</code></a>.
</p>
<p>
See also the "Text Handling in GTK 2" section of
<a href="http://developer.gnome.org/dotplan/porting/" target="_top">Porting applications
to the GNOME 2.0 platform</a>.
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2561059"></a><a name="id2561062"></a><b>1.14.</b>
</td>
<td align="left" valign="top"><p>
Why are types not registered if I use their <code class="literal">GTK_TYPE_BLAH</code> macro ?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
The <code class="literal">GTK_TYPE_BLAH</code> macros are defined as calls to
<code class="literal"><code class="function">gtk_blah_get_type()</code></code>, and the <code class="literal"><code class="function">_get_type()</code></code> functions
are declared as <code class="literal">G_GNUC_CONST</code> which allows the compiler to optimize
the call away if it appears that the value is not being used.
</p>
<p>
A common workaround for this problem is to store the result in a volatile variable,
which keeps the compiler from optimizing the call away.
</p>
<div class="informalexample"><pre class="programlisting">
volatile GType dummy = GTK_TYPE_BLAH;
</pre></div>
<p>
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2561140"></a><a name="id2561142"></a><b>1.15.</b>
</td>
<td align="left" valign="top"><p>
How do I create a transparent toplevel window ?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
To make a window transparent, it needs to use a visual which supports that.
This is done by getting the RGBA colormap of the screen with
<a
href="../gdk/GdkScreen.html#gdk-screen-get-rgba-colormap"
><code class="function">gdk_screen_get_rgba_colormap()</code></a> and setting it on the window. Note that
<a
href="../gdk/GdkScreen.html#gdk-screen-get-rgba-colormap"
><code class="function">gdk_screen_get_rgba_colormap()</code></a> will return <a
href="../glib/glib-Standard-Macros.html#NULL:CAPS"
><code class="literal">NULL</code></a> if transparent windows
are not supported on the screen; also note that this may change from
screen to screen, so it needs to be repeated whenever the window is moved
to a different screen.
</p>
<div class="informalexample"><pre class="programlisting">
GdkColormap *colormap;
colormap = gdk_screen_get_rgba_colormap (screen);
if (!colormap)
colormap = gtk_screen_get_rgb_colormap (screen);
gtk_widget_set_colormap (widget, colormap);
</pre></div>
<p>
One possibility to fill the alpha channel on the window is to use
<a
href="../gdk/gdk-GdkRGB.html#gdk-draw-rgb-32-image"
><code class="function">gdk_draw_rgb_32_image()</code></a>.
</p>
<p>
Note that the presence of an RGBA visual is no guarantee that the
window will actually appear transparent on screen. On X11, this
requires a compositing manager to be running. See
<a href="GtkWidget.html#gtk-widget-is-composited"><code class="function">gtk_widget_is_composited()</code></a> for a way to find out if the alpha
channel will be respected.
</p>
</td>
</tr>
<tr class="qandadiv"><td align="left" valign="top" colspan="2">
<a name="id2561241"></a><h5 class="title">
<a name="id2561241"></a>2. Which widget should I use...</h5>
</td></tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2561246"></a><a name="id2561248"></a><b>2.1.</b>
</td>
<td align="left" valign="top"><p>
...for lists and trees?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p>
See <a href="TreeWidget.html" title="Tree and List Widget Overview">tree widget overview</a> — you
should use the <a href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</span></a> 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 <a href="GtkTree.html" title="GtkTree"><span class="type">GtkTree</span></a> or <a href="GtkCList.html" title="GtkCList"><span class="type">GtkCList</span></a>/<a href="GtkCTree.html" title="GtkCTree"><span class="type">GtkCTree</span></a> in newly-written code, they are
less flexible and result in an inferior user interface.
</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2561306"></a><a name="id2561308"></a><b>2.2.</b>
</td>
<td align="left" valign="top"><p>
...for multi-line text display or editing?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
See <a href="TextWidget.html" title="Text Widget Overview">text widget overview</a> — you
should use the <a href="GtkTextView.html" title="GtkTextView"><span class="type">GtkTextView</span></a> widget. Do not use the deprecated widget <a href="GtkText.html" title="GtkText"><span class="type">GtkText</span></a>
in newly-written code, it has a number of problems that are best avoided.
</p>
<p>
If you only have a small amount of text, <a href="GtkLabel.html" title="GtkLabel"><span class="type">GtkLabel</span></a> may also be appropriate of course.
It can be made selectable with <a href="GtkLabel.html#gtk-label-set-selectable"><code class="function">gtk_label_set_selectable()</code></a>. For a single-line text
entry, see <a href="GtkEntry.html" title="GtkEntry"><span class="type">GtkEntry</span></a>.
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2561382"></a><a name="id2561384"></a><b>2.3.</b>
</td>
<td align="left" valign="top"><p>
...to display an image or animation?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p>
<a href="GtkImage.html" title="GtkImage"><span class="type">GtkImage</span></a> can display images in just about any format GTK+ understands. You can also
use <a href="GtkDrawingArea.html" title="GtkDrawingArea"><span class="type">GtkDrawingArea</span></a> if you need to do something more complex, such as draw text or
graphics over the top of the image.
</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2561416"></a><a name="id2561418"></a><b>2.4.</b>
</td>
<td align="left" valign="top"><p>
...for presenting a set of mutually-exclusive choices, where Windows
would use a combo box?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p>
With GTK+, a <a href="GtkComboBox.html" title="GtkComboBox"><span class="type">GtkComboBox</span></a> is the recommended widget to use for this use case.
This widget looks like either a combo box or the current option menu, depending
on the current theme. If you need an editable text entry, use <a href="GtkComboBoxEntry.html" title="GtkComboBoxEntry"><span class="type">GtkComboBoxEntry</span></a>.
</p></td>
</tr>
<tr class="qandadiv"><td align="left" valign="top" colspan="2">
<a name="id2561454"></a><h5 class="title">
<a name="id2561454"></a>3. <a href="GtkWidget.html" title="GtkWidget"><span class="type">GtkWidget</span></a>
</h5>
</td></tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2561464"></a><a name="id2561467"></a><b>3.1.</b>
</td>
<td align="left" valign="top"><p>
How do I change the color of a widget?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
See <a href="GtkWidget.html#gtk-widget-modify-fg"><code class="function">gtk_widget_modify_fg()</code></a>, <a href="GtkWidget.html#gtk-widget-modify-bg"><code class="function">gtk_widget_modify_bg()</code></a>, <a href="GtkWidget.html#gtk-widget-modify-base"><code class="function">gtk_widget_modify_base()</code></a>,
and <a href="GtkWidget.html#gtk-widget-modify-text"><code class="function">gtk_widget_modify_text()</code></a>. See <a href="gtk-Resource-Files.html" title="Resource Files">GTK+
resource files</a> for more discussion. You can also change widget color by
installing a resource file and parsing it with <a href="gtk-Resource-Files.html#gtk-rc-add-default-file"><code class="function">gtk_rc_add_default_file()</code></a>.
The advantage of a resource file is that users can then override the
color you've chosen.
</p>
<p>To change the background color for widgets such as <a href="GtkLabel.html" title="GtkLabel"><span class="type">GtkLabel</span></a> that have no
background, place them in a <a href="GtkEventBox.html" title="GtkEventBox"><span class="type">GtkEventBox</span></a> and set the background of the event box.
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2561571"></a><a name="id2561573"></a><b>3.2.</b>
</td>
<td align="left" valign="top"><p>
How do I change the font of a widget?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
This has several possible answers, depending on what exactly you want to achieve.
One option is <a href="GtkWidget.html#gtk-widget-modify-font"><code class="function">gtk_widget_modify_font()</code></a>. Note that this function can be used to
change only the font size, as in the following example:
</p>
<pre class="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);
</pre>
<p>
</p>
<p>
If you want to make the text of a label larger, you can use <a href="GtkLabel.html#gtk-label-set-markup"><code class="function">gtk_label_set_markup()</code></a>:
</p>
<pre class="programlisting">
gtk_label_set_markup (label, "<big>big text</big>");
</pre>
<p>
This is preferred for many apps because it's a relative size to the
user's chosen font size. See <a
href="../glib/glib-Simple-XML-Subset-Parser.html#g-markup-escape-text"
><code class="function">g_markup_escape_text()</code></a> if you are constructing such
strings on the fly.
</p>
<p>
You can also change the font of a widget by putting
</p>
<pre class="programlisting">
gtk-font-name = "Sans 30"
</pre>
<p>
in a resource file and parsing it with <a href="gtk-Resource-Files.html#gtk-rc-add-default-file"><code class="function">gtk_rc_add_default_file()</code></a>. The advantage of
a resource file is that users can then override the font you've chosen. See
<a href="gtk-Resource-Files.html" title="Resource Files">GTK+ resource files</a> for more
discussion.
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2561680"></a><a name="id2561683"></a><b>3.3.</b>
</td>
<td align="left" valign="top"><p>
How do I disable/ghost/desensitize a widget?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p> In GTK+ a disabled widget is termed "insensitive." See
<a href="GtkWidget.html#gtk-widget-set-sensitive"><code class="function">gtk_widget_set_sensitive()</code></a>.
</p></td>
</tr>
<tr class="qandadiv"><td align="left" valign="top" colspan="2">
<a name="id2561707"></a><h5 class="title">
<a name="id2561707"></a>4. <a href="GtkTextView.html" title="GtkTextView"><span class="type">GtkTextView</span></a>
</h5>
</td></tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2561717"></a><a name="id2561719"></a><b>4.1.</b>
</td>
<td align="left" valign="top"><p>
How do I get the contents of the entire text widget as a string?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
See <a href="GtkTextBuffer.html#gtk-text-buffer-get-bounds"><code class="function">gtk_text_buffer_get_bounds()</code></a> and <a href="GtkTextBuffer.html#gtk-text-buffer-get-text"><code class="function">gtk_text_buffer_get_text()</code></a>
or <a href="gtk-GtkTextIter.html#gtk-text-iter-get-text"><code class="function">gtk_text_iter_get_text()</code></a>.
</p>
<p>
</p>
<div class="informalexample"><pre class="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, &start, &end);
text = gtk_text_iter_get_text (&start, &end);
/* use text */
g_free (text);
</pre></div>
<p>
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2561782"></a><a name="id2561784"></a><b>4.2.</b>
</td>
<td align="left" valign="top"><p>
How do I make a text widget display its complete contents in a specific font?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
If you use <a href="GtkTextBuffer.html#gtk-text-buffer-insert-with-tags"><code class="function">gtk_text_buffer_insert_with_tags()</code></a> 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.
</p>
<p>
To ensure that all text has the desired appearance, use <a href="GtkWidget.html#gtk-widget-modify-font"><code class="function">gtk_widget_modify_font()</code></a>
to change the default font for the widget.
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2561828"></a><a name="id2561830"></a><b>4.3.</b>
</td>
<td align="left" valign="top"><p>
How do I make a text view scroll to the end of the buffer automatically ?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
A good way to keep a text buffer scrolled to the end is to place a
<a href="GtkTextMark.html" title="GtkTextMark">mark</a> at the end of the buffer, and
give it right gravity. The gravity has the effect that text inserted
at the mark gets inserted <span class="emphasis"><em>before</em></span>, keeping the mark
at the end.
</p>
<p>
To ensure that the end of the buffer remains visible, use
<a href="GtkTextView.html#gtk-text-view-scroll-to-mark"><code class="function">gtk_text_view_scroll_to_mark()</code></a> to scroll to the mark after
inserting new text.
</p>
<p>
The gtk-demo application contains an example of this technique.
</p>
</td>
</tr>
<tr class="qandadiv"><td align="left" valign="top" colspan="2">
<a name="id2561883"></a><h5 class="title">
<a name="id2561883"></a>5. <a href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</span></a>
</h5>
</td></tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2561893"></a><a name="id2561895"></a><b>5.1.</b>
</td>
<td align="left" valign="top"><p>
How do I associate some data with a row in the tree?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p>
Remember that the <a href="GtkTreeModel.html" title="GtkTreeModel"><span class="type">GtkTreeModel</span></a> 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 <a href="GtkTreeModel.html#gtk-tree-model-get"><code class="function">gtk_tree_model_get()</code></a>. See the
<a href="TreeWidget.html" title="Tree and List Widget Overview">tree widget overview</a>.
</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2561938"></a><a name="id2561941"></a><b>5.2.</b>
</td>
<td align="left" valign="top"><p>
What's the <a href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</span></a> equivalent of <a href="GtkCList.html#gtk-clist-find-row-from-data"><code class="function">gtk_clist_find_row_from_data()</code></a>?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p>
As there is no separate data column in the <a href="GtkTreeModel.html" title="GtkTreeModel"><span class="type">GtkTreeModel</span></a>, 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
<a href="GtkTreeModel.html#gtk-tree-model-foreach"><code class="function">gtk_tree_model_foreach()</code></a>.
</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2561996"></a><a name="id2561998"></a><b>5.3.</b>
</td>
<td align="left" valign="top"><p>
How do I put an image and some text in the same column?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p>
You can pack more than one <a href="GtkCellRenderer.html" title="GtkCellRenderer"><span class="type">GtkCellRenderer</span></a> into a single <a href="GtkTreeViewColumn.html" title="GtkTreeViewColumn"><span class="type">GtkTreeViewColumn</span></a> using
<a href="GtkTreeViewColumn.html#gtk-tree-view-column-pack-start"><code class="function">gtk_tree_view_column_pack_start()</code></a> or <a href="GtkTreeViewColumn.html#gtk-tree-view-column-pack-end"><code class="function">gtk_tree_view_column_pack_end()</code></a>. So pack both
a <a href="GtkCellRendererPixbuf.html" title="GtkCellRendererPixbuf"><span class="type">GtkCellRendererPixbuf</span></a> and a <a href="GtkCellRendererText.html" title="GtkCellRendererText"><span class="type">GtkCellRendererText</span></a> into the column.
</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2562074"></a><a name="id2562076"></a><b>5.4.</b>
</td>
<td align="left" valign="top"><p>
I can set data easily on my <a href="GtkTreeStore.html" title="GtkTreeStore"><span class="type">GtkTreeStore</span></a>/<a href="GtkListStore.html" title="GtkListStore"><span class="type">GtkListStore</span></a> models using
<a href="GtkListStore.html#gtk-list-store-set"><code class="function">gtk_list_store_set()</code></a> and <a href="GtkTreeStore.html#gtk-tree-store-set"><code class="function">gtk_tree_store_set()</code></a>, but can't read it back?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p>
Both the <a href="GtkTreeStore.html" title="GtkTreeStore"><span class="type">GtkTreeStore</span></a> and the <a href="GtkListStore.html" title="GtkListStore"><span class="type">GtkListStore</span></a> implement the <a href="GtkTreeModel.html" title="GtkTreeModel"><span class="type">GtkTreeModel</span></a>
interface. Consequentially, the can use any function this interface implements.
The easiest way to read a set of data back is to use <a href="GtkTreeModel.html#gtk-tree-model-get"><code class="function">gtk_tree_model_get()</code></a>.
</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2562169"></a><a name="id2562171"></a><b>5.5.</b>
</td>
<td align="left" valign="top"><p>
How do I change the way that numbers are formatted by <a href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</span></a>?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
Use <a href="GtkTreeView.html#gtk-tree-view-insert-column-with-data-func"><code class="function">gtk_tree_view_insert_column_with_data_func()</code></a>
or <a href="GtkTreeViewColumn.html#gtk-tree-view-column-set-cell-data-func"><code class="function">gtk_tree_view_column_set_cell_data_func()</code></a> and do the conversion from number to
string yourself (with, say, <a
href="../glib/glib-String-Utility-Functions.html#g-strdup-printf"
><code class="function">g_strdup_printf()</code></a>).
</p>
<p>
The following example demonstrates this:
</p>
<div class="informalexample"><pre class="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, &d, -1);
/* Now we can format the value ourselves. */
text = g_strdup_printf ("%.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);
}
</pre></div>
<p>
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2562250"></a><a name="id2562286"></a><b>5.6.</b>
</td>
<td align="left" valign="top"><p>
How do I hide the expander arrows in my tree view ?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p>
Set the expander-column property of the tree view to a hidden column.
See <a href="GtkTreeView.html#gtk-tree-view-set-expander-column"><code class="function">gtk_tree_view_set_expander_column()</code></a> and <a href="GtkTreeViewColumn.html#gtk-tree-view-column-set-visible"><code class="function">gtk_tree_view_column_set_visible()</code></a>.
</p></td>
</tr>
<tr class="qandadiv"><td align="left" valign="top" colspan="2">
<a name="id2562323"></a><h5 class="title">
<a name="id2562323"></a>6. Using cairo with GTK+</h5>
</td></tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2562328"></a><a name="id2562330"></a><b>6.1.</b>
</td>
<td align="left" valign="top"><p>
How do I use cairo to draw in GTK+ applications ?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p>
USe <a
href="../gdk/gdk-Cairo-Interaction.html#gdk-cairo-create"
><code class="function">gdk_cairo_create()</code></a> to obtain a cairo context for drawing
on a GDK window or pixmap. See <a
href="../gdk/gdk-Cairo-Interaction.html"
>Cairo
Interaction</a> for some more useful functions.
</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2562363"></a><a name="id2562365"></a><b>6.2.</b>
</td>
<td align="left" valign="top"><p>
I have created a cairo context with <a
href="../gdk/gdk-Cairo-Interaction.html#gdk-cairo-create"
><code class="function">gdk_cairo_create()</code></a>, but when I
later use it, my drawing does not show up. Why is that ?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top">
<p>
All drawing in GTK+ is normally done in an expose handler, and GTK+
creates a temporary pixmap for double-buffering the drawing. If you
create a cairo context outside the expose handler, it is backed
by the GDK window itself, not the double-buffering pixmap. Consequently,
any drawing you do with that cairo context gets overwritten at the
end of the expose handler, when the double-buffering pixmap is copied
back.
</p>
<p>
Possible solutions to this problem are:
</p>
<div class="itemizedlist"><ul type="disc">
<li><p>
Turn off double-buffering, with <a href="GtkWidget.html#gtk-widget-set-double-buffered"><code class="function">gtk_widget_set_double_buffered()</code></a>.
This is not ideal, since it can cause some flickering.
</p></li>
<li><p>
Create the cairo context inside the expose handler. If you do this,
<code class="function">gdk_create_cairo()</code> arranges for it to be backed by the double-buffering
pixmap. This is the preferred solution, and is used throughout GTK+
itself.
</p></li>
</ul></div>
<p>
</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2562441"></a><a name="id2562443"></a><b>6.3.</b>
</td>
<td align="left" valign="top"><p>
Can I improve the performance of my application by using the
Glitz backend of cairo ?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p>
No. The GDK X11 backend uses the cairo X backend (and the other
GDK backends use their respective native cairo backends). The
GTK+ developers believe that the best way to improving the GDK
drawing performance is to optimize the cairo X backend and the
relevant code paths in the X server that is uses (mostly the
Render extension).
</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2562460"></a><a name="id2562462"></a><b>6.4.</b>
</td>
<td align="left" valign="top"><p>
Can I use cairo to draw on a <a
href="../gdk-pixbuf/gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf"
><span class="type">GdkPixbuf</span></a> ?
</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"><b></b></td>
<td align="left" valign="top"><p>
No, at least not yet. The cairo image surface does not support the
pixel format used by GdkPixbuf.
</p></td>
</tr>
</tbody>
</table></div>
</div>
<div class="footnotes">
<br><hr width="100" align="left">
<div class="footnote"><p><sup>[<a name="ftn.id2560808" href="#id2560808">1</a>] </sup> If the file load fails, <a href="GtkImage.html#gtk-image-new-from-file"><code class="function">gtk_image_new_from_file()</code></a> will display no
image graphic — to detect a failed load yourself, use <a
href="../gdk-pixbuf/gdk-pixbuf-file-loading.html#gdk-pixbuf-new-from-file"
><code class="function">gdk_pixbuf_new_from_file()</code></a>
directly, then <a href="GtkImage.html#gtk-image-new-from-pixbuf"><code class="function">gtk_image_new_from_pixbuf()</code></a>.</p></div>
</div>
</div>
</body>
</html>