AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

Update some outdated content in the question index

Browse Source 
Based on a patch by Jasper St. Pierre
https://bugzilla.gnome.org/show_bug.cgi?id=639494
This commit is contained in:
Matthias Clasen 2011-01-13 23:10:25 -05:00
parent b23839c7a5
commit 04248fbd39
1 changed files with 168 additions and 205 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

373
docs/reference/gtk/question_index.sgml
View File

@ -35,8 +35,8 @@ How do I get started with GTK+?
</para></question> </para></question>
<answer><para> <answer><para>
The GTK+ <ulink url="http://www.gtk.org">website</ulink> offers a 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/tutorial">tutorial</ulink> and a
<ulink url="http://www.gtk.org/faq">FAQ</ulink>. More documentation ranging <ulink url="http://www.gtk.org/faq">FAQ</ulink>. More documentation ranging
from whitepapers to online books can be found at the from whitepapers to online books can be found at the
<ulink url="http://library.gnome.org/devel/">GNOME developer's site</ulink>. <ulink url="http://library.gnome.org/devel/">GNOME developer's site</ulink>.
@ -47,7 +47,7 @@ this reference manual for details.
<qandaentry> <qandaentry>
<question><para> <question><para>
Where can I get help with GTK+, submit a bug report, or make a feature Where can I get help with GTK+, submit a bug report, or make a feature
request? request?
</para></question> </para></question>
@ -102,11 +102,11 @@ state (explained in its documentation).
</para> </para>
<para> <para>
For strings returned from functions, they will be declared "const" (using For strings returned from functions, they will be declared "const" (using
#G_CONST_RETURN) if they should not be freed. Non-const strings should be #G_CONST_RETURN) if they should not be freed. Non-const strings should be
freed with g_free(). Arrays follow the same rule. (If you find an exception freed with g_free(). Arrays follow the same rule. If you find an
to the rules, please report a bug to <ulink undocumented exception to the rules, please report a bug to <ulink
url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.) url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.
</para> </para>
</answer> </answer>
@ -164,8 +164,8 @@ How do I use GTK+ with threads?
<answer> <answer>
<para> <para>
This is covered in the <link linkend="gdk-Threads">GDK threads This is covered in the <link linkend="gdk-Threads">GDK threads
documentation</link>. See also the <link linkend="glib-Threads">GThread</link> documentation</link>. See also the <link linkend="glib-Threads">GThread</link>
documentation for portable threading primitives. documentation for portable threading primitives.
</para> </para>
@ -182,33 +182,37 @@ How do I internationalize a GTK+ program?
<para> <para>
Most people use <ulink url="http://www.gnu.org/software/gettext/">GNU Most people use <ulink url="http://www.gnu.org/software/gettext/">GNU
gettext</ulink>, already required in order to install GLib. On a UNIX gettext</ulink>, already required in order to install GLib. On a UNIX
or Linux system with gettext installed, type <literal>info gettext</literal> or Linux system with gettext installed, type <literal>info gettext</literal>
to read the documentation. to read the documentation.
</para> </para>
<para> <para>
The short checklist on how to use gettext is: call bindtextdomain() so gettext The short checklist on how to use gettext is: call bindtextdomain() so
can find the files containing your translations, call textdomain() to set the gettext can find the files containing your translations, call textdomain()
default translation domain, call bind_textdomain_codeset() to request that to set the default translation domain, call bind_textdomain_codeset() to
all translated strings are returned in UTF-8, then call gettext() to look up request that all translated strings are returned in UTF-8, then call
each string to be translated in the default domain. gettext() to look up each string to be translated in the default domain.
</para>
<para>
<filename>gi18n.h</filename> provides the following shorthand macros for
convenience.
Conventionally, people define macros as follows for convenience: Conventionally, people define macros as follows for convenience:
<informalexample> <informalexample>
<programlisting> <programlisting>
#define _(x) gettext (x) #define _(x) gettext (x)
#define N_(x) x #define N_(x) x
#define C_(ctx,x) pgettext (ctx, x)
</programlisting> </programlisting>
</informalexample> </informalexample>
You use N_() (N stands for no-op) to mark a string for translation in a You use N_() (N stands for no-op) to mark a string for translation in
context where a function call to gettext() is not allowed, such as in an a location where a function call to gettext() is not allowed, such as
array initializer. in an array initializer.
You eventually have to call gettext() on the string to actually fetch the You eventually have to call gettext() on the string to actually fetch
translation. _() both marks the string for translation and actually the translation. _() both marks the string for translation and actually
translates it. translates it.
</para> The C_() macro (C stands for context) adds an additional context to
<para> the string that is marked for translation, which can help to disambiguate
Nowadays, GLib provides the common shorthand macros in the header file short strings that might need different translations in different
<filename>gi18n.h</filename>, so you don't have to define them yourself, parts of your program.
just include that header.
</para> </para>
<para> <para>
Code using these macros ends up looking like this: Code using these macros ends up looking like this:
@ -231,21 +235,21 @@ Code using these macros ends up looking like this:
</informalexample> </informalexample>
</para> </para>
<para> <para>
Libraries using gettext should use dgettext() instead of gettext(), which Libraries using gettext should use dgettext() instead of gettext(), which
allows them to specify the translation domain each time they ask for a allows them to specify the translation domain each time they ask for a
translation. Libraries should also avoid calling textdomain(), since they translation. Libraries should also avoid calling textdomain(), since
will be specifying the domain instead of using the default. For dgettext() they will be specifying the domain instead of using the default.
the _() macro can be defined as:
<informalexample>
<programlisting>
#define _(x) dgettext ("MyDomain", x)
</programlisting>
</informalexample>
</para> </para>
<para> <para>
Again, GLib comes with the <filename>gi18n-lib.h</filename>, saving you the With the convention that the macro <literal>GETTEXT_PACKAGE</literal> is
trouble of defining the macros by hand. The macros in that header expect the defined to hold your libraries translation domain,
translation domain to be specified by the %GETTEXT_PACKAGE macro. <filename>gi18n-lib.h</filename> can be included to provide
the following convenience:
<informalexample>
<programlisting>
#define _(x) dgettext (GETTEXT_PACKAGE, x)
</programlisting>
</informalexample>
</para> </para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -259,9 +263,9 @@ How do I use non-ASCII characters in GTK+ programs ?
<answer> <answer>
<para> <para>
GTK+ uses <ulink url="http://www.unicode.org">Unicode</ulink> (more exactly 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 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 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: choice for working with Unicode text in C programs:
<itemizedlist> <itemizedlist>
<listitem><para> <listitem><para>
@ -271,30 +275,30 @@ ASCII characters are encoded by their familiar ASCII codepoints.
ASCII characters never appear as part of any other character. ASCII characters never appear as part of any other character.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
The zero byte doesn't occur as part of a character, so that UTF-8 strings 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 can be manipulated with the usual C library functions for handling
zero-terminated strings. zero-terminated strings.
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
More information about Unicode and UTF-8 can be found in the 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 i <ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode
FAQ for Unix/Linux</ulink>. FAQ for Unix/Linux</ulink>.
GLib provides functions for converting strings between UTF-8 and other GLib provides functions for converting strings between UTF-8 and other
encodings, see g_locale_to_utf8() and g_convert(). encodings, see g_locale_to_utf8() and g_convert().
</para> </para>
<para> <para>
Text coming from external sources (e.g. files or user input), has to be 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 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 writes the content of a IS0-8859-1 encoded text file to
<literal>stdout</literal>: <literal>stdout</literal>:
<informalexample><programlisting> <informalexample><programlisting>
gchar *text, *utf8_text; gchar *text, *utf8_text;
gsize length; gsize length;
GError *error = NULL; GError *error = NULL;
if (g_file_get_contents (filename, &amp;text, &amp;length, NULL)) if (g_file_get_contents (filename, &amp;text, &amp;length, NULL))
{ {
utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1", utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1",
NULL, NULL, &amp;error); NULL, NULL, &amp;error);
if (error != NULL) if (error != NULL)
{ {
@ -304,7 +308,7 @@ if (g_file_get_contents (filename, &amp;text, &amp;length, NULL))
else else
g_print (utf8_text); g_print (utf8_text);
} }
else else
fprintf (stderr, "Unable to read file &percnt;s\n", filename); fprintf (stderr, "Unable to read file &percnt;s\n", filename);
</programlisting></informalexample> </programlisting></informalexample>
</para> </para>
@ -315,36 +319,37 @@ handling non-ASCII content:
<varlistentry><term>direct UTF-8</term> <varlistentry><term>direct UTF-8</term>
<listitem><para> <listitem><para>
If your editor and compiler are capable of handling UTF-8 encoded sources, 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 it is very convenient to simply use UTF-8 for string literals, since it
you to edit the strings in "wysiwyg". Note that choosing this option may allows you to edit the strings in "wysiwyg". Note that choosing this option
reduce the portability of your code. may reduce the portability of your code.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry><term>escaped UTF-8</term> <varlistentry><term>escaped UTF-8</term>
<listitem><para> <listitem><para>
Even if your toolchain can't handle UTF-8 directly, you can still encode string Even if your toolchain can't handle UTF-8 directly, you can still encode
literals in UTF-8 by using octal or hexadecimal escapes like string literals in UTF-8 by using octal or hexadecimal escapes like
<literal>\212</literal> or <literal>\xa8</literal> to <literal>\212</literal> or <literal>\xa8</literal> to encode each byte.
encode each byte. This is portable, but modifying the escaped strings is not This is portable, but modifying the escaped strings is not very convenient.
very convenient. Be careful when mixing hexadecimal escapes with ordinary text; Be careful when mixing hexadecimal escapes with ordinary text;
<literal>"\xa8abcd"</literal> is a string of length 1 ! <literal>"\xa8abcd"</literal> is a string of length 1 !
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
<varlistentry><term>runtime conversion</term> <varlistentry><term>runtime conversion</term>
<listitem><para> <listitem><para>
If the string literals can be represented in an encoding which your toolchain If the string literals can be represented in an encoding which your
can handle (e.g. IS0-8859-1), you can write your source files in that encoding toolchain can handle (e.g. IS0-8859-1), you can write your source files
and use g_convert() to convert the strings to UTF-8 at runtime. Note that this in that encoding and use g_convert() to convert the strings to UTF-8 at
has some runtime overhead, so you may want to move the conversion out of inner runtime. Note that this has some runtime overhead, so you may want to move
loops. the conversion out of inner loops.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
Here is an example showing the three approaches using the copyright sign 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 &copy; which has Unicode and ISO-8859-1 codepoint 169 and is represented
UTF-8 by the two bytes 194, 169: in UTF-8 by the two bytes 194, 169, or <literal>"\302\251"</literal> as
a string literal:
<informalexample><programlisting> <informalexample><programlisting>
g_print ("direct UTF-8: &copy;"); g_print ("direct UTF-8: &copy;");
g_print ("escaped UTF-8: \302\251"); g_print ("escaped UTF-8: \302\251");
@ -368,9 +373,9 @@ How do I use GTK+ with C++?
<answer> <answer>
<para> <para>
There are two ways to approach this. The GTK+ header files use the subset 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 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" in a C++ program. Alternatively, you can use a "C++ binding"
such as <ulink url="http://gtkmm.sourceforge.net/">gtkmm</ulink> such as <ulink url="http://gtkmm.sourceforge.net/">gtkmm</ulink>
which provides a native C++ API. which provides a native C++ API.
</para> </para>
@ -380,20 +385,20 @@ connected to signals, not methods. So you will need to use global
functions or "static" class functions for signal connections. functions or "static" class functions for signal connections.
</para> </para>
<para> <para>
Another common issue when using GTK+ directly is that Another common issue when using GTK+ directly is that
C++ will not implicitly convert an integer to an enumeration. C++ will not implicitly convert an integer to an enumeration.
This comes up when using bitfields; in C you can write the following This comes up when using bitfields; in C you can write the following
code: code:
<informalexample> <informalexample>
<programlisting> <programlisting>
gdk_window_set_events (gdk_window, gdk_window_set_events (gdk_window,
GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK); GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
</programlisting> </programlisting>
</informalexample> </informalexample>
while in C++ you must write: while in C++ you must write:
<informalexample> <informalexample>
<programlisting> <programlisting>
gdk_window_set_events (gdk_window, gdk_window_set_events (gdk_window,
(GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK); (GdkEventMask) GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
</programlisting> </programlisting>
</informalexample> </informalexample>
@ -427,19 +432,19 @@ How do I load an image or animation from a file?
<answer> <answer>
<para> <para>
To load an image file straight into a display widget, use To load an image file straight into a display widget, use
gtk_image_new_from_file() <footnote><para> If the file load fails, gtk_image_new_from_file() <footnote><para> If the file load fails,
gtk_image_new_from_file() will display no image graphic &mdash; to detect gtk_image_new_from_file() will display no image graphic &mdash; to detect
a failed load yourself, use gdk_pixbuf_new_from_file() directly, then a failed load yourself, use gdk_pixbuf_new_from_file() directly, then
gtk_image_new_from_pixbuf().</para></footnote>. gtk_image_new_from_pixbuf().</para></footnote>.
To load an image for another purpose, use gdk_pixbuf_new_from_file(). To i To load an image for another purpose, use gdk_pixbuf_new_from_file(). To i
load an animation, use gdk_pixbuf_animation_new_from_file(). load an animation, use gdk_pixbuf_animation_new_from_file().
gdk_pixbuf_animation_new_from_file() can also load non-animated images, so gdk_pixbuf_animation_new_from_file() can also load non-animated images, so
use it in combination with gdk_pixbuf_animation_is_static_image() to load a use it in combination with gdk_pixbuf_animation_is_static_image() to load a
file of unknown type. file of unknown type.
</para> </para>
<para> <para>
To load an image or animation file asynchronously (without blocking), use To load an image or animation file asynchronously (without blocking), use
#GdkPixbufLoader. #GdkPixbufLoader.
</para> </para>
</answer> </answer>
@ -453,14 +458,13 @@ How do I draw text ?
<answer> <answer>
<para> <para>
To draw a piece of text, use a Pango layout and gdk_draw_layout(), To draw a piece of text, use a Pango layout and gdk_draw_layout().
using code like the following:
<informalexample> <informalexample>
<programlisting> <programlisting>
layout = gtk_widget_create_pango_layout (widget, text); layout = gtk_widget_create_pango_layout (widget, text);
fontdesc = pango_font_description_from_string ("Luxi Mono 12"); fontdesc = pango_font_description_from_string ("Luxi Mono 12");
pango_layout_set_font_description (layout, fontdesc); pango_layout_set_font_description (layout, fontdesc);
gdk_draw_layout (..., layout); pango_cairo_show_layout (cr, layout);
pango_font_description_free (fontdesc); pango_font_description_free (fontdesc);
g_object_unref (layout); g_object_unref (layout);
</programlisting> </programlisting>
@ -485,13 +489,13 @@ How do I measure the size of a piece of text ?
<answer> <answer>
<para> <para>
To obtain the size of a piece of text, use a Pango layout and To obtain the size of a piece of text, use a Pango layout and
pango_layout_get_pixel_size(), using code like the following: pango_layout_get_pixel_size(), using code like the following:
<informalexample> <informalexample>
<programlisting> <programlisting>
layout = gtk_widget_create_pango_layout (widget, text); layout = gtk_widget_create_pango_layout (widget, text);
fontdesc = pango_font_description_from_string ("Luxi Mono 12"); fontdesc = pango_font_description_from_string ("Luxi Mono 12");
pango_layout_set_font_description (layout, fontdesc); pango_layout_set_font_description (layout, fontdesc);
pango_layout_get_pixel_size (layout, &amp;width, &amp;height); pango_layout_get_pixel_size (layout, &amp;width, &amp;height);
pango_font_description_free (fontdesc); pango_font_description_free (fontdesc);
g_object_unref (layout); g_object_unref (layout);
@ -510,21 +514,21 @@ section of <ulink url="http://library.gnome.org/devel/pango/stable/">Pango manua
<qandaentry> <qandaentry>
<question> <question>
<para> <para>
Why are types not registered if I use their <literal>GTK_TYPE_BLAH</literal> Why are types not registered if I use their <literal>GTK_TYPE_BLAH</literal>
macro ? macro ?
</para> </para>
</question> </question>
<answer> <answer>
<para> <para>
The <literal>GTK_TYPE_BLAH</literal> macros are defined as calls to The <literal>GTK_TYPE_BLAH</literal> macros are defined as calls to
<literal>gtk_blah_get_type()</literal>, and the <literal>_get_type()</literal> i <literal>gtk_blah_get_type()</literal>, and the <literal>_get_type()</literal> i
functions are declared as %G_GNUC_CONST which allows the compiler to optimize functions are declared as %G_GNUC_CONST which allows the compiler to optimize
the call away if it appears that the value is not being used. the call away if it appears that the value is not being used.
</para> </para>
<para> <para>
A common workaround for this problem is to store the result in a volatile A common workaround for this problem is to store the result in a volatile
variable, which keeps the compiler from optimizing the call away. variable, which keeps the compiler from optimizing the call away.
<informalexample><programlisting> <informalexample><programlisting>
volatile GType dummy = GTK_TYPE_BLAH; volatile GType dummy = GTK_TYPE_BLAH;
@ -543,7 +547,7 @@ How do I create a transparent toplevel window ?
<answer> <answer>
<para> <para>
To make a window transparent, it needs to use a visual which supports that. 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 This is done by getting the RGBA colormap of the screen with
gdk_screen_get_rgba_colormap() and setting it on the window. Note that gdk_screen_get_rgba_colormap() and setting it on the window. Note that
gdk_screen_get_rgba_colormap() will return %NULL if transparent windows gdk_screen_get_rgba_colormap() will return %NULL if transparent windows
are not supported on the screen; also note that this may change from are not supported on the screen; also note that this may change from
@ -563,8 +567,8 @@ gdk_draw_rgb_32_image().
</para> </para>
<para> <para>
Note that the presence of an RGBA visual is no guarantee that the Note that the presence of an RGBA visual is no guarantee that the
window will actually appear transparent on screen. On X11, this window will actually appear transparent on screen. On X11, this
requires a compositing manager to be running. See requires a compositing manager to be running. See
gtk_widget_is_composited() for a way to find out if the alpha gtk_widget_is_composited() for a way to find out if the alpha
channel will be respected. channel will be respected.
</para> </para>
@ -583,7 +587,7 @@ channel will be respected.
<answer> <answer>
<para> <para>
See <link linkend="TreeWidget">tree widget overview</link> &mdash; you See <link linkend="TreeWidget">tree widget overview</link> &mdash; you
should use the #GtkTreeView widget. (A list is just a tree with no branches, should use the #GtkTreeView widget. (A list is just a tree with no branches,
so the tree widget is used for lists as well). so the tree widget is used for lists as well).
</para> </para>
</answer> </answer>
@ -600,8 +604,8 @@ See <link linkend="TextWidget">text widget overview</link> &mdash; you
should use the #GtkTextView widget. should use the #GtkTextView widget.
</para> </para>
<para> <para>
If you only have a small amount of text, #GtkLabel may also be appropriate If you only have a small amount of text, #GtkLabel may also be appropriate
of course. It can be made selectable with gtk_label_set_selectable(). For a of course. It can be made selectable with gtk_label_set_selectable(). For a
single-line text entry, see #GtkEntry. single-line text entry, see #GtkEntry.
</para> </para>
</answer> </answer>
@ -615,8 +619,8 @@ single-line text entry, see #GtkEntry.
<answer> <answer>
<para> <para>
#GtkImage can display images in just about any format GTK+ understands. #GtkImage can display images in just about any format GTK+ understands.
You can also use #GtkDrawingArea if you need to do something more complex, You can also use #GtkDrawingArea if you need to do something more complex,
such as draw text or graphics over the top of the image. such as draw text or graphics over the top of the image.
</para> </para>
</answer> </answer>
@ -648,17 +652,14 @@ How do I change the color of a widget?
</para></question> </para></question>
<answer><para> <answer><para>
See gtk_widget_modify_fg(), gtk_widget_modify_bg(), gtk_widget_modify_base(), See gtk_widget_override_color() and gtk_widget_override_background_color().
and gtk_widget_modify_text(). See <link linkend="gtk-Resource-Files">GTK+ You can also change the appearance of a widget by installing a
resource files</link> for more discussion. You can also change widget color custom style provider, see gtk_style_context_add_provider().
by installing a resource file and parsing it with gtk_rc_add_default_file().
The advantage of a resource file is that users can then override the
color you've chosen.
</para> </para>
<para>To change the background color for widgets such as #GtkLabel that have <para>To change the background color for widgets such as #GtkLabel that
no background, place them in a #GtkEventBox and set the background of the have no background, place them in a #GtkEventBox and set the background
event box. of the event box.
</para></answer> </para></answer>
</qandaentry> </qandaentry>
@ -668,35 +669,38 @@ How do I change the font of a widget?
</para></question> </para></question>
<answer><para> <answer><para>
This has several possible answers, depending on what exactly you want to This has several possible answers, depending on what exactly you want to
achieve. One option is gtk_widget_modify_font(). Note that this function achieve. One option is gtk_widget_override_font().
can be used to change only the font size, as in the following example:
<informalexample><programlisting> <informalexample><programlisting>
PangoFontDesc *font_desc = pango_font_description_new (<!-- -->); PangoFontDesc *font_desc = pango_font_description_new (<!-- -->);
pango_font_description_set_size (font_desc, 40); pango_font_description_set_size (font_desc, 40);
gtk_widget_modify_font (widget, font); gtk_widget_override_font (widget, font);
pango_font_description_free (font_desc); pango_font_description_free (font_desc);
</programlisting></informalexample> </programlisting></informalexample>
</para> </para>
<para> <para>
If you want to make the text of a label larger, you can use If you want to make the text of a label larger, you can use
gtk_label_set_markup(): gtk_label_set_markup():
<informalexample><programlisting> <informalexample><programlisting>
gtk_label_set_markup (label, "&lt;big&gt;big text&lt;/big&gt;"); gtk_label_set_markup (label, "&lt;big&gt;big text&lt;/big&gt;");
</programlisting></informalexample> </programlisting></informalexample>
This is preferred for many apps because it's a relative size to the This is preferred for many apps because it's a relative size to the
user's chosen font size. See g_markup_escape_text() if you are user's chosen font size. See g_markup_escape_text() if you are
constructing such strings on the fly. constructing such strings on the fly.
</para> </para>
<para> <para>
You can also change the font of a widget by putting You can also change the font of a widget by putting
<programlisting> <programlisting>
gtk-font-name = "Sans 30" .my-widget-class {
font: Sans 30;
}
</programlisting> </programlisting>
in a resource file and parsing it with gtk_rc_add_default_file(). in a CSS file, loading it with gtk_css_provider_load_from_file(), and
The advantage of a resource file is that users can then override the font you adding the provider with gtk_style_context_add_provider_for_screen().
have chosen. See <link linkend="gtk-Resource-Files">GTK+ resource files</link> To associate this style information with your widget, set a style class
for more discussion. on its #GtkStyleContext using gtk_style_context_add_class().
The advantage of this approach is that users can then override the font
you have chosen. See the #GtkStyleContext documentation for more discussion.
</para> </para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -706,8 +710,9 @@ for more discussion.
How do I disable/ghost/desensitize a widget? How do I disable/ghost/desensitize a widget?
</para></question> </para></question>
<answer><para> In GTK+ a disabled widget is termed "insensitive." See <answer><para>
gtk_widget_set_sensitive(). In GTK+ a disabled widget is termed "insensitive."
See gtk_widget_set_sensitive().
</para></answer> </para></answer>
</qandaentry> </qandaentry>
@ -746,14 +751,14 @@ How do I make a text widget display its complete contents in a specific font?
</para></question> </para></question>
<answer><para> <answer><para>
If you use gtk_text_buffer_insert_with_tags() with appropriate tags to select If you use gtk_text_buffer_insert_with_tags() with appropriate tags to
the font, the inserted text will have the desired appearance, but text typed select the font, the inserted text will have the desired appearance, but
in by the user before or after the tagged block will appear in the default text typed in by the user before or after the tagged block will appear in
style. the default style.
</para> </para>
<para> <para>
To ensure that all text has the desired appearance, use gtk_widget_modify_font() To ensure that all text has the desired appearance, use
to change the default font for the widget. gtk_widget_override_font() to change the default font for the widget.
</para></answer> </para></answer>
</qandaentry> </qandaentry>
@ -770,17 +775,17 @@ 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 <link linkend="GtkTextMark">mark</link> at the end of the buffer, and
give it right gravity. The gravity has the effect that text inserted 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 mark gets inserted <emphasis>before</emphasis>, keeping the mark
at the end. at the end.
</para> </para>
<para> <para>
To ensure that the end of the buffer remains visible, use To ensure that the end of the buffer remains visible, use
gtk_text_view_scroll_to_mark() to scroll to the mark after gtk_text_view_scroll_to_mark() to scroll to the mark after
inserting new text. inserting new text.
</para> </para>
<para> <para>
The gtk-demo application contains an example of this technique. The gtk-demo application contains an example of this technique.
</para> </para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -797,25 +802,10 @@ How do I associate some data with a row in the tree?
<answer> <answer>
<para> <para>
Remember that the #GtkTreeModel columns don't necessarily have to be displayed. Remember that the #GtkTreeModel columns don't necessarily have to be
So you can put non-user-visible data in your model just like any other data, displayed. So you can put non-user-visible data in your model just
and retrieve it with gtk_tree_model_get(). See the like any other data, and retrieve it with gtk_tree_model_get().
<link linkend="TreeWidget">tree widget overview</link>. See the <link linkend="TreeWidget">tree widget overview</link>.
</para>
</answer>
</qandaentry>
<qandaentry>
<question><para>
What's the #GtkTreeView equivalent of gtk_clist_find_row_from_data()?
</para></question>
<answer>
<para>
As there is no separate data column in the #GtkTreeModel, there's no
built in function to find the iter from data. You can write a custom
searching function to walk the tree and find the data, or use
gtk_tree_model_foreach().
</para> </para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -827,9 +817,9 @@ How do I put an image and some text in the same column?
<answer> <answer>
<para> <para>
You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn
using gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end(). using gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end().
So pack both a #GtkCellRendererPixbuf and a #GtkCellRendererText into the So pack both a #GtkCellRendererPixbuf and a #GtkCellRendererText into the
column. column.
</para> </para>
</answer> </answer>
@ -837,15 +827,15 @@ column.
<qandaentry> <qandaentry>
<question><para> <question><para>
I can set data easily on my #GtkTreeStore/#GtkListStore models using I can set data easily on my #GtkTreeStore/#GtkListStore models using
gtk_list_store_set() and gtk_tree_store_set(), but can't read it back? gtk_list_store_set() and gtk_tree_store_set(), but can't read it back?
</para></question> </para></question>
<answer> <answer>
<para> <para>
Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel
interface. Consequentially, the can use any function this interface interface. Consequentially, you can use any function this interface
implements. The easiest way to read a set of data back is to use implements. The easiest way to read a set of data back is to use
gtk_tree_model_get(). gtk_tree_model_get().
</para> </para>
</answer> </answer>
@ -857,14 +847,14 @@ How do I change the way that numbers are formatted by #GtkTreeView?
</para></question> </para></question>
<answer><para> <answer><para>
Use gtk_tree_view_insert_column_with_data_func() Use gtk_tree_view_insert_column_with_data_func()
or gtk_tree_view_column_set_cell_data_func() and do the conversion from i or gtk_tree_view_column_set_cell_data_func() and do the conversion
number to string yourself (with, say, g_strdup_printf()). from number to string yourself (with, say, g_strdup_printf()).
</para> </para>
<para> <para>
The following example demonstrates this: The following example demonstrates this:
<informalexample><programlisting> <informalexample><programlisting>
enum enum
{ {
DOUBLE_COLUMN, DOUBLE_COLUMN,
N_COLUMNS N_COLUMNS
@ -873,11 +863,11 @@ enum
GtkListStore *mycolumns; GtkListStore *mycolumns;
GtkTreeView *treeview; GtkTreeView *treeview;
void void
my_cell_double_to_text (GtkTreeViewColumn *tree_column, my_cell_double_to_text (GtkTreeViewColumn *tree_column,
GtkCellRenderer *cell, GtkCellRenderer *cell,
GtkTreeModel *tree_model, GtkTreeModel *tree_model,
GtkTreeIter *iter, GtkTreeIter *iter,
gpointer data) gpointer data)
{ {
GtkCellRendererText *cell_text = (GtkCellRendererText *)cell; GtkCellRendererText *cell_text = (GtkCellRendererText *)cell;
@ -892,7 +882,7 @@ my_cell_double_to_text (GtkTreeViewColumn *tree_column,
g_free (text); g_free (text);
} }
void void
set_up_new_columns (GtkTreeView *myview) set_up_new_columns (GtkTreeView *myview)
{ {
GtkCellRendererText *renderer; GtkCellRendererText *renderer;
@ -908,7 +898,7 @@ set_up_new_columns (GtkTreeView *myview)
/* Create a new column that has a title ("Example column"), /* Create a new column that has a title ("Example column"),
* uses the above created renderer that will render the double * uses the above created renderer that will render the double
* value into text from the associated model's rows. * value into text from the associated model's rows.
*/ */
column = gtk_tree_view_column_new (<!-- -->); column = gtk_tree_view_column_new (<!-- -->);
gtk_tree_view_column_set_title (column, "Example column"); gtk_tree_view_column_set_title (column, "Example column");
@ -922,10 +912,10 @@ set_up_new_columns (GtkTreeView *myview)
*/ */
/* Set up a custom function that will be called when the column content /* 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 * is rendered. We use the func_data pointer as an index into our
* model. This is convenient when using multi column lists. * model. This is convenient when using multi column lists.
*/ */
gtk_tree_view_column_set_cell_data_func (column, renderer, gtk_tree_view_column_set_cell_data_func (column, renderer,
my_cell_double_to_text, my_cell_double_to_text,
(gpointer)DOUBLE_COLUMN, NULL); (gpointer)DOUBLE_COLUMN, NULL);
} }
</programlisting></informalexample> </programlisting></informalexample>
@ -953,42 +943,15 @@ How do I use cairo to draw in GTK+ applications ?
</para></question> </para></question>
<answer><para> <answer><para>
Use gdk_cairo_create() to obtain a cairo context for drawing The #GtkWidget::draw signal gets a ready-to-use cairo context
on a GDK window or pixmap. See <link linkend="gdk-Cairo-Interaction">Cairo as parameter that you should use.
Interaction</link> for some more useful functions.
</para></answer>
</qandaentry>
<qandaentry>
<question><para>
I have created a cairo context with gdk_cairo_create(), but when I
later use it, my drawing does not show up. Why is that ?
</para></question>
<answer>
<para>
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.
</para> </para>
<para> <para>
Possible solutions to this problem are: All drawing in GTK+ is normally done in a draw handler, and GTK+
<itemizedlist> creates a temporary pixmap for double-buffering the drawing.
<listitem><para> It is possible to turn off double-buffering, with
Turn off double-buffering, with gtk_widget_set_double_buffered(). gtk_widget_set_double_buffered(), but this is not ideal,
This is not ideal, since it can cause some flickering. since it can cause some flickering.
</para></listitem>
<listitem><para>
Create the cairo context inside the expose handler. If you do this,
gdk_cairo_create() arranges for it to be backed by the double-buffering
pixmap. This is the preferred solution, and is used throughout GTK+
itself.
</para></listitem>
</itemizedlist>
</para> </para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -996,7 +959,7 @@ itself.
<qandaentry> <qandaentry>
<question><para> <question><para>
Can I improve the performance of my application by using the Can I improve the performance of my application by using the
Glitz backend of cairo ? Glitz or GL backend of cairo ?
</para></question> </para></question>
<answer><para> <answer><para>
@ -1016,7 +979,7 @@ Can I use cairo to draw on a #GdkPixbuf ?
<answer><para> <answer><para>
No, at least not yet. The cairo image surface does not support the No, at least not yet. The cairo image surface does not support the
pixel format used by GdkPixbuf. pixel format used by GdkPixbuf.
</para></answer> </para></answer>
</qandaentry> </qandaentry>