mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-08-04 16:33:40 +02:00
New macros to check for XML catalog contents and path, borrowed from
2003-06-17 Matthias Clasen <maclas@gmx.de> * acinclude.m4 (JH_PATH_XML_CATALOG, JH_CHECK_XML_CATALOG): New macros to check for XML catalog contents and path, borrowed from gtk-doc. * configure.in: New option --enable-man to enable regeneration of man pages from Docbook, if the necessary tools are found. * gobject/Makefile.am: Add rule to regenerate man pages from Docbook. (man_MANS): Add glib-mkenums.1, glib-genmarshal.1 and gobject-query.1. (content_files): Add glib-mkenums.xml, glib-genmarshal.xml and gobject-query.xml. * gobject/glib-mkenums.xml: * gobject/glib-genmarshal.xml: * gobject/gobject-query.xml: New refentries. * gobject/glib-mkenums.1: * gobject/glib-genmarshal.1: * gobject/gobject-query.1: Man pages generated from the .xml sources. * gobject/gobject-docs.sgml: Include glib-mkenums.xml, glib-genmarshal.xml and gobject-query.xml. * glib/Makefile.am: Add rule to regenerate man pages from Docbook. (man_MANS): Add glib-gettextize.1. (content_files): Add glib-gettextize.xml. * glib/glib-gettextize.xml: New refentry. * glib/glib-gettextize.1: Man page generated from the .xml source. * glib/glib-docs.sgml: Include glib-gettextize.xml.
This commit is contained in:
Matthias Clasen
committed by
Matthias Clasen
Matthias Clasen
parent
6411bedd01
commit
54f796b1b6
336
docs/reference/gobject/glib-genmarshal.xml
Normal file
336
docs/reference/gobject/glib-genmarshal.xml
Normal file
@@ -0,0 +1,336 @@
|
||||
<refentry id="glib-genmarshal">
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>glib-genmarshal</refentrytitle>
|
||||
<manvolnum>1</manvolnum>
|
||||
</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>Invokation</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>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>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>timj@gtk.org</email>.
|
||||
</para>
|
||||
<para>
|
||||
This manual page was provided by Tim Janik <email>timj@gtk.org</email>.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user