question_index.sgml

linux下电话本所依赖的一些图形库

<refentry id="gtk-question-index" revision="1 Jan 2002">
<refmeta>
<refentrytitle>Common Questions</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Common Questions</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Common Questions</refname>
<refpurpose>
Find answers to common questions in the GTK+ manual
</refpurpose>
</refnamediv>

<refsect1>
<title>Questions and Answers</title>

<para>
This is an "index" of the reference manual organized by common "How do
I..." questions. If you aren't sure which documentation to read for
the question you have, this list is a good place to start.
</para>

<qandaset>

<qandadiv><title>General</title>

<qandaentry>
<question><para>
How do I get started with GTK+?
</para></question>

<answer><para>
The GTK+ <ulink url="http://www.gtk.org">website</ulink> offers a 
<ulink url="http://www.gtk.org/tutorial">tutorial</ulink> and a 
<ulink url="http://www.gtk.org/faq">FAQ</ulink>. More documentation ranging
from whitepapers to online books can be found at the
<ulink url="http://developer.gnome.org/doc">GNOME developer's site</ulink>.
After studying these materials you should be well prepared to come back to
this reference manual for details.
</para></answer>
</qandaentry>

<qandaentry>
<question><para>
Where can I get help with GTK+, submit a bug report, or make a feature 
request?
</para></question>

<answer>

<para>
See the <link linkend="gtk-resources">documentation on this topic</link>.
</para>

</answer>

</qandaentry>


<qandaentry>
<question><para>How do I port from one GTK+
version to another?</para></question>

<answer>

<para>
See the <link linkend="gtk-changes-2-0">list of incompatible changes
from 1.2 to 2.0</link>. Also, the <ulink
url="http://developer.gnome.org/dotplan/porting/">GNOME 2.0 porting
guide</ulink> on <ulink
url="http://developer.gnome.org">http://developer.gnome.org</ulink>
has some more detailed discussion of porting from 1.2 to 2.0.
You may also find useful information in the documentation for 
specific widgets and functions.
</para>

<para>
If you have a question not covered in the manual, feel free to
ask on the mailing lists and please <ulink
url="http://bugzilla.gnome.org">file a bug report</ulink> against the
documentation.
</para>

</answer>

</qandaentry>


<qandaentry>
<question><para>
How does memory management work in GTK+? Should I free data returned
from functions?
</para></question>

<answer>

<para>
See the documentation for <link linkend="GObject">GObject</link> and
<link linkend="GtkObject">GtkObject</link>. For <link
linkend="GObject">GObject</link> note specifically <link
linkend="g-object-ref">g_object_ref()</link> and <link
linkend="g-object-unref">g_object_unref()</link>. <link
linkend="GtkObject">GtkObject</link> is a subclass of <link
linkend="GObject">GObject</link> so the same points apply, except that
it has a "floating" state (explained in its documentation).
</para>

<para>
For strings returned from functions, they will be declared "const"
(using <link linkend="G-CONST-RETURN-CAPS">G_CONST_RETURN</link>) if they
should not be freed. Non-const strings should be freed with <link
linkend="g-free">g_free()</link>. Arrays follow the same rule.  (If
you find an exception to the rules, please report a bug to <ulink
url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.)
</para>

</answer>
</qandaentry>

<qandaentry>
<question>
<para>
Why does my program leak memory, if I destroy a widget immediately 
after creating it ?
</para>
</question>

<answer>
<para>
If <structname>GtkFoo</structname> isn't a toplevel window, then
<informalexample><programlisting>
 foo = gtk_foo_new (<!-- -->);
 gtk_widget_destroy (foo);
</programlisting></informalexample>
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.
</para>

<para>
To to get this, you must acquire a reference to the widget and drop the floating 
reference (<quote>ref and sink</quote> in GTK+ parlance) after creating it:
<informalexample><programlisting>
 foo = gtk_foo_new (<!-- -->);
 g_object_ref (foo); 
 gtk_object_sink (GTK_OBJECT (foo));
</programlisting></informalexample>
When you want to get rid of the widget, you must call gtk_widget_destroy()
to break any external connections to the widget before dropping your 
reference:
<informalexample><programlisting>
 gtk_widget_destroy (foo); 
 g_object_unref (foo); 
</programlisting></informalexample>
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 gtk_widget_destroy()
to get rid of the widget.
</para>
</answer>
</qandaentry>

<qandaentry>
<question><para>
How do I use GTK+ with threads?
</para></question>

<answer>

<para>
This is covered in the 
<link linkend="gdk-Threads">GDK threads documentation</link>. 
See also the <link linkend="glib-Threads">GThread</link> documentation for portable
threading primitives.
</para>

</answer>

</qandaentry>

<qandaentry>
<question><para>
How do I internationalize a GTK+ program?
</para></question>

<answer>
<para>
Most people use <ulink url="http://www.gnu.org/software/gettext/">GNU
gettext</ulink>, already required in order to install GLib. On a UNIX
or Linux system with gettext installed, type <literal>info
gettext</literal> to read the documentation.
</para>
<para>
The short checklist on how to use gettext is: call
<function>bindtextdomain()</function> so gettext can find the files
containing your translations, call <function>textdomain()</function>
to set the default translation domain, then call
<function>gettext()</function> to look up each string to be translated
in the default domain. Conventionally, people define macros as
follows for convenience:
<informalexample>
<programlisting>
  #define  _(x)  gettext (x)
  #define N_(x)  x
</programlisting>
</informalexample>
You use <function>N_()</function> (N stands for no-op) to mark 
a string for translation in a context where a function call 
to <function>gettext()</function> is not allowed, such as in 
an array initializer. You eventually have to call
<function>gettext()</function> on the string to actually fetch the
translation.  <function>_()</function> both marks the string for 
translation and actually translates it.
</para>
<para>
Code using these macros ends up looking like this:
<informalexample>
<programlisting>
 #include &lt;libintl.h&gt;

 #define  _(x)  gettext (x)
 #define N_(x)  x

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

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

    label1 = gtk_label_new (_("Another string to translate"));
    label2 = gtk_label_new (_(global_variable));
...
</programlisting>
</informalexample>
</para>
<para>
Libraries using gettext should use <function>dgettext()</function>
instead of <function>gettext()</function>, which allows
them to specify the translation domain each time they 
ask for a translation. Libraries should also avoid calling 
<function>textdomain()</function>, since they'll be specifying 
the domain instead of using the default.
For <function>dgettext()</function> the <function>_()</function> macro
can be defined as:
<informalexample>
<programlisting>
  #define _(x) dgettext ("MyDomain", x)
</programlisting>
</informalexample>
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
How do I use non-ASCII characters in GTK+ programs ?
</para>
</question>

<answer>
<para>
GTK+ uses <ulink url="http://www.unicode.org">Unicode</ulink> (more exactly 
UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a
	      sequence of one to six bytes and has a number of nice
	      properties which make it a good choice for working with Unicode
	      text in C programs:
<itemizedlist>
<listitem><para>
ASCII characters are encoded by their familiar ASCII codepoints.
</para></listitem>
<listitem><para>
ASCII characters never appear as part of any other character.
</para></listitem>
<listitem><para>
The zero byte doesn't occur as part of a character, so that UTF-8 strings can
		    be manipulated with the usual C library functions for
		    handling zero-terminated strings.
</para></listitem>
</itemizedlist>
More information about Unicode and UTF-8 can be found in the 
<ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode FAQ for Unix/Linux</ulink>.
GLib provides functions for converting strings between UTF-8 and other
	      encodings, see 
<link linkend="g-locale-to-utf8">g_locale_to_utf8()</link> and <link
		linkend="g-convert">g_convert()</link>.
</para>
<para>
Text coming from external sources (e.g. files or user input), has to be
	      converted to UTF-8 before being handed over to GTK+. The
	      following example writes the content of a IS0-8859-1 encoded text
	      file to <literal>stdout</literal>:
<informalexample><programlisting>
gchar *text, *utf8_text;
gsize length;
GError *error = NULL;

if (g_file_get_contents (filename, &amp;text, &amp;length, NULL)) 
  {
     utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1", 
                            NULL, NULL, &amp;error);
     if (error != NULL)
       {
         fprintf ("Couldn't convert file &percnt;s to UTF-8\n", filename);
         g_error_free (error);
       }
     else
       g_print (utf8_text);
  }
else 
  fprintf (stderr, "Unable to read file &percnt;s\n", filename);
</programlisting></informalexample>
</para>
<para>
For string literals in the source code, there are several alternatives for
	      handling non-ASCII content:
<variablelist>
<varlistentry><term>direct UTF-8</term>
<listitem><para>
If your editor and compiler are capable of handling UTF-8 encoded sources,
it is very convenient to simply use UTF-8 for string literals, since it allows
you to edit the strings in "wysiwyg". Note that choosing this option may