Update some outdated content in the question index
Based on a patch by Jasper St. Pierre https://bugzilla.gnome.org/show_bug.cgi?id=639494
This commit is contained in:
Matthias Clasen
parent
b23839c7a5
commit
04248fbd39
@ -104,9 +104,9 @@ state (explained in its documentation).
|
||||
<para>
|
||||
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
|
||||
freed with g_free(). Arrays follow the same rule. (If you find an exception
|
||||
to the rules, please report a bug to <ulink
|
||||
url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.)
|
||||
freed with g_free(). Arrays follow the same rule. If you find an
|
||||
undocumented exception to the rules, please report a bug to <ulink
|
||||
url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.
|
||||
</para>
|
||||
|
||||
</answer>
|
||||
@ -186,29 +186,33 @@ 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 bindtextdomain() so gettext
|
||||
can find the files containing your translations, call textdomain() to set the
|
||||
default translation domain, call bind_textdomain_codeset() to request that
|
||||
all translated strings are returned in UTF-8, then call gettext() to look up
|
||||
each string to be translated in the default domain.
|
||||
The short checklist on how to use gettext is: call bindtextdomain() so
|
||||
gettext can find the files containing your translations, call textdomain()
|
||||
to set the default translation domain, call bind_textdomain_codeset() to
|
||||
request that all translated strings are returned in UTF-8, then call
|
||||
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:
|
||||
<informalexample>
|
||||
<programlisting>
|
||||
#define _(x) gettext (x)
|
||||
#define N_(x) x
|
||||
#define C_(ctx,x) pgettext (ctx, x)
|
||||
</programlisting>
|
||||
</informalexample>
|
||||
You use N_() (N stands for no-op) to mark a string for translation in a
|
||||
context where a function call to gettext() is not allowed, such as in an
|
||||
array initializer.
|
||||
You eventually have to call gettext() on the string to actually fetch the
|
||||
translation. _() both marks the string for translation and actually
|
||||
You use N_() (N stands for no-op) to mark a string for translation in
|
||||
a location where a function call to gettext() is not allowed, such as
|
||||
in an array initializer.
|
||||
You eventually have to call gettext() on the string to actually fetch
|
||||
the translation. _() both marks the string for translation and actually
|
||||
translates it.
|
||||
</para>
|
||||
<para>
|
||||
Nowadays, GLib provides the common shorthand macros in the header file
|
||||
<filename>gi18n.h</filename>, so you don't have to define them yourself,
|
||||
just include that header.
|
||||
The C_() 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:
|
||||
@ -233,19 +237,19 @@ Code using these macros ends up looking like this:
|
||||
<para>
|
||||
Libraries using gettext should use dgettext() instead of gettext(), which
|
||||
allows them to specify the translation domain each time they ask for a
|
||||
translation. Libraries should also avoid calling textdomain(), since they
|
||||
will be specifying the domain instead of using the default. For dgettext()
|
||||
the _() macro can be defined as:
|
||||
<informalexample>
|
||||
<programlisting>
|
||||
#define _(x) dgettext ("MyDomain", x)
|
||||
</programlisting>
|
||||
</informalexample>
|
||||
translation. Libraries should also avoid calling textdomain(), since
|
||||
they will be specifying the domain instead of using the default.
|
||||
</para>
|
||||
<para>
|
||||
Again, GLib comes with the <filename>gi18n-lib.h</filename>, saving you the
|
||||
trouble of defining the macros by hand. The macros in that header expect the
|
||||
translation domain to be specified by the %GETTEXT_PACKAGE macro.
|
||||
With the convention that the macro <literal>GETTEXT_PACKAGE</literal> is
|
||||
defined to hold your libraries translation domain,
|
||||
<filename>gi18n-lib.h</filename> can be included to provide
|
||||
the following convenience:
|
||||
<informalexample>
|
||||
<programlisting>
|
||||
#define _(x) dgettext (GETTEXT_PACKAGE, x)
|
||||
</programlisting>
|
||||
</informalexample>
|
||||
</para>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
@ -277,7 +281,7 @@ zero-terminated strings.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
More information about Unicode and UTF-8 can be found in the
|
||||
<ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode i
|
||||
<ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode
|
||||
FAQ for Unix/Linux</ulink>.
|
||||
GLib provides functions for converting strings between UTF-8 and other
|
||||
encodings, see g_locale_to_utf8() and g_convert().
|
||||
@ -315,36 +319,37 @@ handling non-ASCII content:
|
||||
<varlistentry><term>direct UTF-8</term>
|
||||
<listitem><para>
|
||||
If your editor and compiler are capable of handling UTF-8 encoded sources,
|
||||
it is very convenient to simply use UTF-8 for string literals, since it allows
|
||||
you to edit the strings in "wysiwyg". Note that choosing this option may
|
||||
reduce the portability of your code.
|
||||
it is very convenient to simply use UTF-8 for string literals, since it
|
||||
allows you to edit the strings in "wysiwyg". Note that choosing this option
|
||||
may reduce the portability of your code.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>escaped UTF-8</term>
|
||||
<listitem><para>
|
||||
Even if your toolchain can't handle UTF-8 directly, you can still encode string
|
||||
literals in UTF-8 by using octal or hexadecimal escapes like
|
||||
<literal>\212</literal> or <literal>\xa8</literal> to
|
||||
encode each byte. This is portable, but modifying the escaped strings is not
|
||||
very convenient. Be careful when mixing hexadecimal escapes with ordinary text;
|
||||
Even if your toolchain can't handle UTF-8 directly, you can still encode
|
||||
string literals in UTF-8 by using octal or hexadecimal escapes like
|
||||
<literal>\212</literal> or <literal>\xa8</literal> to encode each byte.
|
||||
This is portable, but modifying the escaped strings is not very convenient.
|
||||
Be careful when mixing hexadecimal escapes with ordinary text;
|
||||
<literal>"\xa8abcd"</literal> is a string of length 1 !
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>runtime conversion</term>
|
||||
<listitem><para>
|
||||
If the string literals can be represented in an encoding which your toolchain
|
||||
can handle (e.g. IS0-8859-1), you can write your source files in that encoding
|
||||
and use g_convert() 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.
|
||||
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 g_convert() to convert the strings to UTF-8 at
|
||||
runtime. Note that this has some runtime overhead, so you may want to move
|
||||
the conversion out of inner loops.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
Here is an example showing the three approaches using the copyright sign
|
||||
© which has Unicode and ISO-8859-1 codepoint 169 and is represented in
|
||||
UTF-8 by the two bytes 194, 169:
|
||||
© which has Unicode and ISO-8859-1 codepoint 169 and is represented
|
||||
in UTF-8 by the two bytes 194, 169, or <literal>"\302\251"</literal> as
|
||||
a string literal:
|
||||
<informalexample><programlisting>
|
||||
g_print ("direct UTF-8: ©");
|
||||
g_print ("escaped UTF-8: \302\251");
|
||||
@ -453,14 +458,13 @@ How do I draw text ?
|
||||
|
||||
<answer>
|
||||
<para>
|
||||
To draw a piece of text, use a Pango layout and gdk_draw_layout(),
|
||||
using code like the following:
|
||||
To draw a piece of text, use a Pango layout and gdk_draw_layout().
|
||||
<informalexample>
|
||||
<programlisting>
|
||||
layout = gtk_widget_create_pango_layout (widget, text);
|
||||
fontdesc = pango_font_description_from_string ("Luxi Mono 12");
|
||||
pango_layout_set_font_description (layout, fontdesc);
|
||||
gdk_draw_layout (..., layout);
|
||||
pango_cairo_show_layout (cr, layout);
|
||||
pango_font_description_free (fontdesc);
|
||||
g_object_unref (layout);
|
||||
</programlisting>
|
||||
@ -648,17 +652,14 @@ How do I change the color of a widget?
|
||||
</para></question>
|
||||
|
||||
<answer><para>
|
||||
See gtk_widget_modify_fg(), gtk_widget_modify_bg(), gtk_widget_modify_base(),
|
||||
and gtk_widget_modify_text(). See <link linkend="gtk-Resource-Files">GTK+
|
||||
resource files</link> for more discussion. You can also change widget color
|
||||
by installing a resource file and parsing it with gtk_rc_add_default_file().
|
||||
The advantage of a resource file is that users can then override the
|
||||
color you've chosen.
|
||||
See gtk_widget_override_color() and gtk_widget_override_background_color().
|
||||
You can also change the appearance of a widget by installing a
|
||||
custom style provider, see gtk_style_context_add_provider().
|
||||
</para>
|
||||
|
||||
<para>To change the background color for widgets such as #GtkLabel that have
|
||||
no background, place them in a #GtkEventBox and set the background of the
|
||||
event box.
|
||||
<para>To change the background color for widgets such as #GtkLabel that
|
||||
have no background, place them in a #GtkEventBox and set the background
|
||||
of the event box.
|
||||
</para></answer>
|
||||
</qandaentry>
|
||||
|
||||
@ -669,12 +670,11 @@ How do I change the font of a widget?
|
||||
|
||||
<answer><para>
|
||||
This has several possible answers, depending on what exactly you want to
|
||||
achieve. One option is gtk_widget_modify_font(). Note that this function
|
||||
can be used to change only the font size, as in the following example:
|
||||
achieve. One option is gtk_widget_override_font().
|
||||
<informalexample><programlisting>
|
||||
PangoFontDesc *font_desc = pango_font_description_new (<!-- -->);
|
||||
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);
|
||||
</programlisting></informalexample>
|
||||
</para>
|
||||
@ -691,12 +691,16 @@ constructing such strings on the fly.
|
||||
<para>
|
||||
You can also change the font of a widget by putting
|
||||
<programlisting>
|
||||
gtk-font-name = "Sans 30"
|
||||
.my-widget-class {
|
||||
font: Sans 30;
|
||||
}
|
||||
</programlisting>
|
||||
in 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 font you
|
||||
have chosen. See <link linkend="gtk-Resource-Files">GTK+ resource files</link>
|
||||
for more discussion.
|
||||
in a CSS file, loading it with gtk_css_provider_load_from_file(), and
|
||||
adding the provider with gtk_style_context_add_provider_for_screen().
|
||||
To associate this style information with your widget, set a style class
|
||||
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>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
@ -706,8 +710,9 @@ for more discussion.
|
||||
How do I disable/ghost/desensitize a widget?
|
||||
</para></question>
|
||||
|
||||
<answer><para> In GTK+ a disabled widget is termed "insensitive." See
|
||||
gtk_widget_set_sensitive().
|
||||
<answer><para>
|
||||
In GTK+ a disabled widget is termed "insensitive."
|
||||
See gtk_widget_set_sensitive().
|
||||
</para></answer>
|
||||
</qandaentry>
|
||||
|
||||
@ -746,14 +751,14 @@ How do I make a text widget display its complete contents in a specific font?
|
||||
</para></question>
|
||||
|
||||
<answer><para>
|
||||
If you use gtk_text_buffer_insert_with_tags() 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.
|
||||
If you use gtk_text_buffer_insert_with_tags() with appropriate tags to
|
||||
select the font, the inserted text will have the desired appearance, but
|
||||
text typed in by the user before or after the tagged block will appear in
|
||||
the default style.
|
||||
</para>
|
||||
<para>
|
||||
To ensure that all text has the desired appearance, use gtk_widget_modify_font()
|
||||
to change the default font for the widget.
|
||||
To ensure that all text has the desired appearance, use
|
||||
gtk_widget_override_font() to change the default font for the widget.
|
||||
</para></answer>
|
||||
</qandaentry>
|
||||
|
||||
@ -797,25 +802,10 @@ How do I associate some data with a row in the tree?
|
||||
|
||||
<answer>
|
||||
<para>
|
||||
Remember that the #GtkTreeModel 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 gtk_tree_model_get(). 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().
|
||||
Remember that the #GtkTreeModel 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 gtk_tree_model_get().
|
||||
See the <link linkend="TreeWidget">tree widget overview</link>.
|
||||
</para>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
@ -844,7 +834,7 @@ gtk_list_store_set() and gtk_tree_store_set(), but can't read it back?
|
||||
<answer>
|
||||
<para>
|
||||
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
|
||||
gtk_tree_model_get().
|
||||
</para>
|
||||
@ -857,8 +847,8 @@ How do I change the way that numbers are formatted by #GtkTreeView?
|
||||
</para></question>
|
||||
<answer><para>
|
||||
Use gtk_tree_view_insert_column_with_data_func()
|
||||
or gtk_tree_view_column_set_cell_data_func() and do the conversion from i
|
||||
number to string yourself (with, say, g_strdup_printf()).
|
||||
or gtk_tree_view_column_set_cell_data_func() and do the conversion
|
||||
from number to string yourself (with, say, g_strdup_printf()).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -953,42 +943,15 @@ How do I use cairo to draw in GTK+ applications ?
|
||||
</para></question>
|
||||
|
||||
<answer><para>
|
||||
Use gdk_cairo_create() to obtain a cairo context for drawing
|
||||
on a GDK window or pixmap. See <link linkend="gdk-Cairo-Interaction">Cairo
|
||||
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.
|
||||
The #GtkWidget::draw signal gets a ready-to-use cairo context
|
||||
as parameter that you should use.
|
||||
</para>
|
||||
<para>
|
||||
Possible solutions to this problem are:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
Turn off double-buffering, with gtk_widget_set_double_buffered().
|
||||
This is not ideal, 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>
|
||||
All drawing in GTK+ is normally done in a draw handler, and GTK+
|
||||
creates a temporary pixmap for double-buffering the drawing.
|
||||
It is possible to turn off double-buffering, with
|
||||
gtk_widget_set_double_buffered(), but this is not ideal,
|
||||
since it can cause some flickering.
|
||||
</para>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
@ -996,7 +959,7 @@ itself.
|
||||
<qandaentry>
|
||||
<question><para>
|
||||
Can I improve the performance of my application by using the
|
||||
Glitz backend of cairo ?
|
||||
Glitz or GL backend of cairo ?
|
||||
</para></question>
|
||||
|
||||
<answer><para>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user