docs/reference/gobject/html/glib-genmarshal.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>glib-genmarshal</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="index.html" title="GObject Reference Manual">
   8 <link rel="up" href="rn02.html" title="Tools Reference">
   9 <link rel="prev" href="glib-mkenums.html" title="glib-mkenums">
  10 <link rel="next" href="gobject-query.html" title="gobject-query">
  11 <meta name="generator" content="GTK-Doc V1.13 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 <link rel="preface" href="pr01.html" title="Introduction">
  14 <link rel="part" href="pt01.html" title="Part I. Concepts">
  15 <link rel="chapter" href="chapter-intro.html" title="Background">
  16 <link rel="chapter" href="chapter-gtype.html" title="The GLib Dynamic Type System">
  17 <link rel="chapter" href="chapter-gobject.html" title="The GObject base class">
  18 <link rel="chapter" href="chapter-signal.html" title="The GObject messaging system">
  19 <link rel="reference" href="rn01.html" title="API Reference">
  20 <link rel="reference" href="rn02.html" title="Tools Reference">
  21 <link rel="part" href="pt02.html" title="Part IV. Tutorial">
  22 <link rel="chapter" href="howto-gobject.html" title="How to define and implement a new GObject">
  23 <link rel="chapter" href="howto-interface.html" title="How to define and implement interfaces">
  24 <link rel="chapter" href="howto-signals.html" title="How to create and use signals">
  25 <link rel="part" href="pt03.html" title="Part V. Related Tools">
  26 <link rel="chapter" href="tools-vala.html" title="Vala">
  27 <link rel="chapter" href="tools-gob.html" title="GObject builder">
  28 <link rel="chapter" href="tools-ginspector.html" title="Graphical inspection of GObjects">
  29 <link rel="chapter" href="tools-refdb.html" title="Debugging reference count problems">
  30 <link rel="chapter" href="tools-gtkdoc.html" title="Writing API docs">
  31 <link rel="index" href="api-index-full.html" title="Index">
  32 <link rel="index" href="api-index-deprecated.html" title="Index of deprecated symbols">
  33 <link rel="index" href="api-index-2-2.html" title="Index of new symbols in 2.2">
  34 <link rel="index" href="api-index-2-4.html" title="Index of new symbols in 2.4">
  35 <link rel="index" href="api-index-2-6.html" title="Index of new symbols in 2.6">
  36 <link rel="index" href="api-index-2-8.html" title="Index of new symbols in 2.8">
  37 <link rel="index" href="api-index-2-10.html" title="Index of new symbols in 2.10">
  38 <link rel="index" href="api-index-2-12.html" title="Index of new symbols in 2.12">
  39 <link rel="index" href="api-index-2-14.html" title="Index of new symbols in 2.14">
  40 <link rel="index" href="api-index-2-18.html" title="Index of new symbols in 2.18">
  41 <link rel="index" href="api-index-2-22.html" title="Index of new symbols in 2.22">
  42 <link rel="index" href="api-index-2-24.html" title="Index of new symbols in 2.24">
  43 </head>
  44 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  45 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  46 <td><a accesskey="p" href="glib-mkenums.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  47 <td><a accesskey="u" href="rn02.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  48 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  49 <th width="100%" align="center">GObject Reference Manual</th>
  50 <td><a accesskey="n" href="gobject-query.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  51 </tr></table>
  52 <div class="refentry" title="glib-genmarshal">
  53 <a name="glib-genmarshal"></a><div class="titlepage"></div>
  54 <div class="refnamediv"><table width="100%"><tr>
  55 <td valign="top">
  56 <h2><span class="refentrytitle">glib-genmarshal</span></h2>
  57 <p>glib-genmarshal — C code marshaller generation utility for GLib closures</p>
  58 </td>
  59 <td valign="top" align="right"></td>
  60 </tr></table></div>
  61 <div class="refsynopsisdiv" title="Synopsis">
  62 <h2>Synopsis</h2>
  63 <div class="cmdsynopsis"><p><code class="command">glib-genmarshal</code>  [options...] [files...]</p></div>
  64 </div>
  65 <div class="refsect1" title="Description">
  66 <a name="id618843"></a><h2>Description</h2>
  67 <p><span class="command"><strong>glib-genmarshal</strong></span> is a small utility that generates C code
  68 marshallers for callback functions of the GClosure mechanism in the GObject
  69 sublibrary of GLib. The marshaller functions have a standard signature,
  70 they get passed in the invoking closure, an array of value structures holding
  71 the callback function parameters and a value structure for the return value
  72 of the callback. The marshaller is then responsible to call the respective C
  73 code function of the closure with all the parameters on the stack and to
  74 collect its return value.
  75 </p>
  76 </div>
  77 <div class="refsect1" title="Invocation">
  78 <a name="id589843"></a><h2>Invocation</h2>
  79 <p><span class="command"><strong>glib-genmarshal</strong></span> takes a list of marshallers to generate as
  80 input. The marshaller list is either read from standard input or from files
  81 passed as additional arguments on the command line.
  82 </p>
  83 <div class="refsect2" title="Options">
  84 <a name="id584517"></a><h3>Options</h3>
  85 <div class="variablelist"><table border="0">
  86 <col align="left" valign="top">
  87 <tbody>
  88 <tr>
  89 <td><p><span class="term"><code class="option">--header</code></span></p></td>
  90 <td><p>
  91 Generate header file contents of the marshallers.
  92 </p></td>
  93 </tr>
  94 <tr>
  95 <td><p><span class="term"><code class="option">--body</code></span></p></td>
  96 <td><p>
  97 Generate C code file contents of the marshallers.
  98 </p></td>
  99 </tr>
 100 <tr>
 101 <td><p><span class="term"><code class="option">--prefix=string</code>, <code class="option">--prefix string</code></span></p></td>
 102 <td><p>
 103 Specify marshaller prefix. The default prefix is <code class="literal">`g_cclosure_marshal'</code>.
 104 </p></td>
 105 </tr>
 106 <tr>
 107 <td><p><span class="term"><code class="option">--skip-source</code></span></p></td>
 108 <td><p>
 109 Skip source location remarks in generated comments.
 110 </p></td>
 111 </tr>
 112 <tr>
 113 <td><p><span class="term"><code class="option">--nostdinc</code></span></p></td>
 114 <td><p>
 115 Do not use the standard marshallers of the GObject library, and skip
 116 <code class="filename">gmarshal.h</code> include directive in generated header files.
 117 </p></td>
 118 </tr>
 119 <tr>
 120 <td><p><span class="term"><code class="option">--g-fatal-warnings</code></span></p></td>
 121 <td><p>
 122 Make warnings fatal, that is, exit immediately once a warning occurs.
 123 </p></td>
 124 </tr>
 125 <tr>
 126 <td><p><span class="term"><code class="option">-h</code>, <code class="option">--help</code></span></p></td>
 127 <td><p>
 128 Print brief help and exit.
 129 </p></td>
 130 </tr>
 131 <tr>
 132 <td><p><span class="term"><code class="option">-v</code>, <code class="option">--version</code></span></p></td>
 133 <td><p>
 134 Print version and exit.
 135 </p></td>
 136 </tr>
 137 </tbody>
 138 </table></div>
 139 </div>
 140 <hr>
 141 <div class="refsect2" title="Marshaller list format">
 142 <a name="id561940"></a><h3>Marshaller list format</h3>
 143 <p>
 144 The marshaller lists are processed line by line, a line can contain a
 145 comment in the form of
 146 </p>
 147 <pre class="programlisting">
 148 # this is a comment
 149 </pre>
 150 <p>
 151 or a marshaller specification of the form
 152 </p>
 153 <pre class="programlisting">
 154 <em class="replaceable"><code>RTYPE</code></em>:<em class="replaceable"><code>PTYPE</code></em>
 155 <em class="replaceable"><code>RTYPE</code></em>:<em class="replaceable"><code>PTYPE</code></em>,<em class="replaceable"><code>PTYPE</code></em>
 156 <em class="replaceable"><code>RTYPE</code></em>:<em class="replaceable"><code>PTYPE</code></em>,<em class="replaceable"><code>PTYPE</code></em>,<em class="replaceable"><code>PTYPE</code></em>
 157 </pre>
 158 <p>
 159 (up to 16 <em class="replaceable"><code>PTYPE</code></em>s may be present).
 160 </p>
 161 <p>
 162 The <em class="replaceable"><code>RTYPE</code></em> part specifies the callback's return
 163 type and the <em class="replaceable"><code>PTYPE</code></em>s right to the colon specify
 164 the callback's parameter list, except for the first and the last arguments
 165 which are always pointers.
 166 </p>
 167 </div>
 168 <hr>
 169 <div class="refsect2" title="Parameter types">
 170 <a name="id615939"></a><h3>Parameter types</h3>
 171 <p>
 172 Currently, the following types are supported:
 173 </p>
 174 <div class="variablelist"><table border="0">
 175 <col align="left" valign="top">
 176 <tbody>
 177 <tr>
 178 <td><p><span class="term"><em class="replaceable"><code>VOID</code></em></span></p></td>
 179 <td><p>
 180 indicates no return type, or no extra parameters.
 181 If <em class="replaceable"><code>VOID</code></em> is used as the parameter list, no
 182 additional parameters may be present.
 183 </p></td>
 184 </tr>
 185 <tr>
 186 <td><p><span class="term"><em class="replaceable"><code>BOOLEAN</code></em></span></p></td>
 187 <td><p>
 188 for boolean types (gboolean)
 189 </p></td>
 190 </tr>
 191 <tr>
 192 <td><p><span class="term"><em class="replaceable"><code>CHAR</code></em></span></p></td>
 193 <td><p>
 194 for signed char types (gchar)
 195 </p></td>
 196 </tr>
 197 <tr>
 198 <td><p><span class="term"><em class="replaceable"><code>UCHAR</code></em></span></p></td>
 199 <td><p>
 200 for unsigned char types (guchar)
 201 </p></td>
 202 </tr>
 203 <tr>
 204 <td><p><span class="term"><em class="replaceable"><code>INT</code></em></span></p></td>
 205 <td><p>
 206 for signed integer types (gint)
 207 </p></td>
 208 </tr>
 209 <tr>
 210 <td><p><span class="term"><em class="replaceable"><code>UINT</code></em></span></p></td>
 211 <td><p>
 212 for unsigned integer types (guint)
 213 </p></td>
 214 </tr>
 215 <tr>
 216 <td><p><span class="term"><em class="replaceable"><code>LONG</code></em></span></p></td>
 217 <td><p>
 218 for signed long integer types (glong)
 219 </p></td>
 220 </tr>
 221 <tr>
 222 <td><p><span class="term"><em class="replaceable"><code>ULONG</code></em></span></p></td>
 223 <td><p>
 224 for unsigned long integer types (gulong)
 225 </p></td>
 226 </tr>
 227 <tr>
 228 <td><p><span class="term"><em class="replaceable"><code>INT64</code></em></span></p></td>
 229 <td><p>
 230 for signed 64bit integer types (gint64)
 231 </p></td>
 232 </tr>
 233 <tr>
 234 <td><p><span class="term"><em class="replaceable"><code>UINT64</code></em></span></p></td>
 235 <td><p>
 236 for unsigned 64bit integer types (guint64)
 237 </p></td>
 238 </tr>
 239 <tr>
 240 <td><p><span class="term"><em class="replaceable"><code>ENUM</code></em></span></p></td>
 241 <td><p>
 242 for enumeration types (gint)
 243 </p></td>
 244 </tr>
 245 <tr>
 246 <td><p><span class="term"><em class="replaceable"><code>FLAGS</code></em></span></p></td>
 247 <td><p>
 248 for flag enumeration types (guint)
 249 </p></td>
 250 </tr>
 251 <tr>
 252 <td><p><span class="term"><em class="replaceable"><code>FLOAT</code></em></span></p></td>
 253 <td><p>
 254 for single-precision float types (gfloat)
 255 </p></td>
 256 </tr>
 257 <tr>
 258 <td><p><span class="term"><em class="replaceable"><code>DOUBLE</code></em></span></p></td>
 259 <td><p>
 260 for double-precision float types (gdouble)
 261 </p></td>
 262 </tr>
 263 <tr>
 264 <td><p><span class="term"><em class="replaceable"><code>STRING</code></em></span></p></td>
 265 <td><p>
 266 for string types (gchar*)
 267 </p></td>
 268 </tr>
 269 <tr>
 270 <td><p><span class="term"><em class="replaceable"><code>BOXED</code></em></span></p></td>
 271 <td><p>
 272 for boxed (anonymous but reference counted) types (GBoxed*)
 273 </p></td>
 274 </tr>
 275 <tr>
 276 <td><p><span class="term"><em class="replaceable"><code>PARAM</code></em></span></p></td>
 277 <td><p>
 278 for GParamSpec or derived types (GParamSpec*)
 279 </p></td>
 280 </tr>
 281 <tr>
 282 <td><p><span class="term"><em class="replaceable"><code>POINTER</code></em></span></p></td>
 283 <td><p>
 284 for anonymous pointer types (gpointer)
 285 </p></td>
 286 </tr>
 287 <tr>
 288 <td><p><span class="term"><em class="replaceable"><code>OBJECT</code></em></span></p></td>
 289 <td><p>
 290 for GObject or derived types (GObject*)
 291 </p></td>
 292 </tr>
 293 <tr>
 294 <td><p><span class="term"><em class="replaceable"><code>NONE</code></em></span></p></td>
 295 <td><p>
 296 deprecated alias for <em class="replaceable"><code>VOID</code></em>
 297 </p></td>
 298 </tr>
 299 <tr>
 300 <td><p><span class="term"><em class="replaceable"><code>BOOL</code></em></span></p></td>
 301 <td><p>
 302 deprecated alias for <em class="replaceable"><code>BOOLEAN</code></em>
 303 </p></td>
 304 </tr>
 305 </tbody>
 306 </table></div>
 307 <p>
 308 </p>
 309 </div>
 310 </div>
 311 <div class="refsect1" title="Example">
 312 <a name="id583131"></a><h2>Example</h2>
 313 <p>
 314 To generate marshallers for the following callback functions:
 315 </p>
 316 <pre class="programlisting">
 317 void   foo (gpointer data1,
 318             gpointer data2);
 319 void   bar (gpointer data1,
 320             gint     param1,
 321             gpointer data2);
 322 gfloat baz (gpointer data1,
 323             gboolean param1,
 324             guchar   param2,
 325             gpointer data2);
 326 </pre>
 327 <p>
 328 The marshaller list has to look like this:
 329 </p>
 330 <pre class="programlisting">
 331 VOID:VOID
 332 VOID:INT
 333 FLOAT:BOOLEAN,UCHAR
 334 </pre>
 335 <p>
 336 The generated marshallers have the arguments encoded in their function name.
 337 For this particular list, they are
 338 </p>
 339 <pre class="programlisting">
 340 g_cclosure_marshal_VOID__VOID(),
 341 g_cclosure_marshal_VOID__INT(),
 342 g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR().
 343 </pre>
 344 <p>
 345 They can be used directly for GClosures or be passed in as the
 346 GSignalCMarshaller c_marshaller; argument upon creation of signals:
 347 </p>
 348 <pre class="programlisting">
 349 GClosure *cc_foo, *cc_bar, *cc_baz;
 350
 351 cc_foo = g_cclosure_new (NULL, foo, NULL);
 352 g_closure_set_marshal (cc_foo, g_cclosure_marshal_VOID__VOID);
 353 cc_bar = g_cclosure_new (NULL, bar, NULL);
 354 g_closure_set_marshal (cc_bar, g_cclosure_marshal_VOID__INT);
 355 cc_baz = g_cclosure_new (NULL, baz, NULL);
 356 g_closure_set_marshal (cc_baz, g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR);
 357 </pre>
 358 </div>
 359 <div class="refsect1" title="See also">
 360 <a name="id570966"></a><h2>See also</h2>
 361 <p>
 362 <span class="command"><strong>glib-mkenums</strong></span>(1)
 363 </p>
 364 </div>
 365 <div class="refsect1" title="Bugs">
 366 <a name="id591176"></a><h2>Bugs</h2>
 367 <p>
 368 None known yet.
 369 </p>
 370 </div>
 371 <div class="refsect1" title="Author">
 372 <a name="id597530"></a><h2>Author</h2>
 373 <p><span class="command"><strong>glib-genmarshal</strong></span> has been written by Tim Janik
 374 <code class="email">&lt;<a class="email" href="mailto:timj@gtk.org">timj@gtk.org</a>&gt;</code>.
 375 </p>
 376 <p>
 377 This manual page was provided by Tim Janik <code class="email">&lt;<a class="email" href="mailto:timj@gtk.org">timj@gtk.org</a>&gt;</code>.
 378 </p>
 379 </div>
 380 </div>
 381 <div class="footer">
 382 <hr>
 383           Generated by GTK-Doc V1.13</div>
 384 </body>
 385 </html>