<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Utility Functions: Clutter-Gtk 1.0 Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="Clutter-Gtk 1.0 Reference Manual">
<link rel="up" href="ch03.html" title="Miscellaneous">
<link rel="prev" href="ch03.html" title="Miscellaneous">
<link rel="next" href="ix01.html" title="Index">
<meta name="generator" content="GTK-Doc V1.25.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts">
<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span>
<a href="#clutter-gtk-1.0-Utility-Functions.description" class="shortcut">Description</a></span>
</td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="ch03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="ch03.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="ix01.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="clutter-gtk-1.0-Utility-Functions"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="clutter-gtk-1.0-Utility-Functions.top_of_page"></a>Utility Functions</span></h2>
<p>Utility Functions — Utility functions for integrating Clutter in GTK+</p>
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsect1">
<a name="clutter-gtk-1.0-Utility-Functions.functions"></a><h2>Functions</h2>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="functions_return">
<col class="functions_name">
</colgroup>
<tbody>
<tr>
<td class="function_type">
<span class="returnvalue">ClutterInitError</span>
</td>
<td class="function_name">
<a class="link" href="clutter-gtk-1.0-Utility-Functions.html#gtk-clutter-init" title="gtk_clutter_init ()">gtk_clutter_init</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">ClutterInitError</span>
</td>
<td class="function_name">
<a class="link" href="clutter-gtk-1.0-Utility-Functions.html#gtk-clutter-init-with-args" title="gtk_clutter_init_with_args ()">gtk_clutter_init_with_args</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">GOptionGroup</span> *
</td>
<td class="function_name">
<a class="link" href="clutter-gtk-1.0-Utility-Functions.html#gtk-clutter-get-option-group" title="gtk_clutter_get_option_group ()">gtk_clutter_get_option_group</a> <span class="c_punctuation">()</span>
</td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="clutter-gtk-1.0-Utility-Functions.description"></a><h2>Description</h2>
<p>In order to properly integrate a Clutter scene into a GTK+ applications
a certain degree of state must be retrieved from GTK+ itself.</p>
<p>Clutter-GTK provides API for easing the process of synchronizing colors
with the current GTK+ theme and for loading image sources from <span class="type">GdkPixbuf</span>,
GTK+ stock items and icon themes.</p>
</div>
<div class="refsect1">
<a name="clutter-gtk-1.0-Utility-Functions.functions_details"></a><h2>Functions</h2>
<div class="refsect2">
<a name="gtk-clutter-init"></a><h3>gtk_clutter_init ()</h3>
<pre class="programlisting"><span class="returnvalue">ClutterInitError</span>
gtk_clutter_init (<em class="parameter"><code><span class="type">int</span> *argc</code></em>,
<em class="parameter"><code><span class="type">char</span> ***argv</code></em>);</pre>
<p>This function should be called instead of <code class="function">clutter_init()</code> and
<code class="function">gtk_init()</code>.</p>
<div class="refsect3">
<a name="gtk-clutter-init.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>argc</p></td>
<td class="parameter_description"><p>pointer to the arguments count, or <code class="literal">NULL</code>. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
</tr>
<tr>
<td class="parameter_name"><p>argv</p></td>
<td class="parameter_description"><p>pointer to the
arguments vector, or <code class="literal">NULL</code>. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=argc][<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="gtk-clutter-init.returns"></a><h4>Returns</h4>
<p> <code class="literal">CLUTTER_INIT_SUCCESS</code> on success, a negative integer
on failure.</p>
</div>
</div>
<hr>
<div class="refsect2">
<a name="gtk-clutter-init-with-args"></a><h3>gtk_clutter_init_with_args ()</h3>
<pre class="programlisting"><span class="returnvalue">ClutterInitError</span>
gtk_clutter_init_with_args (<em class="parameter"><code><span class="type">int</span> *argc</code></em>,
<em class="parameter"><code><span class="type">char</span> ***argv</code></em>,
<em class="parameter"><code>const <span class="type">char</span> *parameter_string</code></em>,
<em class="parameter"><code><span class="type">GOptionEntry</span> *entries</code></em>,
<em class="parameter"><code>const <span class="type">char</span> *translation_domain</code></em>,
<em class="parameter"><code><span class="type">GError</span> **error</code></em>);</pre>
<p>This function should be called instead of <code class="function">clutter_init()</code> and
<code class="function">gtk_init_with_args()</code>.</p>
<div class="refsect3">
<a name="gtk-clutter-init-with-args.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>argc</p></td>
<td class="parameter_description"><p>a pointer to the number of command line
arguments, or <code class="literal">NULL</code>. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
</tr>
<tr>
<td class="parameter_name"><p>argv</p></td>
<td class="parameter_description"><p>a pointer to the array
of command line arguments, or <code class="literal">NULL</code>. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=argc]</span></td>
</tr>
<tr>
<td class="parameter_name"><p>parameter_string</p></td>
<td class="parameter_description"><p>a string which is displayed in
the first line of <code class="option">--help</code> output, after
<code class="literal"><em class="replaceable"><code>programname</code></em> [OPTION...]</code>. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
</tr>
<tr>
<td class="parameter_name"><p>entries</p></td>
<td class="parameter_description"><p>a
<code class="literal">NULL</code>-terminated array of <span class="type">GOptionEntry</span>s describing the
options of your program. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1]</span></td>
</tr>
<tr>
<td class="parameter_name"><p>translation_domain</p></td>
<td class="parameter_description"><p>a translation domain to use for
translating the <code class="option">--help</code> output for the options
in <em class="parameter"><code>entries</code></em>
with <code class="function">gettext()</code>, or <code class="literal">NULL</code>. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
</tr>
<tr>
<td class="parameter_name"><p>error</p></td>
<td class="parameter_description"><p>a return location for errors, or <code class="literal">NULL</code>. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="gtk-clutter-init-with-args.returns"></a><h4>Returns</h4>
<p> <code class="literal">CLUTTER_INIT_SUCCESS</code> on success, a negative integer
on failure.</p>
</div>
</div>
<hr>
<div class="refsect2">
<a name="gtk-clutter-get-option-group"></a><h3>gtk_clutter_get_option_group ()</h3>
<pre class="programlisting"><span class="returnvalue">GOptionGroup</span> *
gtk_clutter_get_option_group (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
<p>Returns a <span class="type">GOptionGroup</span> for the command line arguments recognized
by Clutter. You should add this group to your <span class="type">GOptionContext</span> with
<code class="function">g_option_context_add_group()</code>, if you are using <code class="function">g_option_context_parse()</code>
to parse your commandline arguments instead of using <a class="link" href="clutter-gtk-1.0-Utility-Functions.html#gtk-clutter-init" title="gtk_clutter_init ()"><code class="function">gtk_clutter_init()</code></a>
or <a class="link" href="clutter-gtk-1.0-Utility-Functions.html#gtk-clutter-init-with-args" title="gtk_clutter_init_with_args ()"><code class="function">gtk_clutter_init_with_args()</code></a>.</p>
<p>You should add this option group to your <span class="type">GOptionContext</span> after
the GTK option group created with <code class="function">gtk_get_option_group()</code>, and after
the clutter option group obtained from <code class="function">clutter_get_option_group_without_init()</code>.
You should not use <code class="function">clutter_get_option_group()</code> together with this function.</p>
<p>You must pass <code class="literal">TRUE</code> to <code class="function">gtk_get_option_group()</code> since gtk-clutter's option
group relies on it.</p>
<p>Parsing options using <code class="function">g_option_context_parse()</code> with a <span class="type">GOptionContext</span>
containing the returned <span class="type">GOptionGroupwith</span> will result in Clutter's and
GTK-Clutter's initialisation. That is, the following code:</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="function">g_option_context_add_group</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">context</span><span class="symbol">,</span><span class="normal"> </span><span class="function">gtk_get_option_group</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">TRUE</span><span class="symbol">));</span>
<span class="function">g_option_context_add_group</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">context</span><span class="symbol">,</span><span class="normal"> </span><span class="function">cogl_get_option_group</span><span class="normal"> </span><span class="symbol">());</span>
<span class="function">g_option_context_add_group</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">context</span><span class="symbol">,</span><span class="normal"> </span><span class="function">clutter_get_option_group_without_init</span><span class="normal"> </span><span class="symbol">());</span>
<span class="function">g_option_context_add_group</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">context</span><span class="symbol">,</span><span class="normal"> </span><span class="function"><a href="clutter-gtk-1.0-Utility-Functions.html#gtk-clutter-get-option-group">gtk_clutter_get_option_group</a></span><span class="normal"> </span><span class="symbol">());</span>
<span class="normal">res </span><span class="symbol">=</span><span class="normal"> </span><span class="function">g_option_context_parse</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">context</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">argc</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">argc</span><span class="symbol">,</span><span class="normal"> NULL</span><span class="symbol">);</span></pre></td>
</tr>
</tbody>
</table>
</div>
<p></p>
<p>is functionally equivalent to:</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="function"><a href="clutter-gtk-1.0-Utility-Functions.html#gtk-clutter-init">gtk_clutter_init</a></span><span class="normal"> </span><span class="symbol">(&</span><span class="normal">argc</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">argv</span><span class="symbol">);</span></pre></td>
</tr>
</tbody>
</table>
</div>
<p></p>
<p>After <code class="function">g_option_context_parse()</code> on a <span class="type">GOptionContext</span> containing the
the returned <span class="type">GOptionGroup</span> has returned <code class="literal">TRUE</code>, Clutter and GTK-Clutter are
guaranteed to be initialized.</p>
<p><span class="annotation">[<acronym title="Exposed in C code, not necessarily available in other languages."><span class="acronym">skip</span></acronym>]</span></p>
<div class="refsect3">
<a name="gtk-clutter-get-option-group.returns"></a><h4>Returns</h4>
<p>a <span class="type">GOptionGroup</span> for the commandline arguments
recognized by ClutterGtk. </p>
<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p>
</div>
</div>
</div>
<div class="refsect1">
<a name="clutter-gtk-1.0-Utility-Functions.other_details"></a><h2>Types and Values</h2>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.25.1</div>
</body>
</html>