[gtk-doc-cn] r289 committed - update gobject docs

6 views

Skip to first unread message

gtk-d...@googlecode.com

unread,

Apr 17, 2011, 12:10:57 PM4/17/11

to gtk-d...@googlegroups.com

Revision: 289
Author: yetist
Date: Sun Apr 17 09:09:31 2011
Log: update gobject docs
http://code.google.com/p/gtk-doc-cn/source/detail?r=289

Added:
/trunk/zh_CN/gobject/gobject-docs
/trunk/zh_CN/gobject/gobject-docs/credits.xml
/trunk/zh_CN/gobject/gobject-docs/gobject-docs.sgml
/trunk/zh_CN/gobject/gobject-docs-2.28.5.po
Deleted:
/trunk/zh_CN/gobject/credits.xml
/trunk/zh_CN/gobject/docs-2.28.5/glib-genmarshal.xml
/trunk/zh_CN/gobject/docs-2.28.5/glib-mkenums.xml
/trunk/zh_CN/gobject/docs-2.28.5/gobject-docs.sgml
/trunk/zh_CN/gobject/docs-2.28.5/gobject-query.xml
/trunk/zh_CN/gobject/docs-2.28.5/tut_gobject.xml
/trunk/zh_CN/gobject/docs-2.28.5/tut_gsignal.xml
/trunk/zh_CN/gobject/docs-2.28.5/tut_howto.xml
/trunk/zh_CN/gobject/docs-2.28.5/tut_intro.xml
/trunk/zh_CN/gobject/docs-2.28.5/tut_tools.xml
Modified:
/trunk/zh_CN/gobject/AUTHORS

=======================================
--- /dev/null
+++ /trunk/zh_CN/gobject/gobject-docs/credits.xml Sun Apr 17 09:09:31 2011
@@ -0,0 +1,1 @@
+link ../../../tools/credits.xml
=======================================
--- /dev/null
+++ /trunk/zh_CN/gobject/gobject-docs/gobject-docs.sgml Sun Apr 17 09:09:31
2011
@@ -0,0 +1,160 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+
+<!ENTITY % local.common.attrib "xmlns:xi CDATA
#FIXED 'http://www.w3.org/2003/XInclude'">
+<!ENTITY version SYSTEM "version.xml">
+<!ENTITY credits SYSTEM "credits.xml">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+ <bookinfo>
+ <title>GObject Reference Manual</title>
+ <releaseinfo>
+ for GObject &version;
+ The latest version of this documentation can be found on-line at
+ <ulink role="online-location"
url="http://library.gnome.org/devel/gobject/unstable/">http://library.gnome.org/devel/gobject/unstable/</ulink>.
+ </releaseinfo>
+ &credits;
+ </bookinfo>
+
+ <preface>
+ <title>Introduction</title>
+ <para>
+ Most modern programming languages come with their own native object
+ systems and additional fundamental algorithmic language constructs.
+ Just as GLib serves as an implementation of such fundamental
+ types and algorithms (linked lists, hash tables and so forth), the
+ GLib Object System provides the required implementations of a
+ flexible extensible and intentionally easy to map (into other
+ languages) object-oriented framework for C.
+ The substantial elements that are provided can be summarized as:
+ <itemizedlist>
+ <listitem><para>
+ A generic type system to register arbitrary single-inherited
+ flat and deep derived types as well as interfaces for
+ structured types.
+ It takes care of creation, initialization and memory management
+ of the assorted object and class structures, maintains
+ parent/child relationships and deals with dynamic implementations
+ of such types. That is, their type specific implementations are
+ relocatable/unloadable during runtime.
+ </para></listitem>
+ <listitem><para>
+ A collection of fundamental type implementations, such as integers,
+ doubles, enums and structured types, to name a few.
+ </para></listitem>
+ <listitem><para>
+ A sample fundamental type implementation to base object hierarchies
+ upon - the GObject fundamental type.
+ </para></listitem>
+ <listitem><para>
+ A signal system that allows very flexible user customization of
+ virtual/overridable object methods and can serve as a powerful
+ notification mechanism.
+ </para></listitem>
+ <listitem><para>
+ An extensible parameter/value system, supporting all the provided
+ fundamental types that can be used to generically handle object
+ properties or otherwise parameterized types.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </preface>
+
+ <part label="I">
+ <title>Concepts</title>
+
+ <xi:include href="tut_intro.xml" />
+ <xi:include href="tut_gtype.xml" />
+ <xi:include href="tut_gobject.xml" />
+ <xi:include href="tut_gsignal.xml" />
+ </part>
+ <reference label="II">
+ <title>API Reference</title>
+
+ <xi:include href="xml/gtype.xml" />
+ <xi:include href="xml/gtypeplugin.xml" />
+ <xi:include href="xml/gtypemodule.xml" />
+ <xi:include href="xml/objects.xml" />
+ <xi:include href="xml/enumerations_flags.xml" />
+ <xi:include href="xml/gboxed.xml" />
+ <xi:include href="xml/generic_values.xml" />
+ <xi:include href="xml/param_value_types.xml" />
+ <xi:include href="xml/gparamspec.xml" />
+ <xi:include href="xml/value_collection.xml" />
+ <xi:include href="xml/signals.xml" />
+ <xi:include href="xml/gclosure.xml" />
+ <xi:include href="xml/value_arrays.xml" />
+ <xi:include href="xml/gbinding.xml" />
+ </reference>
+ <reference label="III">
+ <title>Tools Reference</title>
+
+ <xi:include href="glib-mkenums.xml" />
+ <xi:include href="glib-genmarshal.xml" />
+ <xi:include href="gobject-query.xml" />
+ </reference>
+
+ <xi:include href="tut_howto.xml" />
+ <xi:include href="tut_tools.xml" />
+
+ <index id="api-index-full">
+ <title>Index</title>
+ <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-deprecated" role="deprecated">
+ <title>Index of deprecated symbols</title>
+ <xi:include href="xml/api-index-deprecated.xml"><xi:fallback
/></xi:include>
+ </index>
+ <index id="api-index-2-2" role="2.2">
+ <title>Index of new symbols in 2.2</title>
+ <xi:include href="xml/api-index-2.2.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-2-4" role="2.4">
+ <title>Index of new symbols in 2.4</title>
+ <xi:include href="xml/api-index-2.4.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-2-6" role="2.6">
+ <title>Index of new symbols in 2.6</title>
+ <xi:include href="xml/api-index-2.6.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-2-8" role="2.8">
+ <title>Index of new symbols in 2.8</title>
+ <xi:include href="xml/api-index-2.8.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-2-10" role="2.10">
+ <title>Index of new symbols in 2.10</title>
+ <xi:include href="xml/api-index-2.10.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-2-12" role="2.12">
+ <title>Index of new symbols in 2.12</title>
+ <xi:include href="xml/api-index-2.12.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-2-14" role="2.14">
+ <title>Index of new symbols in 2.14</title>
+ <xi:include href="xml/api-index-2.14.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-2-18" role="2.18">
+ <title>Index of new symbols in 2.18</title>
+ <xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-2-22" role="2.22">
+ <title>Index of new symbols in 2.22</title>
+ <xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-2-24" role="2.24">
+ <title>Index of new symbols in 2.24</title>
+ <xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-2-26" role="2.26">
+ <title>Index of new symbols in 2.26</title>
+ <xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-2-28" role="2.28">
+ <title>Index of new symbols in 2.28</title>
+ <xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include>
+ </index>
+
+ <xi:include href="xml/annotation-glossary.xml"><xi:fallback
/></xi:include>
+
+</book>
=======================================
--- /dev/null
+++ /trunk/zh_CN/gobject/gobject-docs-2.28.5.po Sun Apr 17 09:09:31 2011
@@ -0,0 +1,5525 @@
+msgid ""
+msgstr ""
+"Project-Id-Version: gtk+ 3.0.8\n"
+"POT-Creation-Date: 2011-04-17 23:55+0800\n"
+"PO-Revision-Date: 2011-04-17 23:59+0800\n"
+"Last-Translator: yetist <yet...@gmail.com>\n"
+"Language-Team: LANGUAGE <L...@li.org>\n"
+"Language: \n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"X-Poedit-Language: Chinese\n"
+"X-Poedit-Country: CHINA\n"
+"X-Poedit-SourceCharset: utf-8\n"
+
+#. Put one translator per line, in the form of NAME <EMAIL>, YEAR1, YEAR2
+#: glib-genmarshal.xml:0(None) glib-mkenums.xml:0(None)
+#: gobject-docs.sgml:0(None) gobject-query.xml:0(None)
tut_gobject.xml:0(None)
+#: tut_gsignal.xml:0(None) tut_gtype.xml:0(None) tut_howto.xml:0(None)
+#: tut_intro.xml:0(None) tut_tools.xml:0(None)
+msgid "translator-credits"
+msgstr "translator-credits"
+
+#: glib-genmarshal.xml:10(refname) glib-genmarshal.xml:16(command)
+#: glib-genmarshal.xml:4(refentrytitle) glib-mkenums.xml:289(refentrytitle)
+msgid "glib-genmarshal"
+msgstr ""
+
+#: glib-genmarshal.xml:103(title)
+msgid "Marshaller list format"
+msgstr ""
+
+#: glib-genmarshal.xml:104(para)
+msgid ""
+"The marshaller lists are processed line by line, a line can contain a "
+"comment in the form of <placeholder-1/> or a marshaller specification of
the "
+"form <placeholder-2/> (up to 16 <replaceable>PTYPE</replaceable>s may be "
+"present)."
+msgstr ""
+
+#: glib-genmarshal.xml:107(programlisting)
+#, no-wrap
+msgid ""
+"\n"
+"# this is a comment\n"
+msgstr ""
+
+#: glib-genmarshal.xml:11(refpurpose)
+msgid "C code marshaller generation utility for GLib closures"
+msgstr ""
+
+#: glib-genmarshal.xml:111(programlisting)
+#, no-wrap
+msgid ""
+"\n"
+"<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>\n"
+"<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>\n"
+"<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>\n"
+msgstr ""
+
+#: glib-genmarshal.xml:118(para)
+msgid ""
+"The <replaceable>RTYPE</replaceable> part specifies the callback's
return "
+"type and the <replaceable>PTYPE</replaceable>s right to the colon
specify "
+"the callback's parameter list, except for the first and the last
arguments "
+"which are always pointers."
+msgstr ""
+
+#: glib-genmarshal.xml:125(title)
+msgid "Parameter types"
+msgstr ""
+
+#: glib-genmarshal.xml:126(para)
+msgid "Currently, the following types are supported: <placeholder-1/>"
+msgstr ""
+
+#: glib-genmarshal.xml:130(replaceable)
+msgid "VOID"
+msgstr ""
+
+#: glib-genmarshal.xml:131(para)
+msgid ""
+"indicates no return type, or no extra parameters. If <replaceable>VOID</"
+"replaceable> is used as the parameter list, no additional parameters may
be "
+"present."
+msgstr ""
+
+#: glib-genmarshal.xml:139(replaceable)
+msgid "BOOLEAN"
+msgstr ""
+
+#: glib-genmarshal.xml:140(para)
+msgid "for boolean types (gboolean)"
+msgstr ""
+
+#: glib-genmarshal.xml:146(replaceable)
+msgid "CHAR"
+msgstr ""
+
+#: glib-genmarshal.xml:147(para)
+msgid "for signed char types (gchar)"
+msgstr ""
+
+#: glib-genmarshal.xml:153(replaceable)
+msgid "UCHAR"
+msgstr ""
+
+#: glib-genmarshal.xml:154(para)
+msgid "for unsigned char types (guchar)"
+msgstr ""
+
+#: glib-genmarshal.xml:160(replaceable)
+msgid "INT"
+msgstr ""
+
+#: glib-genmarshal.xml:161(para)
+msgid "for signed integer types (gint)"
+msgstr ""
+
+#: glib-genmarshal.xml:167(replaceable)
+msgid "UINT"
+msgstr ""
+
+#: glib-genmarshal.xml:168(para)
+msgid "for unsigned integer types (guint)"
+msgstr ""
+
+#: glib-genmarshal.xml:17(arg) glib-mkenums.xml:17(arg)
+#: gobject-query.xml:18(arg) gobject-query.xml:23(arg)
+msgid "options"
+msgstr ""
+
+#: glib-genmarshal.xml:174(replaceable)
+msgid "LONG"
+msgstr ""
+
+#: glib-genmarshal.xml:175(para)
+msgid "for signed long integer types (glong)"
+msgstr ""
+
+#: glib-genmarshal.xml:18(arg) glib-mkenums.xml:18(arg)
+msgid "files"
+msgstr ""
+
+#: glib-genmarshal.xml:181(replaceable)
+msgid "ULONG"
+msgstr ""
+
+#: glib-genmarshal.xml:182(para)
+msgid "for unsigned long integer types (gulong)"
+msgstr ""
+
+#: glib-genmarshal.xml:188(replaceable)
+msgid "INT64"
+msgstr ""
+
+#: glib-genmarshal.xml:189(para)
+msgid "for signed 64bit integer types (gint64)"
+msgstr ""
+
+#: glib-genmarshal.xml:195(replaceable)
+msgid "UINT64"
+msgstr ""
+
+#: glib-genmarshal.xml:196(para)
+msgid "for unsigned 64bit integer types (guint64)"
+msgstr ""
+
+#: glib-genmarshal.xml:202(replaceable)
+msgid "ENUM"
+msgstr ""
+
+#: glib-genmarshal.xml:203(para)
+msgid "for enumeration types (gint)"
+msgstr ""
+
+#: glib-genmarshal.xml:209(replaceable)
+msgid "FLAGS"
+msgstr ""
+
+#: glib-genmarshal.xml:210(para)
+msgid "for flag enumeration types (guint)"
+msgstr ""
+
+#: glib-genmarshal.xml:216(replaceable)
+msgid "FLOAT"
+msgstr ""
+
+#: glib-genmarshal.xml:217(para)
+msgid "for single-precision float types (gfloat)"
+msgstr ""
+
+#: glib-genmarshal.xml:22(title) glib-mkenums.xml:22(title)
+#: gobject-query.xml:27(title)
+msgid "Description"
+msgstr ""
+
+#: glib-genmarshal.xml:223(replaceable)
+msgid "DOUBLE"
+msgstr ""
+
+#: glib-genmarshal.xml:224(para)
+msgid "for double-precision float types (gdouble)"
+msgstr ""
+
+#: glib-genmarshal.xml:23(para)
+msgid ""
+"<command>glib-genmarshal</command> is a small utility that generates C
code "
+"marshallers for callback functions of the GClosure mechanism in the
GObject "
+"sublibrary of GLib. The marshaller functions have a standard signature,
they "
+"get passed in the invoking closure, an array of value structures holding
the "
+"callback function parameters and a value structure for the return value
of "
+"the callback. The marshaller is then responsible to call the respective
C "
+"code function of the closure with all the parameters on the stack and to "
+"collect its return value."
+msgstr ""
+
+#: glib-genmarshal.xml:230(replaceable)
+msgid "STRING"
+msgstr ""
+
+#: glib-genmarshal.xml:231(para)
+msgid "for string types (gchar*)"
+msgstr ""
+
+#: glib-genmarshal.xml:237(replaceable)
+msgid "BOXED"
+msgstr ""
+
+#: glib-genmarshal.xml:238(para)
+msgid "for boxed (anonymous but reference counted) types (GBoxed*)"
+msgstr ""
+
+#: glib-genmarshal.xml:244(replaceable)
+msgid "PARAM"
+msgstr ""
+
+#: glib-genmarshal.xml:245(para)
+msgid "for GParamSpec or derived types (GParamSpec*)"
+msgstr ""
+
+#: glib-genmarshal.xml:251(replaceable)
+msgid "POINTER"
+msgstr ""
+
+#: glib-genmarshal.xml:252(para)
+msgid "for anonymous pointer types (gpointer)"
+msgstr ""
+
+#: glib-genmarshal.xml:258(replaceable)
+msgid "OBJECT"
+msgstr ""
+
+#: glib-genmarshal.xml:259(para)
+msgid "for GObject or derived types (GObject*)"
+msgstr ""
+
+#: glib-genmarshal.xml:265(replaceable)
+msgid "VARIANT"
+msgstr ""
+
+#: glib-genmarshal.xml:266(para)
+msgid "for GVariant types (GVariant*)"
+msgstr ""
+
+#: glib-genmarshal.xml:272(replaceable)
+msgid "NONE"
+msgstr ""
+
+#: glib-genmarshal.xml:273(para)
+msgid "deprecated alias for <replaceable>VOID</replaceable>"
+msgstr ""
+
+#: glib-genmarshal.xml:279(replaceable)
+msgid "BOOL"
+msgstr ""
+
+#: glib-genmarshal.xml:280(para)
+msgid "deprecated alias for <replaceable>BOOLEAN</replaceable>"
+msgstr ""
+
+#: glib-genmarshal.xml:288(title)
+msgid "Example"
+msgstr ""
+
+#: glib-genmarshal.xml:289(para)
+msgid "To generate marshallers for the following callback functions:"
+msgstr ""
+
+#: glib-genmarshal.xml:292(programlisting)
+#, no-wrap
+msgid ""
+"\n"
+"void foo (gpointer data1,\n"
+" gpointer data2);\n"
+"void bar (gpointer data1,\n"
+" gint param1,\n"
+" gpointer data2);\n"
+"gfloat baz (gpointer data1,\n"
+" gboolean param1,\n"
+" guchar param2,\n"
+" gpointer data2);\n"
+msgstr ""
+
+#: glib-genmarshal.xml:303(para)
+msgid "The marshaller list has to look like this:"
+msgstr ""
+
+#: glib-genmarshal.xml:306(programlisting)
+#, no-wrap
+msgid ""
+"\n"
+"VOID:VOID\n"
+"VOID:INT\n"
+"FLOAT:BOOLEAN,UCHAR\n"
+msgstr ""
+
+#: glib-genmarshal.xml:311(para)
+msgid ""
+"The generated marshallers have the arguments encoded in their function
name. "
+"For this particular list, they are"
+msgstr ""
+
+#: glib-genmarshal.xml:315(programlisting)
+#, no-wrap
+msgid ""
+"\n"
+"g_cclosure_marshal_VOID__VOID(),\n"
+"g_cclosure_marshal_VOID__INT(), \n"
+"g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR().\n"
+msgstr ""
+
+#: glib-genmarshal.xml:320(para)
+msgid ""
+"They can be used directly for GClosures or be passed in as the "
+"GSignalCMarshaller c_marshaller; argument upon creation of signals:"
+msgstr ""
+
+#: glib-genmarshal.xml:324(programlisting)
+#, no-wrap
+msgid ""
+"\n"
+"GClosure *cc_foo, *cc_bar, *cc_baz;\n"
+"\n"
+"cc_foo = g_cclosure_new (NULL, foo, NULL);\n"
+"g_closure_set_marshal (cc_foo, g_cclosure_marshal_VOID__VOID);\n"
+"cc_bar = g_cclosure_new (NULL, bar, NULL);\n"
+"g_closure_set_marshal (cc_bar, g_cclosure_marshal_VOID__INT);\n"
+"cc_baz = g_cclosure_new (NULL, baz, NULL);\n"
+"g_closure_set_marshal (cc_baz,
g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR);\n"
+msgstr ""
+
+#: glib-genmarshal.xml:335(title) glib-mkenums.xml:286(title)
+msgid "See also"
+msgstr ""
+
+#: glib-genmarshal.xml:336(para)
+msgid "<command>glib-mkenums</command>(1)"
+msgstr ""
+
+#: glib-genmarshal.xml:34(title) glib-mkenums.xml:31(title)
+#: gobject-query.xml:34(title)
+msgid "Invocation"
+msgstr ""
+
+#: glib-genmarshal.xml:340(title)
+msgid "Bugs"
+msgstr ""
+
+#: glib-genmarshal.xml:341(para)
+msgid "None known yet."
+msgstr ""
+
+#: glib-genmarshal.xml:345(title)
+msgid "Author"
+msgstr ""
+
+#: glib-genmarshal.xml:346(para)
+msgid ""
+"<command>glib-genmarshal</command> has been written by Tim Janik "
+"<email>ti...@gtk.org</email>."
+msgstr ""
+
+#: glib-genmarshal.xml:349(para)
+msgid "This manual page was provided by Tim Janik
<email>ti...@gtk.org</email>."
+msgstr ""
+
+#: glib-genmarshal.xml:35(para)
+msgid ""
+"<command>glib-genmarshal</command> takes a list of marshallers to
generate "
+"as input. The marshaller list is either read from standard input or from "
+"files passed as additional arguments on the command line."
+msgstr ""
+
+#: glib-genmarshal.xml:40(title) glib-mkenums.xml:38(title)
+#: gobject-query.xml:40(title)
+msgid "Options"
+msgstr ""
+
+#: glib-genmarshal.xml:44(option)
+msgid "--header"
+msgstr ""
+
+#: glib-genmarshal.xml:45(para)
+msgid "Generate header file contents of the marshallers."
+msgstr ""
+
+#: glib-genmarshal.xml:5(manvolnum) glib-mkenums.xml:290(manvolnum)
+#: glib-mkenums.xml:5(manvolnum) gobject-query.xml:5(manvolnum)
+msgid "1"
+msgstr ""
+
+#: glib-genmarshal.xml:51(option)
+msgid "--body"
+msgstr ""
+
+#: glib-genmarshal.xml:52(para)
+msgid "Generate C code file contents of the marshallers."
+msgstr ""
+
+#: glib-genmarshal.xml:58(term)
+msgid "<option>--prefix=string</option>, <option>--prefix string</option>"
+msgstr ""
+
+#: glib-genmarshal.xml:59(para)
+msgid ""
+"Specify marshaller prefix. The default prefix is "
+"<literal>`g_cclosure_marshal'</literal>."
+msgstr ""
+
+#: glib-genmarshal.xml:6(refmiscinfo) glib-mkenums.xml:6(refmiscinfo)
+#: gobject-query.xml:6(refmiscinfo)
+msgid "User Commands"
+msgstr ""
+
+#: glib-genmarshal.xml:65(option)
+msgid "--skip-source"
+msgstr ""
+
+#: glib-genmarshal.xml:66(para)
+msgid "Skip source location remarks in generated comments."
+msgstr ""
+
+#: glib-genmarshal.xml:72(option)
+msgid "--nostdinc"
+msgstr ""
+
+#: glib-genmarshal.xml:73(para)
+msgid ""
+"Do not use the standard marshallers of the GObject library, and skip "
+"<filename>gmarshal.h</filename> include directive in generated header
files."
+msgstr ""
+
+#: glib-genmarshal.xml:80(option)
+msgid "--g-fatal-warnings"
+msgstr ""
+
+#: glib-genmarshal.xml:81(para)
+msgid "Make warnings fatal, that is, exit immediately once a warning
occurs."
+msgstr ""
+
+#: glib-genmarshal.xml:87(term) gobject-query.xml:94(term)
+msgid "<option>-h</option>, <option>--help</option>"
+msgstr ""
+
+#: glib-genmarshal.xml:88(para) glib-mkenums.xml:122(para)
+#: gobject-query.xml:95(para)
+msgid "Print brief help and exit."
+msgstr ""
+
+#: glib-genmarshal.xml:94(term) gobject-query.xml:101(term)
+msgid "<option>-v</option>, <option>--version</option>"
+msgstr ""
+
+#: glib-genmarshal.xml:95(para) glib-mkenums.xml:129(para)
+#: gobject-query.xml:102(para)
+msgid "Print version and exit."
+msgstr ""
+
+#: glib-mkenums.xml:10(refname) glib-mkenums.xml:16(command)
+#: glib-mkenums.xml:4(refentrytitle)
+msgid "glib-mkenums"
+msgstr ""
+
+#: glib-mkenums.xml:104(option)
+msgid "--template"
+msgstr ""
+
+#: glib-mkenums.xml:104(replaceable)
+msgid "file"
+msgstr ""
+
+#: glib-mkenums.xml:105(para)
+msgid ""
+"Read templates from the given file. The templates are enclosed in
specially-"
+"formatted C comments <placeholder-1/> where section may be <literal>file-"
+"header</literal>, <literal>file-production</literal>,
<literal>file-tail</"
+"literal>, <literal>enumeration-production</literal>,
<literal>value-header</"
+"literal>, <literal>value-production</literal>,
<literal>value-tail</literal> "
+"or <literal>comment</literal>."
+msgstr ""
+
+#: glib-mkenums.xml:108(programlisting)
+#, no-wrap
+msgid ""
+"\n"
+"/*** BEGIN section ***/\n"
+"/*** END section ***/\n"
+msgstr ""
+
+#: glib-mkenums.xml:11(refpurpose)
+msgid "C language enum description generation utility"
+msgstr ""
+
+#: glib-mkenums.xml:121(option)
+msgid "--help"
+msgstr ""
+
+#: glib-mkenums.xml:128(option)
+msgid "--version"
+msgstr ""
+
+#: glib-mkenums.xml:137(title)
+msgid "Production text substitutions"
+msgstr ""
+
+#: glib-mkenums.xml:138(para)
+msgid ""
+"Certain keywords enclosed in @ characters will be substituted in the
emitted "
+"text. For the substitution examples of the keywords below, the following "
+"example enum definition is assumed: <placeholder-1/><placeholder-2/>"
+msgstr ""
+
+#: glib-mkenums.xml:142(programlisting)
+#, no-wrap
+msgid ""
+"\n"
+"typedef enum\n"
+"{\n"
+" PREFIX_THE_XVALUE = 1 << 3,\n"
+" PREFIX_ANOTHER_VALUE = 1 << 4\n"
+"} PrefixTheXEnum;\n"
+msgstr ""
+
+#: glib-mkenums.xml:151(term)
+msgid "@EnumName@"
+msgstr ""
+
+#: glib-mkenums.xml:152(para)
+msgid ""
+"The name of the enum currently being processed, enum names are assumed to
be "
+"properly namespaced and to use mixed capitalization to separate words
(e.g. "
+"PrefixTheXEnum)."
+msgstr ""
+
+#: glib-mkenums.xml:160(term)
+msgid "@enum_name@"
+msgstr ""
+
+#: glib-mkenums.xml:161(para)
+msgid ""
+"The enum name with words lowercase and word-separated by underscores
(e.g. "
+"prefix_the_xenum)."
+msgstr ""
+
+#: glib-mkenums.xml:168(term)
+msgid "@ENUMNAME@"
+msgstr ""
+
+#: glib-mkenums.xml:169(para)
+msgid ""
+"The enum name with words uppercase and word-separated by underscores
(e.g. "
+"PREFIX_THE_XENUM)."
+msgstr ""
+
+#: glib-mkenums.xml:176(term)
+msgid "@ENUMSHORT@"
+msgstr ""
+
+#: glib-mkenums.xml:177(para)
+msgid ""
+"The enum name with words uppercase and word-separated by underscores,
prefix "
+"stripped (e.g. THE_XENUM)."
+msgstr ""
+
+#: glib-mkenums.xml:184(term)
+msgid "@VALUENAME@"
+msgstr ""
+
+#: glib-mkenums.xml:185(para)
+msgid ""
+"The enum value name currently being processed with words uppercase and
word-"
+"separated by underscores, this is the assumed literal notation of enum "
+"values in the C sources (e.g. PREFIX_THE_XVALUE)."
+msgstr ""
+
+#: glib-mkenums.xml:194(term)
+msgid "@valuenick@"
+msgstr ""
+
+#: glib-mkenums.xml:195(para)
+msgid ""
+"A nick name for the enum value currently being processed, this is
usually "
+"generated by stripping common prefix words of all the enum values of the "
+"current enum, the words are lowercase and underscores are substituted by
a "
+"minus (e.g. the-xvalue)."
+msgstr ""
+
+#: glib-mkenums.xml:204(term)
+msgid "@valuenum@"
+msgstr ""
+
+#: glib-mkenums.xml:205(para)
+msgid ""
+"The integer value for the enum value currently being processed. This is "
+"calculated by using <command>perl</command> to attempt to evaluate the "
+"expression as it appears in the C source code. If evaluation fails then "
+"<command>glib-mkenums</command> will exit with an error status, but this "
+"only happens if <literal>@valuenum@</literal> appears in your value "
+"production template. (Since: 2.26)"
+msgstr ""
+
+#: glib-mkenums.xml:216(term)
+msgid "@type@"
+msgstr ""
+
+#: glib-mkenums.xml:217(para)
+msgid ""
+"This is substituted either by \"enum\" or \"flags\", depending on
whether "
+"the enum value definitions contained bit-shift operators or not (e.g.
flags)."
+msgstr ""
+
+#: glib-mkenums.xml:224(term)
+msgid "@Type@"
+msgstr ""
+
+#: glib-mkenums.xml:225(para)
+msgid ""
+"The same as <literal>@type@</literal> with the first letter capitalized
(e."
+"g. Flags)."
+msgstr ""
+
+#: glib-mkenums.xml:23(para)
+msgid ""
+"<command>glib-mkenums</command> is a small perl-script utility that
parses C "
+"code to extract enum definitions and produces enum descriptions based on "
+"text templates specified by the user. Most frequently this script is used
to "
+"produce C code that contains enum values as strings so programs can
provide "
+"value name strings for introspection."
+msgstr ""
+
+#: glib-mkenums.xml:231(term)
+msgid "@TYPE@"
+msgstr ""
+
+#: glib-mkenums.xml:232(para)
+msgid ""
+"The same as <literal>@type@</literal> with all letters uppercased (e.g. "
+"FLAGS)."
+msgstr ""
+
+#: glib-mkenums.xml:238(term)
+msgid "@filename@"
+msgstr ""
+
+#: glib-mkenums.xml:239(para)
+msgid "The name of the input file currently being processed (e.g. foo.h)."
+msgstr ""
+
+#: glib-mkenums.xml:245(term)
+msgid "@basename@"
+msgstr ""
+
+#: glib-mkenums.xml:246(para)
+msgid ""
+"The base name of the input file currently being processed (e.g. foo.h). "
+"(Since: 2.22)"
+msgstr ""
+
+#: glib-mkenums.xml:253(title)
+msgid "Trigraph extensions"
+msgstr ""
+
+#: glib-mkenums.xml:254(para)
+msgid ""
+"Some C comments are treated specially in the parsed enum definitions,
such "
+"comments start out with the trigraph sequence <literal>/*<</literal>
and "
+"end with the trigraph sequence <literal>>*/</literal>. Per enum "
+"definition, the options \"skip\" and \"flags\" can be specified, to
indicate "
+"this enum definition to be skipped, or for it to be treated as a flags "
+"definition, or to specify the common prefix to be stripped from all
values "
+"to generate value nicknames, respectively. The \"lowercase_name\" option
can "
+"be used to specify the word separation used in the *_get_type()
function. "
+"For instance, /*< lowercase_name=gnome_vfs_uri_hide_options >*/."
+msgstr ""
+
+#: glib-mkenums.xml:265(para)
+msgid ""
+"Per value definition, the options \"skip\" and \"nick\" are supported.
The "
+"former causes the value to be skipped, and the latter can be used to
specify "
+"the otherwise auto-generated nickname. Examples: <placeholder-1/>"
+msgstr ""
+
+#: glib-mkenums.xml:270(programlisting)
+#, no-wrap
+msgid ""
+"\n"
+"typedef enum /*< skip >*/\n"
+"{\n"
+" PREFIX_FOO\n"
+"} PrefixThisEnumWillBeSkipped;\n"
+"typedef enum /*< flags,prefix=PREFIX >*/\n"
+"{\n"
+" PREFIX_THE_ZEROTH_VALUE,\t/*< skip >*/\n"
+" PREFIX_THE_FIRST_VALUE,\n"
+" PREFIX_THE_SECOND_VALUE,\n"
+" PREFIX_THE_THIRD_VALUE,\t/*< nick=the-last-value >*/\n"
+"} PrefixTheFlagsEnum;\n"
+msgstr ""
+
+#: glib-mkenums.xml:32(para)
+msgid ""
+"<command>glib-mkenums</command> takes a list of valid C code files as
input. "
+"The options specified control the text that is output, certain
substitutions "
+"are performed on the text templates for keywords enclosed in @
characters."
+msgstr ""
+
+#: glib-mkenums.xml:42(option)
+msgid "--fhead"
+msgstr ""
+
+#: glib-mkenums.xml:42(replaceable) glib-mkenums.xml:49(replaceable)
+#: glib-mkenums.xml:57(replaceable) glib-mkenums.xml:65(replaceable)
+#: glib-mkenums.xml:73(replaceable) glib-mkenums.xml:81(replaceable)
+#: glib-mkenums.xml:88(replaceable) glib-mkenums.xml:96(replaceable)
+msgid "text"
+msgstr ""
+
+#: glib-mkenums.xml:43(para)
+msgid ""
+"Put out <replaceable>text</replaceable> prior to processing input files."
+msgstr ""
+
+#: glib-mkenums.xml:49(option)
+msgid "--fprod"
+msgstr ""
+
+#: glib-mkenums.xml:50(para)
+msgid ""
+"Put out <replaceable>text</replaceable> everytime a new input file is
being "
+"processed."
+msgstr ""
+
+#: glib-mkenums.xml:57(option)
+msgid "--ftail"
+msgstr ""
+
+#: glib-mkenums.xml:58(para)
+msgid ""
+"Put out <replaceable>text</replaceable> after all input files have been "
+"processed."
+msgstr ""
+
+#: glib-mkenums.xml:65(option)
+msgid "--eprod"
+msgstr ""
+
+#: glib-mkenums.xml:66(para)
+msgid ""
+"Put out <replaceable>text</replaceable> everytime an enum is encountered
in "
+"the input files."
+msgstr ""
+
+#: glib-mkenums.xml:73(option)
+msgid "--vhead"
+msgstr ""
+
+#: glib-mkenums.xml:74(para)
+msgid ""
+"Put out <replaceable>text</replaceable> before iterating over the set of "
+"values of an enum."
+msgstr ""
+
+#: glib-mkenums.xml:81(option)
+msgid "--vprod"
+msgstr ""
+
+#: glib-mkenums.xml:82(para)
+msgid "Put out <replaceable>text</replaceable> for every value of an enum."
+msgstr ""
+
+#: glib-mkenums.xml:88(option)
+msgid "--vtail"
+msgstr ""
+
+#: glib-mkenums.xml:89(para)
+msgid ""
+"Put out <replaceable>text</replaceable> after iterating over all values
of "
+"an enum."
+msgstr ""
+
+#: glib-mkenums.xml:96(option)
+msgid "--comments"
+msgstr ""
+
+#: glib-mkenums.xml:97(para)
+msgid ""
+"Template for auto-generated comments, the default (for C code
generations) "
+"is <literal>\"/* @comment@ */\"</literal>."
+msgstr ""
+
+#: gobject-docs.sgml:10(title)
+msgid "GObject Reference Manual"
+msgstr "GObject 参考手册"
+
+#: gobject-docs.sgml:100(title)
+msgid "Index"
+msgstr "索引"
+
+#: gobject-docs.sgml:104(title)
+msgid "Index of deprecated symbols"
+msgstr "已过时符号索引"
+
+#: gobject-docs.sgml:108(title)
+msgid "Index of new symbols in 2.2"
+msgstr "2.2版本中的新符号索引"
+
+#: gobject-docs.sgml:11(releaseinfo)
+msgid ""
+"for GObject 2.28.5 The latest version of this documentation can be found
on-"
+"line at <ulink role=\"online-location\"
url=\"http://library.gnome.org/devel/"
+"gobject/unstable/\">http://library.gnome.org/devel/gobject/unstable/</ulink>."
+msgstr ""
+"GObject 当前版本为2.28.5, 最新在线版本请浏览这里<ulink
role=\"online-location"
+"\"
url=\"http://library.gnome.org/devel/gobject/unstable/\">http://library."
+"gnome.org/devel/gobject/unstable/</ulink>."
+
+#: gobject-docs.sgml:112(title)
+msgid "Index of new symbols in 2.4"
+msgstr "2.4版本中的新符号索引"
+
+#: gobject-docs.sgml:116(title)
+msgid "Index of new symbols in 2.6"
+msgstr "2.6版本中的新符号索引"
+
+#: gobject-docs.sgml:120(title)
+msgid "Index of new symbols in 2.8"
+msgstr "2.8版本中的新符号索引"
+
+#: gobject-docs.sgml:124(title)
+msgid "Index of new symbols in 2.10"
+msgstr "2.10版本中的新符号索引"
+
+#: gobject-docs.sgml:128(title)
+msgid "Index of new symbols in 2.12"
+msgstr "2.12版本中的新符号索引"
+
+#: gobject-docs.sgml:132(title)
+msgid "Index of new symbols in 2.14"
+msgstr "2.14版本中的新符号索引"
+
+#: gobject-docs.sgml:136(title)
+msgid "Index of new symbols in 2.18"
+msgstr "2.18版本中的新符号索引"
+
+#: gobject-docs.sgml:140(title)
+msgid "Index of new symbols in 2.22"
+msgstr "2.22版本中的新符号索引"
+
+#: gobject-docs.sgml:144(title)
+msgid "Index of new symbols in 2.24"
+msgstr "2.24版本中的新符号索引"
+
+#: gobject-docs.sgml:148(title)
+msgid "Index of new symbols in 2.26"
+msgstr "2.26版本中的新符号索引"
+
+#: gobject-docs.sgml:152(title)
+msgid "Index of new symbols in 2.28"
+msgstr "2.28版本中的新符号索引"
+
+#: gobject-docs.sgml:19(title)
+msgid "Introduction"
+msgstr ""
+
+#: gobject-docs.sgml:20(para)
+msgid ""
+"Most modern programming languages come with their own native object
systems "
+"and additional fundamental algorithmic language constructs. Just as GLib "
+"serves as an implementation of such fundamental types and algorithms
(linked "
+"lists, hash tables and so forth), the GLib Object System provides the "
+"required implementations of a flexible extensible and intentionally easy
to "
+"map (into other languages) object-oriented framework for C. The
substantial "
+"elements that are provided can be summarized as: <placeholder-1/>"
+msgstr ""
+
+#: gobject-docs.sgml:30(para)
+msgid ""
+"A generic type system to register arbitrary single-inherited flat and
deep "
+"derived types as well as interfaces for structured types. It takes care
of "
+"creation, initialization and memory management of the assorted object
and "
+"class structures, maintains parent/child relationships and deals with "
+"dynamic implementations of such types. That is, their type specific "
+"implementations are relocatable/unloadable during runtime."
+msgstr ""
+
+#: gobject-docs.sgml:40(para)
+msgid ""
+"A collection of fundamental type implementations, such as integers,
doubles, "
+"enums and structured types, to name a few."
+msgstr ""
+
+#: gobject-docs.sgml:44(para)
+msgid ""
+"A sample fundamental type implementation to base object hierarchies upon
- "
+"the GObject fundamental type."
+msgstr ""
+
+#: gobject-docs.sgml:48(para)
+msgid ""
+"A signal system that allows very flexible user customization of virtual/"
+"overridable object methods and can serve as a powerful notification "
+"mechanism."
+msgstr ""
+
+#: gobject-docs.sgml:53(para)
+msgid ""
+"An extensible parameter/value system, supporting all the provided "
+"fundamental types that can be used to generically handle object
properties "
+"or otherwise parameterized types."
+msgstr ""
+
+#: gobject-docs.sgml:63(title)
+msgid "Concepts"
+msgstr ""
+
+#: gobject-docs.sgml:71(title)
+msgid "API Reference"
+msgstr "API 参考"
+
+#: gobject-docs.sgml:89(title)
+msgid "Tools Reference"
+msgstr "工具参考"
+
+#: gobject-query.xml:10(refname) gobject-query.xml:16(command)
+#: gobject-query.xml:21(command) gobject-query.xml:4(refentrytitle)
+msgid "gobject-query"
+msgstr ""
+
+#: gobject-query.xml:11(refpurpose)
+msgid "display a tree of types"
+msgstr ""
+
+#: gobject-query.xml:17(arg) gobject-query.xml:44(option)
+msgid "froots"
+msgstr ""
+
+#: gobject-query.xml:22(arg) gobject-query.xml:51(option)
+msgid "tree"
+msgstr ""
+
+#: gobject-query.xml:28(para)
+msgid ""
+"<command>gobject-query</command> is a small utility that draws a tree of "
+"types."
+msgstr ""
+
+#: gobject-query.xml:35(para)
+msgid ""
+"<command>gobject-query</command> takes a mandatory argument that
specifies "
+"whether it should iterate over the fundamental types or print a type
tree."
+msgstr ""
+
+#: gobject-query.xml:45(para)
+msgid "iterate over fundamental roots"
+msgstr ""
+
+#: gobject-query.xml:52(para)
+msgid "print type tree"
+msgstr ""
+
+#: gobject-query.xml:58(option)
+msgid "-r"
+msgstr ""
+
+#: gobject-query.xml:58(replaceable)
+msgid "type"
+msgstr ""
+
+#: gobject-query.xml:59(para)
+msgid "specify the root type"
+msgstr ""
+
+#: gobject-query.xml:65(option)
+msgid "-n"
+msgstr ""
+
+#: gobject-query.xml:66(para)
***The diff for this file has been truncated for email.***
=======================================
--- /trunk/zh_CN/gobject/credits.xml Sun Apr 10 08:46:13 2011
+++ /dev/null
@@ -1,1 +0,0 @@
-link ../../tools/credits.xml
=======================================
--- /trunk/zh_CN/gobject/docs-2.28.5/glib-genmarshal.xml Sun Apr 10
08:46:13 2011
+++ /dev/null
@@ -1,355 +0,0 @@
-<refentry id="glib-genmarshal" lang="en">
-
-<refmeta>
-<refentrytitle>glib-genmarshal</refentrytitle>
-<manvolnum>1</manvolnum>
-<refmiscinfo class="manual">User Commands</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>glib-genmarshal</refname>
-<refpurpose>C code marshaller generation utility for GLib
closures</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-<cmdsynopsis>
-<command>glib-genmarshal</command>
-<arg choice="opt" rep="repeat">options</arg>
-<arg choice="opt" rep="repeat">files</arg>
-</cmdsynopsis>
-</refsynopsisdiv>
-
-<refsect1><title>Description</title>
-<para><command>glib-genmarshal</command> is a small utility that generates
C code
-marshallers for callback functions of the GClosure mechanism in the GObject
-sublibrary of GLib. The marshaller functions have a standard signature,
-they get passed in the invoking closure, an array of value structures
holding
-the callback function parameters and a value structure for the return value
-of the callback. The marshaller is then responsible to call the respective
C
-code function of the closure with all the parameters on the stack and to
-collect its return value.
-</para>
-</refsect1>
-
-<refsect1><title>Invocation</title>
-<para><command>glib-genmarshal</command> takes a list of marshallers to
generate as
-input. The marshaller list is either read from standard input or from files
-passed as additional arguments on the command line.
-</para>
-
-<refsect2><title>Options</title>
-<variablelist>
-
-<varlistentry>
-<term><option>--header</option></term>
-<listitem><para>
-Generate header file contents of the marshallers.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--body</option></term>
-<listitem><para>
-Generate C code file contents of the marshallers.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--prefix=string</option>, <option>--prefix
string</option></term>
-<listitem><para>
-Specify marshaller prefix. The default prefix is
<literal>`g_cclosure_marshal'</literal>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--skip-source</option></term>
-<listitem><para>
-Skip source location remarks in generated comments.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--nostdinc</option></term>
-<listitem><para>
-Do not use the standard marshallers of the GObject library, and skip
-<filename>gmarshal.h</filename> include directive in generated header
files.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--g-fatal-warnings</option></term>
-<listitem><para>
-Make warnings fatal, that is, exit immediately once a warning occurs.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>-h</option>, <option>--help</option></term>
-<listitem><para>
-Print brief help and exit.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>-v</option>, <option>--version</option></term>
-<listitem><para>
-Print version and exit.
-</para></listitem>
-</varlistentry>
-
-</variablelist>
-</refsect2>
-
-<refsect2><title>Marshaller list format</title>
-<para>
-The marshaller lists are processed line by line, a line can contain a
-comment in the form of
-<programlisting>
-# this is a comment
-</programlisting>
-or a marshaller specification of the form
-<programlisting>
-<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>
-<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
-<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
-</programlisting>
-(up to 16 <replaceable>PTYPE</replaceable>s may be present).
-</para>
-<para>
-The <replaceable>RTYPE</replaceable> part specifies the callback's return
-type and the <replaceable>PTYPE</replaceable>s right to the colon specify
-the callback's parameter list, except for the first and the last arguments
-which are always pointers.
-</para>
-</refsect2>
-<refsect2><title>Parameter types</title>
-<para>
-Currently, the following types are supported:
-<variablelist>
-<varlistentry>
-<term><replaceable>VOID</replaceable></term>
-<listitem><para>
-indicates no return type, or no extra parameters.
-If <replaceable>VOID</replaceable> is used as the parameter list, no
-additional parameters may be present.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>BOOLEAN</replaceable></term>
-<listitem><para>
-for boolean types (gboolean)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>CHAR</replaceable></term>
-<listitem><para>
-for signed char types (gchar)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>UCHAR</replaceable></term>
-<listitem><para>
-for unsigned char types (guchar)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>INT</replaceable></term>
-<listitem><para>
-for signed integer types (gint)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>UINT</replaceable></term>
-<listitem><para>
-for unsigned integer types (guint)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>LONG</replaceable></term>
-<listitem><para>
-for signed long integer types (glong)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>ULONG</replaceable></term>
-<listitem><para>
-for unsigned long integer types (gulong)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>INT64</replaceable></term>
-<listitem><para>
-for signed 64bit integer types (gint64)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>UINT64</replaceable></term>
-<listitem><para>
-for unsigned 64bit integer types (guint64)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>ENUM</replaceable></term>
-<listitem><para>
-for enumeration types (gint)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>FLAGS</replaceable></term>
-<listitem><para>
-for flag enumeration types (guint)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>FLOAT</replaceable></term>
-<listitem><para>
-for single-precision float types (gfloat)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>DOUBLE</replaceable></term>
-<listitem><para>
-for double-precision float types (gdouble)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>STRING</replaceable></term>
-<listitem><para>
-for string types (gchar*)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>BOXED</replaceable></term>
-<listitem><para>
-for boxed (anonymous but reference counted) types (GBoxed*)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>PARAM</replaceable></term>
-<listitem><para>
-for GParamSpec or derived types (GParamSpec*)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>POINTER</replaceable></term>
-<listitem><para>
-for anonymous pointer types (gpointer)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>OBJECT</replaceable></term>
-<listitem><para>
-for GObject or derived types (GObject*)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>VARIANT</replaceable></term>
-<listitem><para>
-for GVariant types (GVariant*)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>NONE</replaceable></term>
-<listitem><para>
-deprecated alias for <replaceable>VOID</replaceable>
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><replaceable>BOOL</replaceable></term>
-<listitem><para>
-deprecated alias for <replaceable>BOOLEAN</replaceable>
-</para></listitem>
-</varlistentry>
-</variablelist>
-</para>
-</refsect2>
-</refsect1>
-<refsect1><title>Example</title>
-<para>
-To generate marshallers for the following callback functions:
-</para>
-<programlisting>
-void foo (gpointer data1,
- gpointer data2);
-void bar (gpointer data1,
- gint param1,
- gpointer data2);
-gfloat baz (gpointer data1,
- gboolean param1,
- guchar param2,
- gpointer data2);
-</programlisting>
-<para>
-The marshaller list has to look like this:
-</para>
-<programlisting>
-VOID:VOID
-VOID:INT
-FLOAT:BOOLEAN,UCHAR
-</programlisting>
-<para>
-The generated marshallers have the arguments encoded in their function
name.
-For this particular list, they are
-</para>
-<programlisting>
-g_cclosure_marshal_VOID__VOID(),
-g_cclosure_marshal_VOID__INT(),
-g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR().
-</programlisting>
-<para>
-They can be used directly for GClosures or be passed in as the
-GSignalCMarshaller c_marshaller; argument upon creation of signals:
-</para>
-<programlisting>
-GClosure *cc_foo, *cc_bar, *cc_baz;
-
-cc_foo = g_cclosure_new (NULL, foo, NULL);
-g_closure_set_marshal (cc_foo, g_cclosure_marshal_VOID__VOID);
-cc_bar = g_cclosure_new (NULL, bar, NULL);
-g_closure_set_marshal (cc_bar, g_cclosure_marshal_VOID__INT);
-cc_baz = g_cclosure_new (NULL, baz, NULL);
-g_closure_set_marshal (cc_baz, g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR);
-</programlisting>
-</refsect1>
-<refsect1><title>See also</title>
-<para>
-<command>glib-mkenums</command>(1)
-</para>
-</refsect1>
-<refsect1><title>Bugs</title>
-<para>
-None known yet.
-</para>
-</refsect1>
-<refsect1><title>Author</title>
-<para><command>glib-genmarshal</command> has been written by Tim Janik
-<email>ti...@gtk.org</email>.
-</para>
-<para>
-This manual page was provided by Tim Janik <email>ti...@gtk.org</email>.
-</para>
-</refsect1>
-</refentry>
-
-
=======================================
--- /trunk/zh_CN/gobject/docs-2.28.5/glib-mkenums.xml Sun Apr 10 08:46:13
2011
+++ /dev/null
@@ -1,296 +0,0 @@
-<refentry id="glib-mkenums" lang="en">
-
-<refmeta>
-<refentrytitle>glib-mkenums</refentrytitle>
-<manvolnum>1</manvolnum>
-<refmiscinfo class="manual">User Commands</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>glib-mkenums</refname>
-<refpurpose>C language enum description generation utility</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-<cmdsynopsis>
-<command>glib-mkenums</command>
-<arg choice="opt" rep="repeat">options</arg>
-<arg choice="opt" rep="repeat">files</arg>
-</cmdsynopsis>
-</refsynopsisdiv>
-
-<refsect1><title>Description</title>
-<para><command>glib-mkenums</command> is a small perl-script utility that
parses C
-code to extract enum definitions and produces enum descriptions based on
text
-templates specified by the user. Most frequently this script is used to
-produce C code that contains enum values as strings so programs can provide
-value name strings for introspection.
-</para>
-</refsect1>
-
-<refsect1><title>Invocation</title>
-<para><command>glib-mkenums</command> takes a list of valid C code files as
-input. The options specified control the text that is output, certain
-substitutions are performed on the text templates for keywords enclosed
-in @ characters.
-</para>
-
-<refsect2><title>Options</title>
-<variablelist>
-
-<varlistentry>
-<term><option>--fhead</option> <replaceable>text</replaceable></term>
-<listitem><para>
-Put out <replaceable>text</replaceable> prior to processing input files.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--fprod</option> <replaceable>text</replaceable></term>
-<listitem><para>
-Put out <replaceable>text</replaceable> everytime a new input file
-is being processed.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--ftail</option> <replaceable>text</replaceable></term>
-<listitem><para>
-Put out <replaceable>text</replaceable> after all input files have been
-processed.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--eprod</option> <replaceable>text</replaceable></term>
-<listitem><para>
-Put out <replaceable>text</replaceable> everytime an enum is encountered
-in the input files.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--vhead</option> <replaceable>text</replaceable></term>
-<listitem><para>
-Put out <replaceable>text</replaceable> before iterating over the set of
-values of an enum.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--vprod</option> <replaceable>text</replaceable></term>
-<listitem><para>
-Put out <replaceable>text</replaceable> for every value of an enum.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--vtail</option> <replaceable>text</replaceable></term>
-<listitem><para>
-Put out <replaceable>text</replaceable> after iterating over all values
-of an enum.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--comments</option> <replaceable>text</replaceable></term>
-<listitem><para>
-Template for auto-generated comments, the default (for C code generations)
is
-<literal>"/* @comment@ */"</literal>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--template</option> <replaceable>file</replaceable></term>
-<listitem><para>
-Read templates from the given file. The templates are enclosed in
-specially-formatted C comments
-<programlisting>
-/*** BEGIN section ***/
-/*** END section ***/
-</programlisting>
-where section may be <literal>file-header</literal>,
-<literal>file-production</literal>, <literal>file-tail</literal>,
-<literal>enumeration-production</literal>, <literal>value-header</literal>,
-<literal>value-production</literal>, <literal>value-tail</literal> or
-<literal>comment</literal>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--help</option></term>
-<listitem><para>
-Print brief help and exit.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--version</option></term>
-<listitem><para>
-Print version and exit.
-</para></listitem>
-</varlistentry>
-
-</variablelist>
-</refsect2>
-
-<refsect2><title>Production text substitutions</title>
-<para>
-Certain keywords enclosed in @ characters will be substituted in the
-emitted text. For the substitution examples of the keywords below,
-the following example enum definition is assumed:
-<programlisting>
-typedef enum
-{
- PREFIX_THE_XVALUE = 1 << 3,
- PREFIX_ANOTHER_VALUE = 1 << 4
-} PrefixTheXEnum;
-</programlisting>
-<variablelist>
-<varlistentry>
-<term>@EnumName@</term>
-<listitem><para>
-The name of the enum currently being processed, enum names are assumed to
be
-properly namespaced and to use mixed capitalization to separate
-words (e.g. PrefixTheXEnum).
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>@enum_name@</term>
-<listitem><para>
-The enum name with words lowercase and word-separated by underscores
-(e.g. prefix_the_xenum).
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>@ENUMNAME@</term>
-<listitem><para>
-The enum name with words uppercase and word-separated by underscores
-(e.g. PREFIX_THE_XENUM).
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>@ENUMSHORT@</term>
-<listitem><para>
-The enum name with words uppercase and word-separated by underscores,
-prefix stripped (e.g. THE_XENUM).
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>@VALUENAME@</term>
-<listitem><para>
-The enum value name currently being processed with words uppercase and
-word-separated by underscores,
-this is the assumed literal notation of enum values in the C sources
-(e.g. PREFIX_THE_XVALUE).
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>@valuenick@</term>
-<listitem><para>
-A nick name for the enum value currently being processed, this is usually
-generated by stripping common prefix words of all the enum values of the
-current enum, the words are lowercase and underscores are substituted by a
-minus (e.g. the-xvalue).
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>@valuenum@</term>
-<listitem><para>
-The integer value for the enum value currently being processed. This is
-calculated by using <command>perl</command> to attempt to evaluate the
-expression as it appears in the C source code. If evaluation fails then
-<command>glib-mkenums</command> will exit with an error status, but this
-only happens if <literal>@valuenum@</literal> appears in your value
-production template. (Since: 2.26)
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>@type@</term>
-<listitem><para>
-This is substituted either by "enum" or "flags", depending on whether the
-enum value definitions contained bit-shift operators or not (e.g. flags).
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>@Type@</term>
-<listitem><para>
-The same as <literal>@type@</literal> with the first letter capitalized
(e.g. Flags).
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>@TYPE@</term>
-<listitem><para>
-The same as <literal>@type@</literal> with all letters uppercased (e.g.
FLAGS).
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>@filename@</term>
-<listitem><para>
-The name of the input file currently being processed (e.g. foo.h).
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>@basename@</term>
-<listitem><para>
-The base name of the input file currently being processed (e.g. foo.h).
(Since: 2.22)
-</para></listitem>
-</varlistentry>
-</variablelist>
-</para>
-</refsect2>
-<refsect2><title>Trigraph extensions</title>
-<para>
-Some C comments are treated specially in the parsed enum definitions,
-such comments start out with the trigraph sequence
<literal>/*<</literal>
-and end with the trigraph sequence <literal>>*/</literal>.
-Per enum definition, the options "skip" and "flags" can be specified, to
-indicate this enum definition to be skipped, or for it to be treated as
-a flags definition, or to specify the common prefix to be stripped from
-all values to generate value nicknames, respectively. The "lowercase_name"
-option can be used to specify the word separation used in the *_get_type()
-function. For instance, /*< lowercase_name=gnome_vfs_uri_hide_options
>*/.
-</para>
-<para>
-Per value definition, the options "skip" and "nick" are supported.
-The former causes the value to be skipped, and the latter can be used to
-specify the otherwise auto-generated nickname.
-Examples:
-<programlisting>
-typedef enum /*< skip >*/
-{
- PREFIX_FOO
-} PrefixThisEnumWillBeSkipped;
-typedef enum /*< flags,prefix=PREFIX >*/
-{
- PREFIX_THE_ZEROTH_VALUE, /*< skip >*/
- PREFIX_THE_FIRST_VALUE,
- PREFIX_THE_SECOND_VALUE,
- PREFIX_THE_THIRD_VALUE, /*< nick=the-last-value >*/
-} PrefixTheFlagsEnum;
-</programlisting>
-</para>
-</refsect2>
-</refsect1>
-<refsect1><title>See also</title>
-<para>
-<citerefentry>
-<refentrytitle>glib-genmarshal</refentrytitle>
-<manvolnum>1</manvolnum>
-</citerefentry>
-</para>
-</refsect1>
-</refentry>
-
-
=======================================
--- /trunk/zh_CN/gobject/docs-2.28.5/gobject-docs.sgml Mon Apr 11 08:57:23
2011
+++ /dev/null
@@ -1,159 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-
-<!ENTITY % local.common.attrib "xmlns:xi CDATA
#FIXED 'http://www.w3.org/2003/XInclude'">
-<!ENTITY version SYSTEM "version.xml">
-<!ENTITY credits SYSTEM "credits.xml">
-]>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
- <bookinfo>
- <title>GObject参考手册</title>
- <releaseinfo>
- 当前版本为 &version; , 最新在线版本请浏览这里
- <ulink role="online-location"
url="http://library.gnome.org/devel/gobject/unstable/">http://library.gnome.org/devel/gobject/unstable/</ulink>.
- </releaseinfo>
- &credits;
- </bookinfo>
-
- <preface>
- <title>Introduction</title>
- <para>
- Most modern programming languages come with their own native object
- systems and additional fundamental algorithmic language constructs.
- Just as GLib serves as an implementation of such fundamental
- types and algorithms (linked lists, hash tables and so forth), the
- GLib Object System provides the required implementations of a
- flexible extensible and intentionally easy to map (into other
- languages) object-oriented framework for C.
- The substantial elements that are provided can be summarized as:
- <itemizedlist>
- <listitem><para>
- A generic type system to register arbitrary single-inherited
- flat and deep derived types as well as interfaces for
- structured types.
- It takes care of creation, initialization and memory management
- of the assorted object and class structures, maintains
- parent/child relationships and deals with dynamic implementations
- of such types. That is, their type specific implementations are
- relocatable/unloadable during runtime.
- </para></listitem>
- <listitem><para>
- A collection of fundamental type implementations, such as integers,
- doubles, enums and structured types, to name a few.
- </para></listitem>
- <listitem><para>
- A sample fundamental type implementation to base object hierarchies
- upon - the GObject fundamental type.
- </para></listitem>
- <listitem><para>
- A signal system that allows very flexible user customization of
- virtual/overridable object methods and can serve as a powerful
- notification mechanism.
- </para></listitem>
- <listitem><para>
- An extensible parameter/value system, supporting all the provided
- fundamental types that can be used to generically handle object
- properties or otherwise parameterized types.
- </para></listitem>
- </itemizedlist>
- </para>
- </preface>
-
- <part label="I">
- <title>Concepts</title>
-
- <xi:include href="tut_intro.xml" />
- <xi:include href="tut_gtype.xml" />
- <xi:include href="tut_gobject.xml" />
- <xi:include href="tut_gsignal.xml" />
- </part>
- <reference label="II">
- <title>API Reference</title>
-
- <xi:include href="xml/gtype.xml" />
- <xi:include href="xml/gtypeplugin.xml" />
- <xi:include href="xml/gtypemodule.xml" />
- <xi:include href="xml/objects.xml" />
- <xi:include href="xml/enumerations_flags.xml" />
- <xi:include href="xml/gboxed.xml" />
- <xi:include href="xml/generic_values.xml" />
- <xi:include href="xml/param_value_types.xml" />
- <xi:include href="xml/gparamspec.xml" />
- <xi:include href="xml/value_collection.xml" />
- <xi:include href="xml/signals.xml" />
- <xi:include href="xml/gclosure.xml" />
- <xi:include href="xml/value_arrays.xml" />
- <xi:include href="xml/gbinding.xml" />
- </reference>
- <reference label="III">
- <title>Tools Reference</title>
-
- <xi:include href="glib-mkenums.xml" />
- <xi:include href="glib-genmarshal.xml" />
- <xi:include href="gobject-query.xml" />
- </reference>
-
- <xi:include href="tut_howto.xml" />
- <xi:include href="tut_tools.xml" />
-
- <index id="api-index-full">
- <title>Index</title>
- <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-deprecated" role="deprecated">
- <title>Index of deprecated symbols</title>
- <xi:include href="xml/api-index-deprecated.xml"><xi:fallback
/></xi:include>
- </index>
- <index id="api-index-2-2" role="2.2">
- <title>Index of new symbols in 2.2</title>
- <xi:include href="xml/api-index-2.2.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-4" role="2.4">
- <title>Index of new symbols in 2.4</title>
- <xi:include href="xml/api-index-2.4.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-6" role="2.6">
- <title>Index of new symbols in 2.6</title>
- <xi:include href="xml/api-index-2.6.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-8" role="2.8">
- <title>Index of new symbols in 2.8</title>
- <xi:include href="xml/api-index-2.8.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-10" role="2.10">
- <title>Index of new symbols in 2.10</title>
- <xi:include href="xml/api-index-2.10.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-12" role="2.12">
- <title>Index of new symbols in 2.12</title>
- <xi:include href="xml/api-index-2.12.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-14" role="2.14">
- <title>Index of new symbols in 2.14</title>
- <xi:include href="xml/api-index-2.14.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-18" role="2.18">
- <title>Index of new symbols in 2.18</title>
- <xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-22" role="2.22">
- <title>Index of new symbols in 2.22</title>
- <xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-24" role="2.24">
- <title>Index of new symbols in 2.24</title>
- <xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-26" role="2.26">
- <title>Index of new symbols in 2.26</title>
- <xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-28" role="2.28">
- <title>Index of new symbols in 2.28</title>
- <xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include>
- </index>
-
- <xi:include href="xml/annotation-glossary.xml"><xi:fallback
/></xi:include>
-
-</book>
=======================================
--- /trunk/zh_CN/gobject/docs-2.28.5/gobject-query.xml Sun Apr 10 08:46:13
2011
+++ /dev/null
@@ -1,112 +0,0 @@
-<refentry id="gobject-query" lang="en">
-
-<refmeta>
-<refentrytitle>gobject-query</refentrytitle>
-<manvolnum>1</manvolnum>
-<refmiscinfo class="manual">User Commands</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>gobject-query</refname>
-<refpurpose>display a tree of types</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-<cmdsynopsis>
-<command>gobject-query</command>
-<arg choice="plain">froots</arg>
-<arg choice="opt" rep="repeat">options</arg>
-</cmdsynopsis>
-<cmdsynopsis>
-<command>gobject-query</command>
-<arg choice="plain">tree</arg>
-<arg choice="opt" rep="repeat">options</arg>
-</cmdsynopsis>
-</refsynopsisdiv>
-
-<refsect1><title>Description</title>
-<para>
-<command>gobject-query</command> is a small utility that draws a tree of
-types.
-</para>
-</refsect1>
-
-<refsect1><title>Invocation</title>
-<para>
-<command>gobject-query</command> takes a mandatory argument that specifies
-whether it should iterate over the fundamental types or print a type tree.
-</para>
-
-<refsect2><title>Options</title>
-<variablelist>
-
-<varlistentry>
-<term><option>froots</option></term>
-<listitem><para>
-iterate over fundamental roots
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>tree</option></term>
-<listitem><para>
-print type tree
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>-r</option> <replaceable>type</replaceable></term>
-<listitem><para>
-specify the root type
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>-n</option></term>
-<listitem><para>
-don't descend type tree
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>-b</option> <replaceable>string</replaceable></term>
-<listitem><para>
-specify indent string
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>-i</option> <replaceable>string</replaceable></term>
-<listitem><para>
-specify incremental indent string
-</para></listitem>
-</varlistentry>
-
-
-<varlistentry>
-<term><option>-s</option> <replaceable>number</replaceable></term>
-<listitem><para>
-specify line spacing
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>-h</option>, <option>--help</option></term>
-<listitem><para>
-Print brief help and exit.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>-v</option>, <option>--version</option></term>
-<listitem><para>
-Print version and exit.
-</para></listitem>
-</varlistentry>
-
-</variablelist>
-</refsect2>
-</refsect1>
-</refentry>
-
-
=======================================
--- /trunk/zh_CN/gobject/docs-2.28.5/tut_gobject.xml Sun Apr 10 08:46:13
2011
+++ /dev/null
@@ -1,748 +0,0 @@
-<?xml version='1.0' encoding="ISO-8859-1"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-]>
-<chapter id="chapter-gobject">
- <title>The GObject base class</title>
-
- <para>
- The two previous chapters discussed the details of GLib's Dynamic Type
System
- and its signal control system. The GObject library also contains an
implementation
- for a base fundamental type named <link
linkend="GObject"><type>GObject</type></link>.
- </para>
-
- <para>
- <link linkend="GObject"><type>GObject</type></link> is a fundamental
classed instantiable type. It implements:
- <itemizedlist>
- <listitem><para>Memory management with reference
counting</para></listitem>
- <listitem><para>Construction/Destruction of
instances</para></listitem>
- <listitem><para>Generic per-object properties with set/get function
pairs</para></listitem>
- <listitem><para>Easy use of signals</para></listitem>
- </itemizedlist>
- All the GNOME libraries which use the GLib type system (like GTK+ and
GStreamer)
- inherit from <link linkend="GObject"><type>GObject</type></link> which
is why it is important to understand
- the details of how it works.
- </para>
-
- <sect1 id="gobject-instantiation">
- <title>Object instantiation</title>
-
- <para>
- The <function><link
linkend="g-object-new">g_object_new</link></function>
- family of functions can be used to instantiate any GType which
inherits
- from the GObject base type. All these functions make sure the class
and
- instance structures have been correctly initialized by GLib's type
system
- and then invoke at one point or another the constructor class method
- which is used to:
- <itemizedlist>
- <listitem><para>
- Allocate and clear memory through <function><link
linkend="g-type-create-instance">g_type_create_instance</link></function>,
- </para></listitem>
- <listitem><para>
- Initialize the object's instance with the construction
properties.
- </para></listitem>
- </itemizedlist>
- Although one can expect all class and instance members (except the
fields
- pointing to the parents) to be set to zero, some consider it good
practice
- to explicitly set them.
- </para>
-
- <para>
- Objects which inherit from GObject are allowed to override this
- constructor class method: they should however chain to their parent
- constructor method before doing so:
-<programlisting>
- GObject *(* constructor) (GType gtype,
- guint n_properties,
- GObjectConstructParam *properties);
-</programlisting>
- </para>
-
- <para>
- The example below shows how <type>MamanBar</type> overrides the
parent's constructor:
-<programlisting>
-#define MAMAN_TYPE_BAR (maman_bar_get_type ())
-#define MAMAN_BAR(obj) (G_TYPE_CHECK_INSTANCE_CAST
((obj), MAMAN_TYPE_BAR, MamanBar))
-#define MAMAN_IS_BAR(obj) (G_TYPE_CHECK_INSTANCE_TYPE
((obj), MAMAN_TYPE_BAR))
-#define MAMAN_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass),
MAMAN_TYPE_BAR, MamanBarClass))
-#define MAMAN_IS_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass),
MAMAN_TYPE_BAR))
-#define MAMAN_BAR_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj),
MAMAN_TYPE_BAR, MamanBarClass))
-
-typedef struct _MamanBar MamanBar;
-typedef struct _MamanBarClass MamanBarClass;
-
-struct _MamanBar
-{
- GObject parent_instance;
-
- /* instance members */
-};
-
-struct _MamanBarClass
-{
- GObjectClass parent_class;
-
- /* class members */
-};
-
-/* will create maman_bar_get_type and set maman_bar_parent_class */
-G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT);
-
-static GObject *
-maman_bar_constructor (GType gtype,
- guint n_properties,
- GObjectConstructParam *properties)
-{
- GObject *obj;
-
- {
- /* Always chain up to the parent constructor */
- obj = G_OBJECT_CLASS (maman_bar_parent_class)->constructor (gtype,
n_properties, properties);
- }
-
- /* update the object state depending on constructor properties */
-
- return obj;
-}
-
-static void
-maman_bar_class_init (MamanBarClass *klass)
-{
- GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
-
- gobject_class->constructor = maman_bar_constructor;
-}
-
-static void
-maman_bar_init (MamanBar *self)
-{
- /* initialize the object */
-}
-
-</programlisting>
- If the user instantiates an object <type>MamanBar</type> with:
-<programlisting>
-MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL);
-</programlisting>
- If this is the first instantiation of such an object, the
- <function>maman_bar_class_init</function> function will be invoked
- after any <function>maman_bar_base_class_init</function> function.
- This will make sure the class structure of this new object is
- correctly initialized. Here,
<function>maman_bar_class_init</function>
- is expected to override the object's class methods and setup the
- class' own methods. In the example above, the constructor method is
- the only overridden method: it is set to
- <function>maman_bar_constructor</function>.
- </para>
-
- <para>
- Once <function><link
linkend="g-object-new">g_object_new</link></function> has obtained a
reference to an initialized
- class structure, it invokes its constructor method to create an
instance of the new
- object. Since it has just been overridden by
<function>maman_bar_class_init</function>
- to <function>maman_bar_constructor</function>, the latter is called
and, because it
- was implemented correctly, it chains up to its parent's constructor.
In
- order to find the parent class and chain up to the parent class
- constructor, we can use the <literal>maman_bar_parent_class</literal>
- pointer that has been set up for us by the
- <literal>G_DEFINE_TYPE</literal> macro.
- </para>
-
- <para>
- Finally, at one point or another,
<function>g_object_constructor</function> is invoked
- by the last constructor in the chain. This function allocates the
object's instance' buffer
- through <function><link
linkend="g-type-create-instance">g_type_create_instance</link></function>
- which means that the instance_init function is invoked at this point
if one
- was registered. After instance_init returns, the object is fully
initialized and should be
- ready to answer any user-request. When <function><link
linkend="g-type-create-instance">g_type_create_instance</link></function>
- returns, <function>g_object_constructor</function> sets the
construction properties
- (i.e. the properties which were given to <function><link
linkend="g-object-new">g_object_new</link></function>) and returns
- to the user's constructor which is then allowed to do useful
instance initialization...
- </para>
-
- <para>
- The process described above might seem a bit complicated, but it can
be
- summarized easily by the table below which lists the functions
invoked
- by <function><link
linkend="g-object-new">g_object_new</link></function>
- and their order of invocation:
- </para>
-
- <para>
- <table id="gobject-construction-table">
- <title><function><link
linkend="g-object-new">g_object_new</link></function></title>
- <tgroup cols="3">
- <colspec colwidth="*" colnum="1" align="left"/>
- <colspec colwidth="*" colnum="2" align="left"/>
- <colspec colwidth="8*" colnum="3" align="left"/>
-
- <thead>
- <row>
- <entry>Invocation time</entry>
- <entry>Function Invoked</entry>
- <entry>Function's parameters</entry>
- <entry>Remark</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry morerows="3">First call to <function><link
linkend="g-object-new">g_object_new</link></function> for target
type</entry>
- <entry>target type's base_init function</entry>
- <entry>On the inheritance tree of classes from fundamental
type to target type.
- base_init is invoked once for each class structure.</entry>
- <entry>
- I have no real idea on how this can be used. If you have a
good real-life
- example of how a class' base_init can be used, please, let
me know.
- </entry>
- </row>
- <row>
- 
- <entry>target type's class_init function</entry>
- <entry>On target type's class structure</entry>
- <entry>
- Here, you should make sure to initialize or override class
methods (that is,
- assign to each class' method its function pointer) and
create the signals and
- the properties associated to your object.
- </entry>
- </row>
- <row>
- 
- <entry>interface' base_init function</entry>
- <entry>On interface' vtable</entry>
- <entry></entry>
- </row>
- <row>
- 
- <entry>interface' interface_init function</entry>
- <entry>On interface' vtable</entry>
- <entry></entry>
- </row>
- <row>
- <entry morerows="1">Each call to <function><link
linkend="g-object-new">g_object_new</link></function> for target
type</entry>
- <entry>target type's class constructor method:
GObjectClass->constructor</entry>
- <entry>On object's instance</entry>
- <entry>
- If you need to complete the object initialization after
all the construction properties
- are set, override the constructor method and make sure to
chain up to the object's
- parent class before doing your own initialization.
- In doubt, do not override the constructor method.
- </entry>
- </row>
- <row>
- 
- <entry>type's instance_init function</entry>
- <entry>On the inheritance tree of classes from fundamental
type to target type.
- the instance_init provided for each type is invoked once for
each instance
- structure.</entry>
- <entry>
- Provide an instance_init function to initialize your
object before its construction
- properties are set. This is the preferred way to
initialize a GObject instance.
- This function is equivalent to C++ constructors.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
-
- <para>
- Readers should feel concerned about one little twist in the order in
- which functions are invoked: while, technically, the class'
constructor
- method is called <emphasis>before</emphasis> the GType's
instance_init
- function (since <function><link
linkend="g-type-create-instance">g_type_create_instance</link></function>
which calls instance_init is called by
- <function>g_object_constructor</function> which is the top-level
class
- constructor method and to which users are expected to chain to), the
- user's code which runs in a user-provided constructor will always
- run <emphasis>after</emphasis> GType's instance_init function since
the
- user-provided constructor <emphasis>must</emphasis> (you've been
warned)
- chain up <emphasis>before</emphasis> doing anything useful.
- </para>
- </sect1>
-
- <sect1 id="gobject-memory">
- <title>Object memory management</title>
-
- <para>
- The memory-management API for GObjects is a bit complicated but the
idea behind it
- is pretty simple: the goal is to provide a flexible model based on
reference counting
- which can be integrated in applications which use or require
different memory management
- models (such as garbage collection, aso...). The methods which are
used to
- manipulate this reference count are described below.
-<programlisting>
-/*
- Refcounting
-*/
-gpointer g_object_ref (gpointer object);
-void g_object_unref (gpointer object);
-
-/*
- * Weak References
- */
-typedef void (*GWeakNotify) (gpointer data,
- GObject *where_the_object_was);
-
-void g_object_weak_ref (GObject *object,
- GWeakNotify notify,
- gpointer data);
-void g_object_weak_unref (GObject *object,
- GWeakNotify notify,
- gpointer data);
-void g_object_add_weak_pointer (GObject *object,
- gpointer *weak_pointer_location);
-void g_object_remove_weak_pointer (GObject *object,
- gpointer *weak_pointer_location);
-/*
- * Cycle handling
- */
-void g_object_run_dispose (GObject *object);
-</programlisting>
- </para>
-
- <sect2 id="gobject-memory-refcount">
- <title>Reference count</title>
-
- <para>
- The functions <function><link
linkend="g-object-ref">g_object_ref</link></function>/<function><link
linkend="g-object-unref">g_object_unref</link></function> respectively
- increase and decrease the reference count.These functions are
thread-safe as of GLib 2.8.
- The reference count is, unsurprisingly, initialized to one by
- <function><link
linkend="g-object-new">g_object_new</link></function> which means that the
caller
- is currently the sole owner of the newly-created reference.
- When the reference count reaches zero, that is,
- when <function><link
linkend="g-object-unref">g_object_unref</link></function> is called by the
last client holding
- a reference to the object, the <emphasis>dispose</emphasis> and the
- <emphasis>finalize</emphasis> class methods are invoked.
- </para>
- <para>
- Finally, after <emphasis>finalize</emphasis> is invoked,
- <function><link
linkend="g-type-free-instance">g_type_free_instance</link></function> is
called to free the object instance.
- Depending on the memory allocation policy decided when the type
was registered (through
- one of the <function>g_type_register_*</function> functions), the
object's instance
- memory will be freed or returned to the object pool for this type.
- Once the object has been freed, if it was the last instance of the
type, the type's class
- will be destroyed as described in <xref
linkend="gtype-instantiable-classed"/> and
- <xref linkend="gtype-non-instantiable-classed"/>.
- </para>
-
- <para>
- The table below summarizes the destruction process of a GObject:
- <table id="gobject-destruction-table">
- <title><function><link
linkend="g-object-unref">g_object_unref</link></function></title>
- <tgroup cols="3">
- <colspec colwidth="*" colnum="1" align="left"/>
- <colspec colwidth="*" colnum="2" align="left"/>
- <colspec colwidth="8*" colnum="3" align="left"/>
-
- <thead>
- <row>
- <entry>Invocation time</entry>
- <entry>Function Invoked</entry>
- <entry>Function's parameters</entry>
- <entry>Remark</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry morerows="1">Last call to <function><link
linkend="g-object-unref">g_object_unref</link></function> for an instance
- of target type
- </entry>
- <entry>target type's dispose class function</entry>
- <entry>GObject instance</entry>
- <entry>
- When dispose ends, the object should not hold any
reference to any other
- member object. The object is also expected to be able to
answer client
- method invocations (with possibly an error code but no
memory violation)
- until finalize is executed. dispose can be executed more
than once.
- dispose should chain up to its parent implementation just
before returning
- to the caller.
- </entry>
- </row>
- <row>
- 
- <entry>target type's finalize class function</entry>
- <entry>GObject instance</entry>
- <entry>
- Finalize is expected to complete the destruction process
initiated by
- dispose. It should complete the object's destruction.
finalize will be
- executed only once.
- finalize should chain up to its parent implementation just
before returning
- to the caller.
- The reason why the destruction process is split is two
different phases is
- explained in <xref linkend="gobject-memory-cycles"/>.
- </entry>
- </row>
- <row>
- <entry morerows="3">Last call to <function><link
linkend="g-object-unref">g_object_unref</link></function> for the last
- instance of target type
- </entry>
- <entry>interface' interface_finalize function</entry>
- <entry>On interface' vtable</entry>
- <entry>Never used in practice. Unlikely you will need
it.</entry>
- </row>
- <row>
- 
- <entry>interface' base_finalize function</entry>
- <entry>On interface' vtable</entry>
- <entry>Never used in practice. Unlikely you will need
it.</entry>
- </row>
- <row>
- 
- <entry>target type's class_finalize function</entry>
- <entry>On target type's class structure</entry>
- <entry>Never used in practice. Unlikely you will need
it.</entry>
- </row>
- <row>
- 
- <entry>type's base_finalize function</entry>
- <entry>On the inheritance tree of classes from fundamental
type to target type.
- base_init is invoked once for each class
structure.</entry>
- <entry>Never used in practice. Unlikely you will need
it.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
-
- </sect2>
-
- <sect2 id="gobject-memory-weakref">
- <title>Weak References</title>
-
- <para>
- Weak References are used to monitor object finalization:
- <function><link
linkend="g-object-weak-ref">g_object_weak_ref</link></function> adds a
monitoring callback which does
- not hold a reference to the object but which is invoked when the
object runs
- its dispose method. As such, each weak ref can be invoked more than
once upon
- object finalization (since dispose can run more than once during
object
- finalization).
- </para>
-
- <para>
- <function><link
linkend="g-object-weak-unref">g_object_weak_unref</link></function> can be
used to remove a monitoring
- callback from the object.
- </para>
-
- <para>
- Weak References are also used to implement <function><link
linkend="g-object-add-weak-pointer">g_object_add_weak_pointer</link></function>
- and <function><link
linkend="g-object-remove-weak-pointer">g_object_remove_weak_pointer</link></function>.
These functions add a weak reference
- to the object they are applied to which makes sure to nullify the
pointer given by the user
- when object is finalized.
- </para>
-
- </sect2>
-
- <sect2 id="gobject-memory-cycles">
- <title>Reference counts and cycles</title>
-
- <para>
- Note: the following section was inspired by James Henstridge. I
guess this means that
- all praise and all curses will be directly forwarded to him.
- </para>
-
- <para>
- GObject's memory management model was designed to be easily
integrated in existing code
- using garbage collection. This is why the destruction process is
split in two phases:
- the first phase, executed in the dispose handler is supposed to
release all references
- to other member objects. The second phase, executed by the
finalize handler is supposed
- to complete the object's destruction process. Object methods
should be able to run
- without program error (that is, without segfault :) in-between the
two phases.
- </para>
-
- <para>
- This two-step destruction process is very useful to break
reference counting cycles.
- While the detection of the cycles is up to the external code, once
the cycles have been
- detected, the external code can invoke <function><link
linkend="g-object-run-dispose">g_object_run_dispose</link></function> which
- will indeed break any existing cycles since it will run the
dispose handler associated
- to the object and thus release all references to other objects.
- </para>
-
- <para>
- Attentive readers might now have understood one of the rules about
the dispose handler
- we stated a bit sooner: the dispose handler can be invoked
multiple times. Let's say we
- have a reference count cycle: object A references B which itself
references object A.
- Let's say we have detected the cycle and we want to destroy the
two objects. One way to
- do this would be to invoke <function><link
linkend="g-object-run-dispose">g_object_run_dispose</link></function> on
one of the
- objects.
- </para>
-
- <para>
- If object A releases all its references to all objects, this means
it releases its
- reference to object B. If object B was not owned by anyone else,
this is its last
- reference count which means this last unref runs B's dispose
handler which, in turn,
- releases B's reference on object A. If this is A's last reference
count, this last
- unref runs A's dispose handler which is running for the second
time before
- A's finalize handler is invoked !
- </para>
-
- <para>
- The above example, which might seem a bit contrived can really
happen if your
- GObject's are being handled by language bindings. I would thus
suggest the rules stated above
- for object destruction are closely followed. Otherwise,
<emphasis>Bad Bad Things</emphasis>
- will happen.
- </para>
- </sect2>
- </sect1>
-
- <sect1 id="gobject-properties">
- <title>Object properties</title>
-
- <para>
- One of GObject's nice features is its generic get/set mechanism for
object
- properties. When an object
- is instantiated, the object's class_init handler should be used to
register
- the object's properties with <function><link
linkend="g-object-class-install-property">g_object_class_install_property</link></function>
- (implemented in <filename>gobject.c</filename>).
- </para>
-
- <para>
- The best way to understand how object properties work is by looking
at a real example
- on how it is used:
-<programlisting>
-/************************************************/
-/* Implementation */
-/************************************************/
-
-enum
-{
- PROP_0,
-
- PROP_MAMAN_NAME,
- PROP_PAPA_NUMBER
-};
-
-static void
-maman_bar_set_property (GObject *object,
- guint property_id,
- const GValue *value,
- GParamSpec *pspec)
-{
- MamanBar *self = MAMAN_BAR (object);
-
- switch (property_id)
- {
- case PROP_MAMAN_NAME:
- g_free (self->priv->name);
- self->priv->name = g_value_dup_string (value);
- g_print ("maman: %s\n", self->priv->name);
- break;
-
- case PROP_PAPA_NUMBER:
- self->priv->papa_number = g_value_get_uchar (value);
- g_print ("papa: &percnt;u\n", self->priv->papa_number);
- break;
-
- default:
- /* We don't have any other property... */
- G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
- break;
- }
-}
-
-static void
-maman_bar_get_property (GObject *object,
- guint property_id,
- GValue *value,
- GParamSpec *pspec)
-{
- MamanBar *self = MAMAN_BAR (object);
-
- switch (property_id)
- {
- case PROP_MAMAN_NAME:
- g_value_set_string (value, self->priv->name);
- break;
-
- case PROP_PAPA_NUMBER:
- g_value_set_uchar (value, self->priv->papa_number);
- break;
-
- default:
- /* We don't have any other property... */
- G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
- break;
- }
-}
-
-static void
-maman_bar_class_init (MamanBarClass *klass)
-{
- GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
- GParamSpec *pspec;
-
- gobject_class->set_property = maman_bar_set_property;
- gobject_class->get_property = maman_bar_get_property;
-
- pspec = g_param_spec_string ("maman-name",
- "Maman construct prop",
- "Set maman's name",
- "no-name-set" /* default value */,
- G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE);
- g_object_class_install_property (gobject_class,
- PROP_MAMAN_NAME,
- pspec);
-
- pspec = g_param_spec_uchar ("papa-number",
- "Number of current Papa",
- "Set/Get papa's number",
- 0 /* minimum value */,
- 10 /* maximum value */,
- 2 /* default value */,
- G_PARAM_READWRITE);
- g_object_class_install_property (gobject_class,
- PROP_PAPA_NUMBER,
- pspec);
-}
-
-/************************************************/
-/* Use */
-/************************************************/
-
-GObject *bar;
-GValue val = { 0, };
-
-bar = g_object_new (MAMAN_TYPE_SUBBAR, NULL);
-
-g_value_init (&val, G_TYPE_CHAR);
-g_value_set_char (&val, 11);
-
-g_object_set_property (G_OBJECT (bar), "papa-number", &val);
-
-g_value_unset (&val);
-</programlisting>
- The client code just above looks simple but a lot of things happen
under the hood:
- </para>
-
- <para>
- <function><link
linkend="g-object-set-property">g_object_set_property</link></function>
first ensures a property
- with this name was registered in bar's class_init handler. If so, it
calls
- <function><link
linkend="object-set-property">object_set_property</link></function> which
first walks the class hierarchy,
- from bottom, most derived type, to top, fundamental type to find the
class
- which registered that property. It then tries to convert the
user-provided GValue
- into a GValue whose type is that of the associated property.
- </para>
-
- <para>
- If the user provides a signed char GValue, as is shown
- here, and if the object's property was registered as an unsigned int,
- <function><link
linkend="g-value-transform">g_value_transform</link></function> will try to
transform the input signed char into
- an unsigned int. Of course, the success of the transformation
depends on the availability
- of the required transform function. In practice, there will almost
always be a transformation
- <footnote>
- <para>Its behaviour might not be what you expect but it is up to
you to actually avoid
- relying on these transformations.
- </para>
- </footnote>
- which matches and conversion will be carried out if needed.
- </para>
-
- <para>
- After transformation, the <link
linkend="GValue"><type>GValue</type></link> is validated by
- <function><link
linkend="g-param-value-validate">g_param_value_validate</link></function>
which makes sure the user's
- data stored in the <link linkend="GValue"><type>GValue</type></link>
matches the characteristics specified by
- the property's <link
linkend="GParamSpec"><type>GParamSpec</type></link>.
- Here, the <link linkend="GParamSpec"><type>GParamSpec</type></link>
we
- provided in class_init has a validation function which makes sure
that the GValue
- contains a value which respects the minimum and maximum bounds of the
- <link linkend="GParamSpec"><type>GParamSpec</type></link>. In the
example above, the client's GValue does not
- respect these constraints (it is set to 11, while the maximum is
10). As such, the
- <function><link
linkend="g-object-set-property">g_object_set_property</link></function>
function will return with an error.
- </para>
-
- <para>
- If the user's GValue had been set to a valid value, <function><link
linkend="g-object-set-property">g_object_set_property</link></function>
- would have proceeded with calling the object's set_property class
method. Here, since our
- implementation of Foo did override this method, the code path would
jump to
- <function>foo_set_property</function> after having retrieved from the
- <link linkend="GParamSpec"><type>GParamSpec</type></link> the
<emphasis>param_id</emphasis>
- <footnote>
- <para>
- It should be noted that the param_id used here need only to
uniquely identify each
- <link linkend="GParamSpec"><type>GParamSpec</type></link> within
the <link linkend="FooClass"><type>FooClass</type></link> such that the
switch
- used in the set and get methods actually works. Of course, this
locally-unique
- integer is purely an optimization: it would have been possible
to use a set of
- <emphasis>if (strcmp (a, b) == 0) {} else if (strcmp (a, b) ==
0) {}</emphasis> statements.
- </para>
- </footnote>
- which had been stored by
- <function><link
linkend="g-object-class-install-property">g_object_class_install_property</link></function>.
- </para>
-
- <para>
- Once the property has been set by the object's set_property class
method, the code path
- returns to <function><link
linkend="g-object-set-property">g_object_set_property</link></function>
which calls
- <function><link
linkend="g-object-notify-queue-thaw">g_object_notify_queue_thaw</link></function>.
This function makes sure that
- the "notify" signal is emitted on the object's instance with the
changed property as
- parameter unless notifications were frozen by <function><link
linkend="g-object-freeze-notify">g_object_freeze_notify</link></function>.
- </para>
-
- <para>
- <function><link
linkend="g-object-thaw-notify">g_object_thaw_notify</link></function> can
be used to re-enable notification of
- property modifications through the "notify" signal. It is important
to remember that
- even if properties are changed while property change notification is
frozen, the "notify"
- signal will be emitted once for each of these changed properties as
soon as the property
- change notification is thawed: no property change is lost for
the "notify" signal. Signal
- can only be delayed by the notification freezing mechanism.
- </para>
-
- <para>
- It sounds like a tedious task to set up GValues every time when one
wants to modify a property.
- In practice one will rarely do this. The functions <function><link
linkend="g-object-set-property">g_object_set_property</link></function>
- and <function><link
linkend="g-object-get-property">g_object_get_property</link></function>
- are meant to be used by language bindings. For application there is
an easier way and
- that is described next.
- </para>
-
- <sect2 id="gobject-multi-properties">
- <title>Accessing multiple properties at once</title>
-
- <para>
- It is interesting to note that the <function><link
linkend="g-object-set">g_object_set</link></function> and
- <function><link
linkend="g-object-set-valist">g_object_set_valist</link></function> (vararg
version) functions can be used to set
- multiple properties at once. The client code shown above can then
be re-written as:
-<programlisting>
-MamanBar *foo;
-foo = /* */;
-g_object_set (G_OBJECT (foo),
- "papa-number", 2,
- "maman-name", "test",
- NULL);
-</programlisting>
- This saves us from managing the GValues that we were needing to
handle when using
- <function><link
linkend="g-object-set-property">g_object_set_property</link></function>.
- The code above will trigger one notify signal emission for each
property modified.
- </para>
-
- <para>
- Of course, the _get versions are also available: <function><link
linkend="g-object-get">g_object_get</link></function>
- and <function><link
linkend="g-object-get-valist">g_object_get_valist</link></function> (vararg
version) can be used to get numerous
- properties at once.
- </para>
-
- <para>
- These high level functions have one drawback - they don't provide
a return result.
- One should pay attention to the argument types and ranges when
using them.
- A known source of errors is to e.g. pass a gfloat instead of a
gdouble and thus
- shifting all subsequent parameters by four bytes. Also forgetting
the terminating
- NULL will lead to unexpected behaviour.
- </para>
-
- <para>
- Really attentive readers now understand how <function><link
linkend="g-object-new">g_object_new</link></function>,
- <function><link
linkend="g-object-newv">g_object_newv</link></function> and <function><link
linkend="g-object-new-valist">g_object_new_valist</link></function>
- work: they parse the user-provided variable number of parameters
and invoke
- <function><link
linkend="g-object-set">g_object_set</link></function> on the parameters
only after the object has been successfully constructed.
- Of course, the "notify" signal will be emitted for each property
set.
- </para>
-
- </sect2>
-
-
-
- </sect1>
-
-</chapter>
=======================================
--- /trunk/zh_CN/gobject/docs-2.28.5/tut_gsignal.xml Sun Apr 10 08:46:13
2011
+++ /dev/null
@@ -1,523 +0,0 @@
-<?xml version='1.0' encoding="ISO-8859-1"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-]>
-<chapter id="chapter-signal">
- <title>The GObject messaging system</title>
-
- <sect1 id="closure">
- <title>Closures</title>
-
- <para>
- Closures are central to the concept of asynchronous signal delivery
- which is widely used throughout GTK+ and GNOME applications. A
closure is an
- abstraction, a generic representation of a callback. It is a small
structure
- which contains three objects:
- <itemizedlist>
- <listitem><para>a function pointer (the callback itself) whose
prototype looks like:
-<programlisting>
-return_type function_callback (... , gpointer user_data);
-</programlisting>
- </para></listitem>
- <listitem><para>
- the user_data pointer which is passed to the callback upon
invocation of the closure
- </para></listitem>
- <listitem><para>
- a function pointer which represents the destructor of the
closure: whenever the
- closure's refcount reaches zero, this function will be called
before the closure
- structure is freed.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- The <link linkend="GClosure"><type>GClosure</type></link> structure
represents the common functionality of all
- closure implementations: there exists a different Closure
implementation for
- each separate runtime which wants to use the GObject type system.
- <footnote><para>
- In practice, closures sit at the boundary of language runtimes: if
you are
- writing Python code and one of your Python callbacks receives a
signal from
- a GTK+ widget, the C code in GTK+ needs to execute your Python
- code. The closure invoked by the GTK+ object invokes the Python
callback:
- it behaves as a normal C object for GTK+ and as a normal Python
object for
- Python code.
- </para></footnote>
- The GObject library provides a simple <link
linkend="GCClosure"><type>GCClosure</type></link> type which
- is a specific implementation of closures to be used with C/C++
callbacks.
- </para>
- <para>
- A <link linkend="GClosure"><type>GClosure</type></link> provides
simple services:
- <itemizedlist>
- <listitem><para>
- Invocation (<function><link
linkend="g-closure-invoke">g_closure_invoke</link></function>): this is
what closures
- were created for: they hide the details of callback invocation
from the
- callback invoker.</para>
- </listitem>
- <listitem><para>
- Notification: the closure notifies listeners of certain events
such as
- closure invocation, closure invalidation and closure
finalization. Listeners
- can be registered with <function><link
linkend="g-closure-add-finalize-notifier">g_closure_add_finalize_notifier</link></function>
- (finalization notification), <function><link
linkend="g-closure-add-invalidate-notifier">g_closure_add_invalidate_notifier</link></function>
- (invalidation notification) and
- <function><link
linkend="g-closure-add-marshal-guards">g_closure_add_marshal_guards</link></function>
(invocation notification).
- There exist symmetric deregistration functions for finalization
and invalidation
- events (<function><link
linkend="g-closure-remove-finalize-notifier">g_closure_remove_finalize_notifier</link></function>
and
- <function><link
linkend="g-closure-remove-invalidate-notifier">g_closure_remove_invalidate_notifier</link></function>)
but not for the invocation
- process.
- <footnote><para>
- Closures are reference counted and notify listeners of their
destruction in a two-stage
- process: the invalidation notifiers are invoked before the
finalization notifiers.
- </para></footnote></para>
- </listitem>
- </itemizedlist>
- </para>
-
- <sect2>
- <title>C Closures</title>
-
- <para>
- If you are using C or C++
- to connect a callback to a given event, you will either use simple
<link linkend="GCClosure"><type>GCClosure</type></link>s
- which have a pretty minimal API or the even simpler
<function><link
linkend="g-signal-connect">g_signal_connect</link></function>
- functions (which will be presented a bit later :).
-<programlisting>
-GClosure *g_cclosure_new (GCallback callback_func,
- gpointer user_data,
- GClosureNotify destroy_data);
-GClosure *g_cclosure_new_swap (GCallback callback_func,
- gpointer user_data,
- GClosureNotify destroy_data);
-GClosure *g_signal_type_cclosure_new (GType itype,
- guint struct_offset);
-</programlisting>
- </para>
-
- <para>
- <function><link
linkend="g-cclosure-new">g_cclosure_new</link></function> will create a new
closure which can invoke the
- user-provided callback_func with the user-provided user_data as
last parameter. When the closure
- is finalized (second stage of the destruction process), it will
invoke the destroy_data function
- if the user has supplied one.
- </para>
-
- <para>
- <function><link
linkend="g-cclosure-new-swap">g_cclosure_new_swap</link></function> will
create a new closure which can invoke the
- user-provided callback_func with the user-provided user_data as
first parameter (instead of being the
- last parameter as with <function><link
linkend="g-cclosure-new">g_cclosure_new</link></function>). When the closure
- is finalized (second stage of the destruction process), it will
invoke the destroy_data
- function if the user has supplied one.
- </para>
- </sect2>
-
- <sect2>
- <title>Non-C closures (for the fearless)</title>
-
- <para>
- As was explained above, closures hide the details of callback
invocation. In C,
- callback invocation is just like function invocation: it is a
matter of creating
- the correct stack frame for the called function and executing a
<emphasis>call</emphasis>
- assembly instruction.
- </para>
-
- <para>
- C closure marshallers transform the array of GValues which
represent
- the parameters to the target function into a C-style function
parameter list, invoke
- the user-supplied C function with this new parameter list, get the
return value of the
- function, transform it into a GValue and return this GValue to the
marshaller caller.
- </para>
-
- <para>
- The following code implements a simple marshaller in C for a C
function which takes an
- integer as first parameter and returns void.
-<programlisting>
-g_cclosure_marshal_VOID__INT (GClosure *closure,
- GValue *return_value,
- guint n_param_values,
- const GValue *param_values,
- gpointer invocation_hint,
- gpointer marshal_data)
-{
- typedef void (*GMarshalFunc_VOID__INT) (gpointer data1,
- gint arg_1,
- gpointer data2);
- register GMarshalFunc_VOID__INT callback;
- register GCClosure *cc = (GCClosure*) closure;
- register gpointer data1, data2;
-
- g_return_if_fail (n_param_values == 2);
-
- data1 = g_value_peek_pointer (param_values + 0);
- data2 = closure->data;
-
- callback = (GMarshalFunc_VOID__INT) (marshal_data ? marshal_data :
cc->callback);
-
- callback (data1,
- g_marshal_value_peek_int (param_values + 1),
- data2);
-}
-</programlisting>
- </para>
-
- <para>
- Of course, there exist other kinds of marshallers. For example,
James Henstridge
- wrote a generic Python marshaller which is used by all Python
closures (a Python closure
- is used to have Python-based callback be invoked by the closure
invocation process).
- This Python marshaller transforms the input GValue list
representing the function
- parameters into a Python tuple which is the equivalent structure
in Python (you can
- look in <function>pyg_closure_marshal</function> in
<filename>pygtype.c</filename>
- in the <emphasis>pygobject</emphasis> module in the GNOME source
code repository).
- </para>
-
- </sect2>
- </sect1>
-
- <sect1 id="signal">
- <title>Signals</title>
-
- <para>
- GObject's signals have nothing to do with standard UNIX signals:
they connect
- arbitrary application-specific events with any number of listeners.
- For example, in GTK+, every user event (keystroke or mouse move) is
received
- from the X server and generates a GTK+ event under the form of a
signal emission
- on a given object instance.
- </para>
-
- <para>
- Each signal is registered in the type system together with the type
on which
- it can be emitted: users of the type are said to
<emphasis>connect</emphasis>
- to the signal on a given type instance when they register a closure
to be
- invoked upon the signal emission. Users can also emit the signal by
themselves
- or stop the emission of the signal from within one of the closures
connected
- to the signal.
- </para>
-
- <para>
- When a signal is emitted on a given type instance, all the closures
- connected to this signal on this type instance will be invoked. All
the closures
- connected to such a signal represent callbacks whose signature looks
like:
-<programlisting>
-return_type function_callback (gpointer instance, ... , gpointer
user_data);
-</programlisting>
- </para>
-
- <sect2 id="signal-registration">
- <title>Signal registration</title>
-
- <para>
- To register a new signal on an existing type, we can use any of
<function><link linkend="g-signal-newv">g_signal_newv</link></function>,
- <function><link
linkend="g-signal-new-valist">g_signal_new_valist</link></function> or
<function><link linkend="g-signal-new">g_signal_new</link></function>
functions:
-<programlisting>
-guint g_signal_newv (const gchar *signal_name,
- GType itype,
- GSignalFlags signal_flags,
- GClosure *class_closure,
- GSignalAccumulator accumulator,
- gpointer accu_data,
- GSignalCMarshaller c_marshaller,
- GType return_type,
- guint n_params,
- GType *param_types);
-</programlisting>
- The number of parameters to these functions is a bit intimidating but
they are relatively
- simple:
- <itemizedlist>
- <listitem><para>
- signal_name: is a string which can be used to uniquely identify a
given signal.
- </para></listitem>
- <listitem><para>
- itype: is the instance type on which this signal can be emitted.
- </para></listitem>
- <listitem><para>
- signal_flags: partly defines the order in which closures which were
connected to the
- signal are invoked.
- </para></listitem>
- <listitem><para>
- class_closure: this is the default closure for the signal: if it is
not NULL upon
- the signal emission, it will be invoked upon this emission of the
signal. The
- moment where this closure is invoked compared to other closures
connected to that
- signal depends partly on the signal_flags.
- </para></listitem>
- <listitem><para>
- accumulator: this is a function pointer which is invoked after each
closure
- has been invoked. If it returns FALSE, signal emission is stopped. If
it returns
- TRUE, signal emission proceeds normally. It is also used to compute
the return
- value of the signal based on the return value of all the invoked
closures.
- </para></listitem>
- <listitem><para>
- accumulator_data: this pointer will be passed down to each invocation
of the
- accumulator during emission.
- </para></listitem>
- <listitem><para>
- c_marshaller: this is the default C marshaller for any closure which
is connected to
- this signal.
- </para></listitem>
- <listitem><para>
- return_type: this is the type of the return value of the signal.
- </para></listitem>
- <listitem><para>
- n_params: this is the number of parameters this signal takes.
- </para></listitem>
- <listitem><para>
- param_types: this is an array of GTypes which indicate the type of
each parameter
- of the signal. The length of this array is indicated by n_params.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- As you can see from the above definition, a signal is basically a
description
- of the closures which can be connected to this signal and a description
of the
- order in which the closures connected to this signal will be invoked.
- </para>
-
- </sect2>
-
- <sect2 id="signal-connection">
- <title>Signal connection</title>
-
- <para>
- If you want to connect to a signal with a closure, you have three
possibilities:
- <itemizedlist>
- <listitem><para>
- You can register a class closure at signal registration: this is a
- system-wide operation. i.e.: the class_closure will be invoked during
each emission
- of a given signal on all the instances of the type which supports that
signal.
- </para></listitem>
- <listitem><para>
- You can use <function><link
linkend="g-signal-override-class-closure">g_signal_override_class_closure</link></function>
which
- overrides the class_closure of a given type. It is possible to call
this function
- only on a derived type of the type on which the signal was registered.
- This function is of use only to language bindings.
- </para></listitem>
- <listitem><para>
- You can register a closure with the <function><link
linkend="g-signal-connect">g_signal_connect</link></function>
- family of functions. This is an instance-specific operation: the
closure
- will be invoked only during emission of a given signal on a given
instance.
- </para></listitem>
- </itemizedlist>
- It is also possible to connect a different kind of callback on a given
signal:
- emission hooks are invoked whenever a given signal is emitted whatever
the instance on
- which it is emitted. Emission hooks are used for example to get all
mouse_clicked
- emissions in an application to be able to emit the small mouse click
sound.
- Emission hooks are connected with <function><link
linkend="g-signal-add-emission-hook">g_signal_add_emission_hook</link></function>
- and removed with <function><link
linkend="g-signal-remove-emission-hook">g_signal_remove_emission_hook</link></function>.
- </para>
-
- </sect2>
-
- <sect2 id="signal-emission">
- <title>Signal emission</title>
-
- <para>
- Signal emission is done through the use of the <function><link
linkend="g-signal-emit">g_signal_emit</link></function> family
- of functions.
-<programlisting>
-void g_signal_emitv (const GValue *instance_and_params,
- guint signal_id,
- GQuark detail,
- GValue *return_value);
-</programlisting>
- <itemizedlist>
- <listitem><para>
- The instance_and_params array of GValues contains the list of input
- parameters to the signal. The first element of the array is the
- instance pointer on which to invoke the signal. The following elements
of
- the array contain the list of parameters to the signal.
- </para></listitem>
- <listitem><para>
- signal_id identifies the signal to invoke.
- </para></listitem>
- <listitem><para>
- detail identifies the specific detail of the signal to invoke. A detail
is a kind of
- magic token/argument which is passed around during signal emission and
which is used
- by closures connected to the signal to filter out unwanted signal
emissions. In most
- cases, you can safely set this value to zero. See <xref
linkend="signal-detail"/> for
- more details about this parameter.
- </para></listitem>
- <listitem><para>
- return_value holds the return value of the last closure invoked during
emission if
- no accumulator was specified. If an accumulator was specified during
signal creation,
- this accumulator is used to calculate the return_value as a function of
the return
- values of all the closures invoked during emission.
- <footnote><para>
- James (again!!) gives a few non-trivial examples of accumulators:
- <quote>
- For instance, you may have an accumulator that ignores NULL returns
from
- closures, and only accumulates the non-NULL ones. Another accumulator
may try
- to return the list of values returned by the closures.
- </quote>
- </para></footnote>
- If no closure is invoked during
- emission, the return_value is nonetheless initialized to zero/null.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- Internally, the GValue array is passed to the emission function proper,
- <function>signal_emit_unlocked_R</function> (implemented in
<filename>gsignal.c</filename>).
- Signal emission can be decomposed in 5 steps:
- <itemizedlist>
- <listitem><para>
- <emphasis>RUN_FIRST</emphasis>: if the G_SIGNAL_RUN_FIRST flag was used
- during signal registration and if there exist a class_closure for this
signal,
- the class_closure is invoked. Jump to
<emphasis>EMISSION_HOOK</emphasis> state.
- </para></listitem>
- <listitem><para>
- <emphasis>EMISSION_HOOK</emphasis>: if any emission hook was added to
- the signal, they are invoked from first to last added. Accumulate
return values
- and jump to <emphasis>HANDLER_RUN_FIRST</emphasis> state.
- </para></listitem>
- <listitem><para>
- <emphasis>HANDLER_RUN_FIRST</emphasis>: if any closure were connected
- with the <function><link
linkend="g-signal-connect">g_signal_connect</link></function> family of
- functions, and if they are not blocked (with the <function><link
linkend="g-signal-handler-block">g_signal_handler_block</link></function>
- family of functions) they are run here, from first to last connected.
- Jump to <emphasis>RUN_LAST</emphasis> state.
- </para></listitem>
- <listitem><para>
- <emphasis>RUN_LAST</emphasis>: if the G_SIGNAL_RUN_LAST
- flag was set during registration and if a class_closure
- was set, it is invoked here. Jump to
- <emphasis>HANDLER_RUN_LAST</emphasis> state.
- </para></listitem>
- <listitem><para>
- <emphasis>HANDLER_RUN_LAST</emphasis>: if any closure were connected
- with the <function>g_signal_connect_after</function> family of
- functions, if they were not invoked during HANDLER_RUN_FIRST and if they
- are not blocked, they are run here, from first to last connected.
- Jump to <emphasis>RUN_CLEANUP</emphasis> state.
- </para></listitem>
- <listitem><para>
- <emphasis>RUN_CLEANUP</emphasis>: if the G_SIGNAL_RUN_CLEANUP flag
- was set during registration and if a class_closure was set,
- it is invoked here. Signal emission is completed here.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- If, at any point during emission (except in RUN_CLEANUP state), one of
the
- closures or emission hook stops the signal emission with
- <function><link linkend="g-signal-stop">g_signal_stop</link></function>,
emission jumps to CLEANUP state.
- </para>
-
- <para>
- If, at any point during emission, one of the closures or emission hook
- emits the same signal on the same instance, emission is restarted from
- the RUN_FIRST state.
- </para>
-
- <para>
- The accumulator function is invoked in all states, after invocation
- of each closure (except in EMISSION_HOOK and CLEANUP). It accumulates
- the closure return value into the signal return value and returns TRUE or
- FALSE. If, at any point, it does not return TRUE, emission jumps to
CLEANUP state.
- </para>
-
- <para>
- If no accumulator function was provided, the value returned by the last
handler
- run will be returned by <function><link
linkend="g-signal-emit">g_signal_emit</link></function>.
- </para>
-
- </sect2>
-
-
- <sect2 id="signal-detail">
- <title>The <emphasis>detail</emphasis> argument</title>
-
- <para>All the functions related to signal emission or signal connection
have a parameter
- named the <emphasis>detail</emphasis>. Sometimes, this parameter is
hidden by the API
- but it is always there, under one form or another.
- </para>
-
- <para>
- Of the three main connection functions,
- only one has an explicit detail parameter as a <link
linkend="GQuark"><type>GQuark</type></link>
- <footnote>
- <para>A GQuark is an integer which uniquely represents a string. It is
possible to transform
- back and forth between the integer and string representations with
the functions
- <function><link
linkend="g-quark-from-string">g_quark_from_string</link></function> and
<function><link
linkend="g-quark-to-string">g_quark_to_string</link></function>.
- </para>
- </footnote>:
-<programlisting>
-gulong g_signal_connect_closure_by_id (gpointer
instance,
- guint signal_id,
- GQuark detail,
- GClosure *closure,
- gboolean after);
-</programlisting>
- The two other functions hide the detail parameter in the signal
name identification:
-<programlisting>
-gulong g_signal_connect_closure (gpointer instance,
- const gchar *detailed_signal,
- GClosure *closure,
- gboolean after);
-gulong g_signal_connect_data (gpointer instance,
- const gchar *detailed_signal,
- GCallback c_handler,
- gpointer data,
- GClosureNotify destroy_data,
- GConnectFlags connect_flags);
-</programlisting>
- Their detailed_signal parameter is a string which identifies the name of
the signal
- to connect to. However, the format of this string is structured to look
like
- <emphasis>signal_name::detail_name</emphasis>. Connecting to the signal
- named <emphasis>notify::cursor_position</emphasis> will actually connect
to the signal
- named <emphasis>notify</emphasis> with the
<emphasis>cursor_position</emphasis> name.
- Internally, the detail string is transformed to a GQuark if it is
present.
- </para>
-
- <para>
- Of the four main signal emission functions, three have an explicit
detail parameter as a
- <link linkend="GQuark"><type>GQuark</type></link> again:
-<programlisting>
-void g_signal_emitv (const GValue
*instance_and_params,
- guint signal_id,
- GQuark detail,
- GValue *return_value);
-void g_signal_emit_valist (gpointer instance,
- guint signal_id,
- GQuark detail,
- va_list var_args);
-void g_signal_emit (gpointer instance,
- guint signal_id,
- GQuark detail,
- ...);
-</programlisting>
- The fourth function hides it in its signal name parameter:
-<programlisting>
-void g_signal_emit_by_name (gpointer instance,
- const gchar *detailed_signal,
- ...);
-</programlisting>
- The format of the detailed_signal parameter is exactly the same as
the format used by
- the <function><link
linkend="g-signal-connect">g_signal_connect</link></function> functions:
<emphasis>signal_name::detail_name</emphasis>.
- </para>
-
- <para>
- If a detail is provided by the user to the emission function, it
is used during emission to match
- against the closures which also provide a detail.
- If the closures' detail does not match the detail provided by the
user, they will not be invoked
- (even though they are connected to a signal which is being
emitted).
- </para>
-
- <para>
- This completely optional filtering mechanism is mainly used as an
optimization for signals
- which are often emitted for many different reasons: the clients can
filter out which events they are
- interested in before the closure's marshalling code runs. For example,
this is used extensively
- by the <emphasis>notify</emphasis> signal of GObject: whenever a
property is modified on a GObject,
- instead of just emitting the <emphasis>notify</emphasis> signal, GObject
associates as a detail to this
- signal emission the name of the property modified. This allows clients
who wish to be notified of changes
- to only one property to filter most events before receiving them.
- </para>
-
- <para>
- As a simple rule, users can and should set the detail parameter to zero:
this will disable completely
- this optional filtering.
- </para>
-
- </sect2>
-
- </sect1>
-</chapter>
-
=======================================
--- /trunk/zh_CN/gobject/docs-2.28.5/tut_howto.xml Sun Apr 10 08:46:13 2011
+++ /dev/null
@@ -1,1720 +0,0 @@
-<?xml version='1.0' encoding="ISO-8859-1"?>
-<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-]>
-<part label="IV">
- <title>Tutorial</title>
- <partintro>
- <para>
- This chapter tries to answer the real-life questions of users and
presents
- the most common scenario use cases I could come up with.
- The use cases are presented from most likely to less likely.
- </para>
- </partintro>
-
-<chapter id="howto-gobject">
- <title>How to define and implement a new GObject</title>
-
- <para>
- Clearly, this is one of the most common questions people ask: they just
- want to crank code and implement a subclass of a GObject. Sometimes
because
- they want to create their own class hierarchy, sometimes because they
want
- to subclass one of GTK+'s widget. This chapter will focus on the
- implementation of a subtype of GObject.
- </para>
-
- <sect1 id="howto-gobject-header">
- <title>Boilerplate header code</title>
-
- <para>
- The first step before writing the code for your GObject is to write
the
- type's header which contains the needed type, function and macro
- definitions. Each of these elements is nothing but a convention which
- is followed not only by GTK+'s code but also by most users of
GObject.
- If you feel the need not to obey the rules stated below, think about
it
- twice:
- <itemizedlist>
- <listitem><para>If your users are a bit accustomed to GTK+ code or
any
- GLib code, they will be a bit surprised and getting used to the
- conventions you decided upon will take time (money) and will make
them
- grumpy (not a good thing)</para></listitem>
- <listitem><para>You must assess the fact that these conventions
might
- have been designed by both smart and experienced people: maybe they
- were at least partly right. Try to put your ego
aside.</para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- Pick a name convention for your headers and source code and stick to
it:
- <itemizedlist>
- <listitem><para>use a dash to separate the prefix from the
typename:
- <filename>maman-bar.h</filename> and
<filename>maman-bar.c</filename>
- (this is the convention used by Nautilus and most GNOME
libraries).</para></listitem>
- <listitem><para>use an underscore to separate the prefix from the
- typename: <filename>maman_bar.h</filename> and
- <filename>maman_bar.c</filename>.</para></listitem>
- <listitem><para>Do not separate the prefix from the typename:
- <filename>mamanbar.h</filename> and
<filename>mamanbar.c</filename>.
- (this is the convention used by GTK+)</para></listitem>
- </itemizedlist>
- Some people like the first two solutions better: it makes reading
file
- names easier for those with poor eyesight.
- </para>
-
- <para>
- When you need some private (internal) declarations in several
- (sub)classes, you can define them in a private header file which
- is often named by appending the <emphasis>private</emphasis> keyword
- to the public header name. For example, one could use
- <filename>maman-bar-private.h</filename>,
- <filename>maman_bar_private.h</filename> or
- <filename>mamanbarprivate.h</filename>. Typically, such private
header
- files are not installed.
- </para>
-
- <para>
- The basic conventions for any header which exposes a GType are
described
- in <xref linkend="gtype-conventions"/>. Most GObject-based code also
- obeys one of of the following conventions: pick one and stick to it.
- <itemizedlist>
- <listitem><para>
- If you want to declare a type named bar with prefix maman,
name the type instance
- <function>MamanBar</function> and its class
<function>MamanBarClass</function>
- (name is case-sensitive). It is customary to declare them with
code similar to the
- following:
-<programlisting>
-/*
- * Copyright/Licensing information.
- */
-
-/* inclusion guard */
-#ifndef __MAMAN_BAR_H__
-#define __MAMAN_BAR_H__
-
-#include <glib-object.h>
-/*
- * Potentially, include other headers on which this header depends.
- */
-
-/*
- * Type macros.
- */
-#define MAMAN_TYPE_BAR (maman_bar_get_type ())
-#define MAMAN_BAR(obj) (G_TYPE_CHECK_INSTANCE_CAST
((obj), MAMAN_TYPE_BAR, MamanBar))
-#define MAMAN_IS_BAR(obj) (G_TYPE_CHECK_INSTANCE_TYPE
((obj), MAMAN_TYPE_BAR))
-#define MAMAN_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass),
MAMAN_TYPE_BAR, MamanBarClass))
-#define MAMAN_IS_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass),
MAMAN_TYPE_BAR))
-#define MAMAN_BAR_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj),
MAMAN_TYPE_BAR, MamanBarClass))
-
-typedef struct _MamanBar MamanBar;
-typedef struct _MamanBarClass MamanBarClass;
-
-struct _MamanBar
-{
- GObject parent_instance;
-
- /* instance members */
-};
-
-struct _MamanBarClass
-{
- GObjectClass parent_class;
-
- /* class members */
-};
-
-/* used by MAMAN_TYPE_BAR */
-GType maman_bar_get_type (void);
-
-/*
- * Method definitions.
- */
-
-#endif /* __MAMAN_BAR_H__ */
-</programlisting>
- </para></listitem>
- <listitem><para>
- Most GTK+ types declare their private fields in the public
header
- with a /* private */ comment, relying on their user's
intelligence
- not to try to play with these fields. Fields not marked private
- are considered public by default. The /* protected */ comment
- (same semantics as those of C++) is also used, mainly in the
GType
- library, in code written by Tim Janik.
-<programlisting>
-struct _MamanBar
-{
- GObject parent_instance;
-
- /*< private >*/
- int hsize;
-};
-</programlisting>
- </para></listitem>
- <listitem><para>
- All of Nautilus code and a lot of GNOME libraries use private
- indirection members, as described by Herb Sutter in his Pimpl
- articles(see <ulink
url="http://www.gotw.ca/gotw/024.htm">Compilation Firewalls</ulink>
- and <ulink url="http://www.gotw.ca/gotw/028.htm">The Fast
Pimpl Idiom</ulink>:
- he summarizes the different issues better than I will).
-<programlisting>
-typedef struct _MamanBarPrivate MamanBarPrivate;
-
-struct _MamanBar
-{
- GObject parent_instance;
-
- /*< private >*/
- MamanBarPrivate *priv;
-};
-</programlisting>
- <note><simpara>Do not call this <varname>private</varname>, as
- that is a registered c++ keyword.</simpara></note>
-
- The private structure is then defined in the .c file, using the
- g_type_class_add_private() function to notify the presence of
- a private memory area for each instance and it can either
- be retrieved using
<function>G_TYPE_INSTANCE_GET_PRIVATE()</function>
- each time is needed, or assigned to the <literal>priv</literal>
- member of the instance structure inside the object's
- <function>init</function> function.
-<programlisting>
-#define MAMAN_BAR_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj),
MAMAN_TYPE_BAR, MamanBarPrivate))
-
-struct _MamanBarPrivate
-{
- int hsize;
-}
-
-static void
-maman_bar_class_init (MamanBarClass *klass)
-{
- g_type_class_add_private (klass, sizeof (MamanBarPrivate));
-}
-
-static void
-maman_bar_init (MamanBar *self)
-{
- MamanBarPrivate *priv;
-
- self->priv = priv = MAMAN_BAR_GET_PRIVATE (self);
-
- priv->hsize = 42;
-}
-</programlisting>
- </para></listitem>
-
- <listitem><para>
- You don't need to free or allocate the private structure, only
the
- objects or pointers that it may contain. Another advantage of
this
- to the previous version is that is lessens memory
fragmentation,
- as the public and private parts of the instance memory are
- allocated at once.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- Finally, there are different header include conventions. Again, pick
one
- and stick to it. I personally use indifferently any of the two,
depending
- on the codebase I work on: the rule, as always, is consistency.
- <itemizedlist>
- <listitem><para>
- Some people add at the top of their headers a number of
#include
- directives to pull in all the headers needed to compile client
- code. This allows client code to simply #include "maman-bar.h".
- </para></listitem>
- <listitem><para>
- Other do not #include anything and expect the client to
#include
- themselves the headers they need before including your header.
This
- speeds up compilation because it minimizes the amount of
- pre-processor work. This can be used in conjunction with the
- re-declaration of certain unused types in the client code to
- minimize compile-time dependencies and thus speed up
compilation.
- </para></listitem>
- </itemizedlist>
- </para>
-
- </sect1>
-
- <sect1 id="howto-gobject-code">
- <title>Boilerplate code</title>
-
- <para>
- In your code, the first step is to #include the needed headers:
depending
- on your header include strategy, this can be as simple as
- <literal>#include "maman-bar.h"</literal> or as complicated as tens
- of #include lines ending with
<literal>#include "maman-bar.h"</literal>:
-<programlisting>
-/*
- * Copyright information
- */
-
-#include "maman-bar.h"
-
-/* If you use Pimpls, include the private structure
- * definition here. Some people create a maman-bar-private.h header
- * which is included by the maman-bar.c file and which contains the
- * definition for this private structure.
- */
-struct _MamanBarPrivate {
- int member_1;
- /* stuff */
-};
-
-/*
- * forward definitions
- */
-</programlisting>
- </para>
-
- <para>
- Call the <function>G_DEFINE_TYPE</function> macro using the name
- of the type, the prefix of the functions and the parent GType to
- reduce the amount of boilerplate needed. This macro will:
-
- <itemizedlist>
- <listitem><simpara>implement the
<function>maman_bar_get_type</function>
- function</simpara></listitem>
- <listitem><simpara>define a parent class pointer accessible from
- the whole .c file</simpara></listitem>
- </itemizedlist>
-
-<programlisting>
-G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT);
-</programlisting>
- </para>
-
- <para>
- It is also possible to use the
- <function>G_DEFINE_TYPE_WITH_CODE</function> macro to control the
- get_type function implementation - for instance, to add a call to
- <function>G_IMPLEMENT_INTERFACE</function> macro which will
- call the <function>g_type_implement_interface</function> function.
- </para>
- </sect1>
-
- <sect1 id="howto-gobject-construction">
- <title>Object Construction</title>
-
- <para>
- People often get confused when trying to construct their GObjects
because of the
- sheer number of different ways to hook into the objects's
construction process: it is
- difficult to figure which is the <emphasis>correct</emphasis>,
recommended way.
- </para>
-
- <para>
- <xref linkend="gobject-construction-table"/> shows what
user-provided functions
- are invoked during object instantiation and in which order they are
invoked.
- A user looking for the equivalent of the simple C++ constructor
function should use
- the instance_init method. It will be invoked after all the parent's
instance_init
- functions have been invoked. It cannot take arbitrary construction
parameters
- (as in C++) but if your object needs arbitrary parameters to
complete initialization,
- you can use construction properties.
- </para>
-
- <para>
- Construction properties will be set only after all instance_init
functions have run.
- No object reference will be returned to the client of
<function><link linkend="g-object-new">g_object_new</link></function>
- until all the construction properties have been set.
- </para>
-
- <para>
- As such, I would recommend writing the following code first:
-<programlisting>
-static void
-maman_bar_init (MamanBar *self)
-{
- self->priv = MAMAN_BAR_GET_PRIVATE (self);
-
- /* initialize all public and private members to reasonable default
values. */
-
- /* If you need specific construction properties to complete
initialization,
- * delay initialization completion until the property is set.
- */
-}
-</programlisting>
- </para>
-
- <para>
- Now, if you need special construction properties, install the
properties in the class_init function,
- override the set and get methods and implement the get and set
methods as described in
- <xref linkend="gobject-properties"/>. Make sure that these
properties use a construct only
- <link linkend="GParamSpec"><type>GParamSpec</type></link> by setting
the param spec's flag field to G_PARAM_CONSTRUCT_ONLY: this helps
- GType ensure that these properties are not set again later by
malicious user code.
-<programlisting>
-static void
-bar_class_init (MamanBarClass *klass)
-{
- GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
- GParamSpec *pspec;
-
- gobject_class->set_property = bar_set_property;
- gobject_class->get_property = bar_get_property;
-
- pspec = g_param_spec_string ("maman",
- "Maman construct prop",
- "Set maman's name",
- "no-name-set" /* default value
*/,
- G_PARAM_CONSTRUCT_ONLY |
G_PARAM_READWRITE);
- g_object_class_install_property (gobject_class,
- PROP_MAMAN,
- pspec);
-}
-</programlisting>
- If you need this, make sure you can build and run code similar to
the code shown above. Make sure
- your construct properties can set correctly during construction,
make sure you cannot set them
- afterwards and make sure that if your users do not call
<function><link linkend="g-object-new">g_object_new</link></function>
- with the required construction properties, these will be initialized
with the default values.
- </para>
-
- <para>
- I consider good taste to halt program execution if a construction
property is set its
- default value. This allows you to catch client code which does not
give a reasonable
- value to the construction properties. Of course, you are free to
disagree but you
- should have a good reason to do so.
- </para>
-
- <para>
- Some people sometimes need to construct their object but only after
- the construction properties have been set. This is possible through
- the use of the constructor class method as described in
- <xref linkend="gobject-instantiation"/> or, more simply, using
- the constructed class method available since GLib 2.12.
- </para>
- </sect1>
-
- <sect1 id="howto-gobject-destruction">
- <title>Object Destruction</title>
-
- <para>
- Again, it is often difficult to figure out which mechanism to use to
- hook into the object's destruction process: when the last
- <function><link
linkend="g-object-unref">g_object_unref</link></function>
- function call is made, a lot of things happen as described in
- <xref linkend="gobject-destruction-table"/>.
- </para>
-
- <para>
- The destruction process of your object might be split in two
different
- phases: dispose and the finalize.
-<programlisting>
-#define MAMAN_BAR_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj),
MAMAN_TYPE_BAR, MamanBarPrivate))
-
-struct _MamanBarPrivate
-{
- GObject *an_object;
-
- gchar *a_string;
-};
-
-G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT);
-
-static void
-maman_bar_dispose (GObject *gobject)
-{
- MamanBar *self = MAMAN_BAR (gobject);
-
- /*
- * In dispose, you are supposed to free all types referenced from this
- * object which might themselves hold a reference to self. Generally,
- * the most simple solution is to unref all members on which you own a
- * reference.
- */
-
- /* dispose might be called multiple times, so we must guard against
- * calling g_object_unref() on an invalid GObject.
- */
- if (self->priv->an_object)
- {
- g_object_unref (self->priv->an_object);
-
- self->priv->an_object = NULL;
- }
-
- /* Chain up to the parent class */
- G_OBJECT_CLASS (maman_bar_parent_class)->dispose (gobject);
-}
-
-static void
-maman_bar_finalize (GObject *gobject)
-{
- MamanBar *self = MAMAN_BAR (gobject);
-
- g_free (self->priv->a_string);
-
- /* Chain up to the parent class */
- G_OBJECT_CLASS (maman_bar_parent_class)->finalize (gobject);
-}
-
-static void
-maman_bar_class_init (MamanBarClass *klass)
-{
- GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
-
- gobject_class->dispose = maman_bar_dispose;
- gobject_class->finalize = maman_bar_finalize;
-
- g_type_class_add_private (klass, sizeof (MamanBarPrivate));
-}
-
-static void
-maman_bar_init (MamanBar *self);
-{
- self->priv = MAMAN_BAR_GET_PRIVATE (self);
-
- self->priv->an_object = g_object_new (MAMAN_TYPE_BAZ, NULL);
- self->priv->a_string = g_strdup ("Maman");
-}
-</programlisting>
- </para>
-
- <para>
- Add similar code to your GObject, make sure the code still builds
- and runs: dispose and finalize must be called during the last unref.
- </para>
-
- <para>
- It is possible that object methods might be invoked after dispose is
- run and before finalize runs. GObject does not consider this to be a
- program error: you must gracefully detect this and neither crash nor
- warn the user.
- </para>
- </sect1>
-
- <sect1 id="howto-gobject-methods">
- <title>Object methods</title>
-
- <para>
- Just as with C++, there are many different ways to define object
- methods and extend them: the following list and sections draw on
- C++ vocabulary. (Readers are expected to know basic C++ buzzwords.
- Those who have not had to write C++ code recently can refer to e.g.
- <ulink url="http://www.cplusplus.com/doc/tutorial/"/> to refresh
- their memories.)
- <itemizedlist>
- <listitem><para>
- non-virtual public methods,
- </para></listitem>
- <listitem><para>
- virtual public methods and
- </para></listitem>
- <listitem><para>
- virtual private methods
- </para></listitem>
- </itemizedlist>
- </para>
-
- <sect2>
- <title>Non-virtual public methods</title>
-
- <para>
- These are the simplest: you want to provide a simple method which
- can act on your object. All you need to do is to provide a function
- prototype in the header and an implementation of that prototype
- in the source file.
-<programlisting>
-/* declaration in the header. */
-void maman_bar_do_action (MamanBar *self, /* parameters */);
-
-/* implementation in the source file */
-void
-maman_bar_do_action (MamanBar *self, /* parameters */)
-{
- g_return_if_fail (MAMAN_IS_BAR (self));
-
- /* do stuff here. */
-}
-</programlisting>
- </para>
-
- <para>There is really nothing scary about this.</para>
- </sect2>
-
- <sect2>
- <title>Virtual public methods</title>
-
- <para>
- This is the preferred way to create polymorphic GObjects. All you
- need to do is to define the common method and its class function in
- the public header, implement the common method in the source file
- and re-implement the class function in each object which inherits
- from you.
-<programlisting>
-/* declaration in maman-bar.h. */
-struct _MamanBarClass
-{
- GObjectClass parent_class;
-
- /* stuff */
- void (*do_action) (MamanBar *self, /* parameters */);
-};
-
-void maman_bar_do_action (MamanBar *self, /* parameters */);
-
-/* implementation in maman-bar.c */
-void
-maman_bar_do_action (MamanBar *self, /* parameters */)
-{
- g_return_if_fail (MAMAN_IS_BAR (self));
-
- MAMAN_BAR_GET_CLASS (self)->do_action (self, /* parameters */);
-}
-</programlisting>
- The code above simply redirects the do_action call to the relevant
- class function. Some users, concerned about performance, do not
- provide the <function>maman_bar_do_action</function> wrapper
function
- and require users to dereference the class pointer themselves. This
- is not such a great idea in terms of encapsulation and makes it
- difficult to change the object's implementation afterwards, should
- this be needed.
- </para>
-
- <para>
- Other users, also concerned by performance issues, declare
- the <function>maman_bar_do_action</function> function inline in the
- header file. This, however, makes it difficult to change the
- object's implementation later (although easier than requiring users
- to directly dereference the class function) and is often difficult
- to write in a portable way (the <emphasis>inline</emphasis> keyword
- is part of the C99 standard but not every compiler supports it).
- </para>
-
- <para>
- In doubt, unless a user shows you hard numbers about the
performance
- cost of the function call, just implement
<function>maman_bar_do_action</function>
- in the source file.
- </para>
-
- <para>
- Please, note that it is possible for you to provide a default
- implementation for this class method in the object's
- <function>class_init</function> function: initialize the
- klass->do_action field to a pointer to the actual
implementation.
- You can also make this class method pure virtual by initializing
- the klass->do_action field to NULL:
-<programlisting>
-static void
-maman_bar_real_do_action_two (MamanBar *self, /* parameters */)
-{
- /* Default implementation for the virtual method. */
-}
-
-static void
-maman_bar_class_init (BarClass *klass)
-{
- /* pure virtual method: mandates implementation in children. */
- klass->do_action_one = NULL;
-
- /* merely virtual method. */
- klass->do_action_two = maman_bar_real_do_action_two;
-}
-
-void
-maman_bar_do_action_one (MamanBar *self, /* parameters */)
-{
- g_return_if_fail (MAMAN_IS_BAR (self));
-
- MAMAN_BAR_GET_CLASS (self)->do_action_one (self, /* parameters */);
-}
-
-void
-maman_bar_do_action_two (MamanBar *self, /* parameters */)
-{
- g_return_if_fail (MAMAN_IS_BAR (self));
-
- MAMAN_BAR_GET_CLASS (self)->do_action_two (self, /* parameters */);
-}
-</programlisting>
- </para>
- </sect2>
-
- <sect2>
- <title>Virtual private Methods</title>
-
- <para>
- These are very similar to Virtual Public methods. They just don't
- have a public function to call the function directly. The header
- file contains only a declaration of the class function:
-<programlisting>
-/* declaration in maman-bar.h. */
-struct _MamanBarClass
-{
- GObjectClass parent;
-
- /* stuff */
- void (* helper_do_specific_action) (MamanBar *self, /* parameters */);
-};
-
-void maman_bar_do_any_action (MamanBar *self, /* parameters */);
-</programlisting>
- These class functions are often used to delegate part of the job
- to child classes:
-<programlisting>
-/* this accessor function is static: it is not exported outside of this
file. */
-static void
-maman_bar_do_specific_action (MamanBar *self, /* parameters */)
-{
- MAMAN_BAR_GET_CLASS (self)->do_specific_action (self, /* parameters */);
-}
-
-void
-maman_bar_do_any_action (MamanBar *self, /* parameters */)
-{
- /* random code here */
-
- /*
- * Try to execute the requested action. Maybe the requested action
- * cannot be implemented here. So, we delegate its implementation
- * to the child class:
- */
- maman_bar_do_specific_action (self, /* parameters */);
-
- /* other random code here */
-}
-</programlisting>
- </para>
-
- <para>
- Again, it is possible to provide a default implementation for this
- private virtual class function:
-<programlisting>
-static void
-maman_bar_class_init (MamanBarClass *klass)
-{
- /* pure virtual method: mandates implementation in children. */
- klass->do_specific_action_one = NULL;
-
- /* merely virtual method. */
- klass->do_specific_action_two = maman_bar_real_do_specific_action_two;
-}
-</programlisting>
- </para>
-
- <para>
- Children can then implement the subclass with code such as:
-<programlisting>
-static void
-maman_bar_subtype_class_init (MamanBarSubTypeClass *klass)
-{
- MamanBarClass *bar_class = MAMAN_BAR_CLASS (klass);
-
- /* implement pure virtual class function. */
- bar_class->do_specific_action_one =
maman_bar_subtype_do_specific_action_one;
-}
-</programlisting>
- </para>
- </sect2>
- </sect1>
-
- <sect1 id="howto-gobject-chainup">
- <title>Chaining up</title>
-
- <para>Chaining up is often loosely defined by the following set of
- conditions:
- <itemizedlist>
- <listitem><para>Parent class A defines a public virtual method
named <function>foo</function> and
- provides a default implementation.</para></listitem>
- <listitem><para>Child class B re-implements method
<function>foo</function>.</para></listitem>
- <listitem><para>In the method B::foo, the child class B calls its
parent class method A::foo.</para></listitem>
- </itemizedlist>
- There are many uses to this idiom:
- <itemizedlist>
- <listitem><para>You need to change the behaviour of a class
without modifying its code. You create
- a subclass to inherit its implementation, re-implement a public
virtual method to modify the behaviour
- slightly and chain up to ensure that the previous behaviour is
not really modified, just extended.
- </para></listitem>
- <listitem><para>You are lazy, you have access to the source code
of the parent class but you don't want
- to modify it to add method calls to new specialized method
calls: it is faster to hack the child class
- to chain up than to modify the parent to call
down.</para></listitem>
- <listitem><para>You need to implement the Chain Of Responsibility
pattern: each object of the inheritance
- tree chains up to its parent (typically, at the beginning or the
end of the method) to ensure that
- they each handler is run in turn.</para></listitem>
- </itemizedlist>
- I am personally not really convinced any of the last two uses are
really a good idea but since this
- programming idiom is often used, this section attempts to explain
how to implement it.
- </para>
-
- <para>
- To explicitly chain up to the implementation of the virtual method
in the parent class,
- you first need a handle to the original parent class structure. This
pointer can then be used to
- access the original class function pointer and invoke it directly.
- <footnote>
- <para>
- The <emphasis>original</emphasis> adjective used in this
sentence is not innocuous. To fully
- understand its meaning, you need to recall how class structures
are initialized: for each object type,
- the class structure associated to this object is created by
first copying the class structure of its
- parent type (a simple <function>memcpy</function>) and then by
invoking the class_init callback on
- the resulting class structure. Since the class_init callback is
responsible for overwriting the class structure
- with the user re-implementations of the class methods, we cannot
merely use the modified copy of the parent class
- structure stored in our derived instance. We want to get a copy
of the class structure of an instance of the parent
- class.
- </para>
- </footnote>
- </para>
-
- <para>The function <function><link
linkend="g-type-class-peek-parent">g_type_class_peek_parent</link></function>
is used to access the original parent
- class structure. Its input is a pointer to the class of the derived
object and it returns a pointer
- to the original parent class structure. The code below shows how you
could use it:
-<programlisting>
-static void
-b_method_to_call (B *obj, int a)
-{
- BClass *klass;
- AClass *parent_class;
-
- klass = B_GET_CLASS (obj);
- parent_class = g_type_class_peek_parent (klass);
-
- /* do stuff before chain up */
-
- parent_class->method_to_call (obj, a);
-
- /* do stuff after chain up */
-}
-</programlisting>
- </para>
-
- </sect1>
-
-</chapter>
-
-
-<chapter id="howto-interface">
- <title>How to define and implement interfaces</title>
-
- <sect1 id="howto-interface-define">
- <title>How to define interfaces</title>
-
- <para>
- The bulk of interface definition has already been shown in <xref
linkend="gtype-non-instantiable-classed"/>
- but I feel it is needed to show exactly how to create an interface.
- </para>
-
- <para>
- As above, the first step is to get the header right:
-<programlisting>
-#ifndef __MAMAN_IBAZ_H__
-#define __MAMAN_IBAZ_H__
-
-#include <glib-object.h>
-
-#define MAMAN_TYPE_IBAZ (maman_ibaz_get_type ())
-#define MAMAN_IBAZ(obj) (G_TYPE_CHECK_INSTANCE_CAST
((obj), MAMAN_TYPE_IBAZ, MamanIbaz))
-#define MAMAN_IS_IBAZ(obj) (G_TYPE_CHECK_INSTANCE_TYPE
((obj), MAMAN_TYPE_IBAZ))
-#define MAMAN_IBAZ_GET_INTERFACE(inst) (G_TYPE_INSTANCE_GET_INTERFACE
((inst), MAMAN_TYPE_IBAZ, MamanIbazInterface))
-
-
-typedef struct _MamanIbaz MamanIbaz; /* dummy object */
-typedef struct _MamanIbazInterface MamanIbazInterface;
-
-struct _MamanIbazInterface
-{
- GTypeInterface parent_iface;
-
- void (*do_action) (MamanIbaz *self);
-};
-
-GType maman_ibaz_get_type (void);
-
-void maman_ibaz_do_action (MamanIbaz *self);
-
-#endif /* __MAMAN_IBAZ_H__ */
-</programlisting>
- This code is the same as the code for a normal <link
linkend="GType"><type>GType</type></link>
- which derives from a <link
linkend="GObject"><type>GObject</type></link> except for a few details:
- <itemizedlist>
- <listitem><para>
- The <function>_GET_CLASS</function> macro is called
<function>_GET_INTERFACE</function>
- and not implemented with <function><link
linkend="G_TYPE_INSTANCE_GET_CLASS">G_TYPE_INSTANCE_GET_CLASS</link></function>
- but with <function><link
linkend="G_TYPE_INSTANCE_GET_INTERFACE">G_TYPE_INSTANCE_GET_INTERFACE</link></function>.
- </para></listitem>
- <listitem><para>
- The instance type, <type>MamanIbaz</type> is not fully defined: it
is
- used merely as an abstract type which represents an instance of
- whatever object which implements the interface.
- </para></listitem>
- <listitem><para>
- The parent of the <type>MamanIbazInterface</type> is not
- <type>GObjectClass</type> but <type>GTypeInterface</type>.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- The implementation of the <type>MamanIbaz</type> type itself is
trivial:
- <itemizedlist>
- <listitem><para><function>maman_ibaz_get_type</function> registers
the
- type in the type system.
- </para></listitem>
- <listitem><para><function>maman_ibaz_base_init</function> is expected
- to register the interface's signals if there are any (we will see a
bit
- (later how to use them). Make sure to use a static local boolean
variable
- to make sure not to run the initialization code twice (as described
in
- <xref linkend="gtype-non-instantiable-classed-init"/>,
- <function>base_init</function> is run once for each interface
implementation
- instantiation)</para></listitem>
- <listitem><para><function>maman_ibaz_do_action</function>
dereferences
- the class structure to access its associated class function and
calls it.
- </para></listitem>
- </itemizedlist>
-<programlisting>
-static void
-maman_ibaz_base_init (gpointer g_class)
-{
- static gboolean is_initialized = FALSE;
-
- if (!is_initialized)
- {
- /* add properties and signals to the interface here */
-
- is_initialized = TRUE;
- }
-}
-
-GType
-maman_ibaz_get_type (void)
-{
- static GType iface_type = 0;
- if (iface_type == 0)
- {
- static const GTypeInfo info = {
- sizeof (MamanIbazInterface),
- maman_ibaz_base_init, /* base_init */
- NULL, /* base_finalize */
- };
-
- iface_type = g_type_register_static (G_TYPE_INTERFACE, "MamanIbaz",
- &info, 0);
- }
-
- return iface_type;
-}
-
-void
-maman_ibaz_do_action (MamanIbaz *self)
-{
- g_return_if_fail (MAMAN_IS_IBAZ (self));
-
- MAMAN_IBAZ_GET_INTERFACE (self)->do_action (self);
-}
-</programlisting>
- </para>
- </sect1>
-
- <sect1 id="howto-interface-implement">
- <title>How To define implement an Interface?</title>
-
- <para>
- Once the interface is defined, implementing it is rather trivial.
- </para>
-
- <para>
- The first step is to define a normal GObject class, like:
-<programlisting>
-#ifndef __MAMAN_BAZ_H__
-#define __MAMAN_BAZ_H__
-
-#include <glib-object.h>
-
-#define MAMAN_TYPE_BAZ (maman_baz_get_type ())
-#define MAMAN_BAZ(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj),
MAMAN_TYPE_BAZ, Mamanbaz))
-#define MAMAN_IS_BAZ(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj),
MAMAN_TYPE_BAZ))
-#define MAMAN_BAZ_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass),
MAMAN_TYPE_BAZ, MamanbazClass))
-#define MAMAN_IS_BAZ_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass),
MAMAN_TYPE_BAZ))
-#define MAMAN_BAZ_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj),
MAMAN_TYPE_BAZ, MamanbazClass))
-
-
-typedef struct _MamanBaz MamanBaz;
-typedef struct _MamanBazClass MamanBazClass;
-
-struct _MamanBaz
-{
- GObject parent_instance;
-
- int instance_member;
-};
-
-struct _MamanBazClass
-{
- GObjectClass parent_class;
-};
-
-GType maman_baz_get_type (void);
-
-#endif /* __MAMAN_BAZ_H__ */
-</programlisting>
- There is clearly nothing specifically weird or scary about this
header:
- it does not define any weird API or derives from a weird type.
- </para>
-
- <para>
- The second step is to implement <type>MamanBaz</type> by defining
- its GType. Instead of using <function>G_DEFINE_TYPE</function> we
- use <function>G_DEFINE_TYPE_WITH_CODE</function> and the
- <function>G_IMPLEMENT_INTERFACE</function> macros.
-<programlisting>
-static void maman_ibaz_interface_init (MamanIbazInterface *iface);
-
-G_DEFINE_TYPE_WITH_CODE (MamanBar, maman_bar, G_TYPE_OBJECT,
- G_IMPLEMENT_INTERFACE (MAMAN_TYPE_IBAZ,
-
maman_ibaz_interface_init));
-</programlisting>
- This definition is very much like all the similar functions we looked
- at previously. The only interface-specific code present here is the
call
- to <function>G_IMPLEMENT_INTERFACE</function>.
- </para>
-
- <note><para>Classes can implement multiple interfaces by using multiple
- calls to <function>G_IMPLEMENT_INTERFACE</function> inside the call
- to <function>G_DEFINE_TYPE_WITH_CODE</function>.</para></note>
-
- <para>
- <function>maman_baz_interface_init</function>, the interface
- initialization function: inside it every virtual method of the
interface
- must be assigned to its implementation:
-<programlisting>
-static void
-maman_baz_do_action (MamanBaz *self)
-{
- g_print ("Baz implementation of IBaz interface Action: 0x%x.\n",
- self->instance_member);
-}
-
-static void
-maman_ibaz_interface_init (MamanIbazInterface *iface)
-{
- iface->do_action = baz_do_action;
-}
-
-static void
-maman_baz_init (MamanBaz *self)
-{
- MamanBaz *self = MAMAN_BAZ (instance);
- self->instance_member = 0xdeadbeaf;
-}
-</programlisting>
- </para>
-
- </sect1>
***The diff for this file has been truncated for email.***
=======================================
--- /trunk/zh_CN/gobject/docs-2.28.5/tut_intro.xml Sun Apr 10 08:46:13 2011
+++ /dev/null
@@ -1,182 +0,0 @@
-<?xml version='1.0' encoding="ISO-8859-1"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-]>
-<chapter id="chapter-intro">
- <title>Background</title>
-
- <para>
- GObject, and its lower-level type system, GType, are used by GTK+ and
most GNOME libraries to
- provide:
- <itemizedlist>
- <listitem><para>object-oriented C-based APIs and</para></listitem>
- <listitem><para>automatic transparent API bindings to other compiled
- or interpreted languages.</para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- A lot of programmers are used to working with compiled-only or
dynamically interpreted-only
- languages and do not understand the challenges associated with
cross-language interoperability.
- This introduction tries to provide an insight into these challenges
and briefly describes
- the solution chosen by GLib.
- </para>
-
- <para>
- The following chapters go into greater detail into how GType and
GObject work and
- how you can use them as a C programmer. It is useful to keep in mind
that
- allowing access to C objects from other interpreted languages was one
of the major design
- goals: this can often explain the sometimes rather convoluted APIs and
features present
- in this library.
- </para>
-
- <sect1>
- <title>Data types and programming</title>
-
- <para>
- One could say (I have seen such definitions used in some textbooks
on programming language theory)
- that a programming language is merely a way to create data types and
manipulate them. Most languages
- provide a number of language-native types and a few primitives to
create more complex types based
- on these primitive types.
- </para>
-
- <para>
- In C, the language provides types such as <emphasis>char</emphasis>,
<emphasis>long</emphasis>,
- <emphasis>pointer</emphasis>. During compilation of C code, the
compiler maps these
- language types to the compiler's target architecture machine types.
If you are using a C interpreter
- (I have never seen one myself but it is possible :), the interpreter
(the program which interprets
- the source code and executes it) maps the language types to the
machine types of the target machine at
- runtime, during the program execution (or just before execution if
it uses a Just In Time compiler engine).
- </para>
-
- <para>
- Perl and Python are interpreted languages which do not really
provide type definitions similar
- to those used by C. Perl and Python programmers manipulate variables
and the type of the variables
- is decided only upon the first assignment or upon the first use
which forces a type on the variable.
- The interpreter also often provides a lot of automatic conversions
from one type to the other. For example,
- in Perl, a variable which holds an integer can be automatically
converted to a string given the
- required context:
-<programlisting>
-my $tmp = 10;
-print "this is an integer converted to a string:" . $tmp . "\n";
-</programlisting>
- Of course, it is also often possible to explicitly specify
conversions when the default conversions provided
- by the language are not intuitive.
- </para>
-
- </sect1>
-
- <sect1>
- <title>Exporting a C API</title>
-
- <para>
- C APIs are defined by a set of functions and global variables which
are usually exported from a
- binary. C functions have an arbitrary number of arguments and one
return value. Each function is thus
- uniquely identified by the function name and the set of C types
which describe the function arguments
- and return value. The global variables exported by the API are
similarly identified by their name and
- their type.
- </para>
-
- <para>
- A C API is thus merely defined by a set of names to which a set of
types are associated. If you know the
- function calling convention and the mapping of the C types to the
machine types used by the platform you
- are on, you can resolve the name of each function to find where the
code associated to this function
- is located in memory, and then construct a valid argument list for
the function. Finally, all you have to
- do is trigger a call to the target C function with the argument list.
- </para>
-
- <para>
- For the sake of discussion, here is a sample C function and the
associated 32 bit x86
- assembly code generated by GCC on my Linux box:
-<programlisting>
-static void function_foo (int foo)
-{}
-
-int main (int argc, char *argv[])
-{
-
- function_foo (10);
-
- return 0;
-}
-
-push $0xa
-call 0x80482f4 <function_foo>
-</programlisting>
- The assembly code shown above is pretty straightforward: the first
instruction pushes
- the hexadecimal value 0xa (decimal value 10) as a 32-bit integer on
the stack and calls
- <function>function_foo</function>. As you can see, C function calls
are implemented by
- gcc by native function calls (this is probably the fastest
implementation possible).
- </para>
-
- <para>
- Now, let's say we want to call the C function
<function>function_foo</function> from
- a Python program. To do this, the Python interpreter needs to:
- <itemizedlist>
- <listitem><para>Find where the function is located. This probably
means finding the binary generated by the C compiler
- which exports this function.</para></listitem>
- <listitem><para>Load the code of the function in executable
memory.</para></listitem>
- <listitem><para>Convert the Python parameters to C-compatible
parameters before calling
- the function.</para></listitem>
- <listitem><para>Call the function with the right calling
convention.</para></listitem>
- <listitem><para>Convert the return values of the C function to
Python-compatible
- variables to return them to the Python code.</para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- The process described above is pretty complex and there are a lot of
ways to make it entirely automatic
- and transparent to C and Python programmers:
- <itemizedlist>
- <listitem><para>The first solution is to write by hand a lot of
glue code, once for each function exported or imported,
- which does the Python-to-C parameter conversion and the
C-to-Python return value conversion. This glue code is then
- linked with the interpreter which allows Python programs to call
Python functions which delegate work to
- C functions.</para></listitem>
- <listitem><para>Another, nicer solution is to automatically
generate the glue code, once for each function exported or
- imported, with a special compiler which
- reads the original function signature.</para></listitem>
- <listitem><para>The solution used by GLib is to use the GType
library which holds at runtime a description of
- all the objects manipulated by the programmer. This so-called
<emphasis>dynamic type</emphasis>
- <footnote>
- <para>
- There are numerous different implementations of dynamic type
systems: all C++
- compilers have one, Java and .NET have one too. A dynamic type
system allows you
- to get information about every instantiated object at runtime.
It can be implemented
- by a process-specific database: every new object created
registers the characteristics
- of its associated type in the type system. It can also be
implemented by introspection
- interfaces. The common point between all these different type
systems and implementations
- is that they all allow you to query for object metadata at
runtime.
- </para>
- </footnote>
- library is then used by special generic glue code to automatically
convert function parameters and
- function calling conventions between different runtime
domains.</para></listitem>
- </itemizedlist>
- The greatest advantage of the solution implemented by GType is that
the glue code sitting at the runtime domain
- boundaries is written once: the figure below states this more
clearly.
- <figure>
- <mediaobject>
- <imageobject> 
- <imagedata fileref="glue.png" format="PNG" align="center"/>
- </imageobject>
- <imageobject> 
- <imagedata fileref="glue.jpg" format="JPG" align="center"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- Currently, there exist at least Python and Perl generic glue code
which makes it possible to use
- C objects written with GType directly in Python or Perl, with a
minimum amount of work: there
- is no need to generate huge amounts of glue code either
automatically or by hand.
- </para>
-
- <para>
- Although that goal was arguably laudable, its pursuit has had a
major influence on
- the whole GType/GObject library. C programmers are likely to be
puzzled at the complexity
- of the features exposed in the following chapters if they forget
that the GType/GObject library
- was not only designed to offer OO-like features to C programmers but
also transparent
- cross-language interoperability.
- </para>
-
- </sect1>
-
-</chapter>
=======================================
--- /trunk/zh_CN/gobject/docs-2.28.5/tut_tools.xml Sun Apr 10 08:46:13 2011
+++ /dev/null
@@ -1,132 +0,0 @@
-<?xml version='1.0' encoding="ISO-8859-1"?>
-<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-]>
-<part label="V">
- <title>Related Tools</title>
-
- <partintro>
- <para>
- Several useful developer tools have been build around GObject
- technology. The next sections briefly introduce them and link to
- the respective project pages.
- </para>
-
- <para>
- For example, writing GObjects is often seen as a tedious task. It
- requires a lot of typing and just doing a copy/paste requires a
- great deal of care. A lot of projects and scripts have been
- written to generate GObject skeleton form boilerplate code, or
- even translating higher-level language into plain C.
- </para>
- </partintro>
-
- <chapter id="tools-vala">
- <title>Vala</title>
- <para>
- From the <ulink url="http://live.gnome.org/Vala">Vala
- homepage</ulink> itself: <quote>Vala is a new programming language
- that aims to bring modern programming language features to GNOME
- developers without imposing any additional runtime requirements
- and without using a different ABI compared to applications and
- libraries written in C.</quote>
- </para>
-
- <para>
- The syntax of Vala is similar to C#. The available compiler
- translates Vala into GObject C code. It can also compile
- non-GObject C, using plain C API.
- </para>
- </chapter>
-
- <chapter id="tools-gob">
- <title>GObject builder</title>
-
- <para>
- In order to help a GObject class developper, one obvious idea is
- to use some sort of templates for the skeletons. and then run
- them through a special tool to generate the real C files. <ulink
- url="http://www.5z.com/jirka/gob.html">GOB</ulink> (or GOB2) is
- such a tool. It is a preprocessor which can be used to build
- GObjects with inline C code so that there is no need to edit the
- generated C code. The syntax is inspired by Java and Yacc or
- Lex. The implementation is intentionally kept simple: the inline C
- code provided by the user is not parsed.
- </para>
- </chapter>
-
- <chapter id="tools-ginspector">
- <title>Graphical inspection of GObjects</title>
-
- <para>
- Yet another tool that you may find helpful when working with
- GObjects is <ulink
-
url="http://sourceforge.net/projects/g-inspector">G-Inspector</ulink>. It
- is able to display GLib/GTK+ objects and their properties.
- </para>
- </chapter>
-
- <chapter id="tools-refdb">
- <title>Debugging reference count problems</title>
-
- <para>
- The reference counting scheme used by GObject does solve quite
- a few memory management problems but also introduces new sources of
bugs.
- In large applications, finding the exact spot where the reference
count
- of an Object is not properly handled can be very difficult.
Hopefully,
- there exist a tool named <ulink
url="http://refdbg.sf.net/">refdbg</ulink>
- which can be used to automate the task of tracking down the location
- of invalid code with regard to reference counting. This application
- intercepts the reference counting calls and tries to detect invalid
behavior.
- It supports a filter-rule mechanism to let you trace only the
objects you are
- interested in and it can be used together with GDB.
- </para>
- <para>
- <indexterm><primary>g_trap_object_ref</primary></indexterm>
- Note that if GObject has been compiled with
<option>--enable-debug=yes</option>,
- it exports a trap variable
- <programlisting>
-static volatile GObject *g_trap_object_ref;
- </programlisting>
- If set to a non-NULL value, <link
linkend="g-object-ref">g_object_ref</link>()
- and <link linkend="g-object-unref">g_object_unref</link>() will be
intercepted
- when called with that value.
- </para>
- </chapter>
-
- <chapter id="tools-gtkdoc">
- <title>Writing API docs</title>
-
- <para>The API documentation for most of the GLib, GObject, GTK+ and
GNOME
- libraries is built with a combination of complex tools. Typically, the
part of
- the documentation which describes the behavior of each function is
extracted
- from the specially-formatted source code comments by a tool named
gtk-doc which
- generates DocBook XML and merges this DocBook XML with a set of master
XML
- DocBook files. These XML DocBook files are finally processed with
xsltproc
- (a small program part of the libxslt library) to generate the final
HTML
- output. Other tools can be used to generate PDF output from the source
XML.
- The following code excerpt shows what these comments look like.
- <programlisting>
-/**
- * gtk_widget_freeze_child_notify:
- * @widget: a #GtkWidget
- *
- * Stops emission of "child-notify" signals on @widget. The signals are
- * queued until gtk_widget_thaw_child_notify() is called on @widget.
- *
- * This is the analogue of g_object_freeze_notify() for child properties.
- **/
-void
-gtk_widget_freeze_child_notify (GtkWidget *widget)
-{
-...
- </programlisting>
- </para>
- <para>
- Thorough
- <ulink
url="http://library.gnome.org/devel/gtk-doc-manual/stable/">documentation</ulink>
- on how to set up and use gtk-doc in your project is provided on the
- <ulink url="http://library.gnome.org/devel/">GNOME developer
website</ulink>.
- </para>
- </chapter>
-</part>
=======================================
--- /trunk/zh_CN/gobject/AUTHORS Mon Apr 11 08:57:23 2011
+++ /trunk/zh_CN/gobject/AUTHORS Sun Apr 17 09:09:31 2011
@@ -1,28 +1,17 @@
#!/bin/sh

####################################################################################
-#一、[Introduction]
-#1. gobject-docs.sgml
-#二、[Concepts]
-#1. tut_intro.xml
-#2. tut_gtype.xml
-#3. tut_gobject.xml
-#4. tut_gsignal.xml
-#三、[Tools Reference]
-#1. glib-mkenums.xml
-#2. glib-genmarshal.xml
-#3. gobject-query.xml
-#四、[Tutorial]
-#1. tut_howto.xml
-#五、[Related Tools]
-#1. tut_tools.xml
+#一、[xmlpo 文件列表]
+#
+#二、[po 文件列表]
+#

####################################################################################
#此文件的格式如下
-#作者邮箱 sgml文件数组 po文件数组
-#sgml_files和po_files数组内容以","分隔，中间不要使用空格，否则项目脚本将出
错。
+#作者邮箱 xmlpo文件数组 po文件数组
+#xmlpo_files和po_files数组内容以","分隔，中间不要使用空格，否则项目脚本将出
错。
#作者名为unknown表示计划翻译，但目前还无人认领
#作者名为finished表示内容已经翻译完成。
########已经和正在翻译的文档###############
-yetist yet...@gmail.com sgml_files=(gobject-docs.sgml,tut_gtype.xml)
po_files=()
-黑孩儿 ad...@heiher.info sgml_files=(tut_gtype.xml) po_files=()
+yetist yet...@gmail.com xmlpo_files=(gobject-docs.po,tut_gtype.po)
po_files=()
+黑孩儿 ad...@heiher.info xmlpo_files=(tut_gtype.po) po_files=()
########计划翻译的文档###############
unknown unk...@nomail.com sgml_files=() po_files=()

Reply all

Reply to author

Forward

0 new messages