<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Chapter 8. Script</title><link rel="stylesheet" type="text/css" href="style.css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"><link rel="home" href="index.html" title="The Clutter Cookbook"><link rel="up" href="index.html" title="The Clutter Cookbook"><link rel="prev" href="layouts-box.html" title="4. Arranging actors in a single row or column"><link rel="next" href="script-ui.html" title="2. Defining a user interface with JSON"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 8. Script</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="layouts-box.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="script-ui.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="script"></a>Chapter 8. Script</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="script.html#script-introduction">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="script.html#idm140200511239776">1.1. Basic principles of <span class="type">ClutterScript</span></a></span></dt><dt><span class="section"><a href="script.html#script-introduction-data-types">1.2. Data types</a></span></dt></dl></dd><dt><span class="section"><a href="script-ui.html">2. Defining a user interface with JSON</a></span></dt><dd><dl><dt><span class="section"><a href="script-ui.html#idm140200507622976">2.1. Problem</a></span></dt><dt><span class="section"><a href="script-ui.html#idm140200507618752">2.2. Solution</a></span></dt><dt><span class="section"><a href="script-ui.html#idm140200507599696">2.3. Discussion</a></span></dt></dl></dd><dt><span class="section"><a href="script-signals.html">3. Connecting to signals in <span class="type">ClutterScript</span></a></span></dt><dd><dl><dt><span class="section"><a href="script-signals.html#idm140200507595856">3.1. Problem</a></span></dt><dt><span class="section"><a href="script-signals.html#idm140200507594432">3.2. Solution</a></span></dt><dt><span class="section"><a href="script-signals.html#script-signals-discussion">3.3. Discussion</a></span></dt><dt><span class="section"><a href="script-signals.html#idm140200506690384">3.4. Full examples</a></span></dt></dl></dd><dt><span class="section"><a href="script-state.html">4. Connecting <span class="type">ClutterState</span> states in <span class="type">ClutterScript</span></a></span></dt><dd><dl><dt><span class="section"><a href="script-state.html#idm140200506678736">4.1. Problem</a></span></dt><dt><span class="section"><a href="script-state.html#idm140200506677104">4.2. Solution</a></span></dt><dt><span class="section"><a href="script-state.html#idm140200506669680">4.3. Discussion</a></span></dt><dt><span class="section"><a href="script-state.html#idm140200506655840">4.4. Full examples</a></span></dt></dl></dd></dl></div><div class="epigraph"><p>When an actor comes to me and wants to discuss his character,
I say, "It's in the script". If he says, "But what's my motivation?",
I say, "Your salary".</p><div class="attribution"><span>—<span class="attribution">Alfred Hitchcock</span></span></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="script-introduction"></a>1. Introduction</h2></div></div></div><p>User interfaces can become difficult to maintain when
described entirely in code: declarations of UI
elements become entwined with procedural code for
handling interactions. This can make refactoring tough, as
you have to find the right place in the code to modify the UI
("Where did I set the color of that rectangle?") and make sure
your UI modifications don't break any behaviour.</p><p>Many frameworks separate presentation from programming
logic, making it easier to change the appearance of the UI
without affecting its behaviour (and vice versa). For example,
in web development you can use HTML and CSS to define
presentation, and JavaScript to implement application logic.</p><p><span class="type">ClutterScript</span> enables a similar separation:
you can define the UI declaratively using
<a class="ulink" href="" target="_top">JSON</a>, load
the UI from the JSON, then handle interactions with it through Clutter code
(in C, Python, Vala or some other language). This has several
benefits, including:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Separation of UI element declarations from control logic
(see above).</p></li><li class="listitem"><p>More concise code: typically, describing a UI in JSON
requires far fewer characters than the equivalent procedural
code (at least, once you have more than three or four actors in
your application).</p></li><li class="listitem"><p>If you write your JSON in external files, you can make the
structure of the UI evident in the layout of the file. For
example, child elements can be indented within the parent
element. This can make identifying relationships between
elements simpler and less error-prone.</p></li><li class="listitem"><p>Creating and configuring some objects (e.g. animations,
layouts) can be much simpler in JSON.</p></li><li class="listitem"><p>Less compilation (if you're using a compiled language):
because you can change the UI by editing external JSON files,
you can make changes to it without needing to recompile
the whole application.</p></li></ul></div><p>The following sections are intended
to give an overview of how <span class="type">ClutterScript</span> works, and
how to use it in an application. The recipes in this chapter
then provide more detail about particular aspects of
<span class="type">ClutterScript</span>, such as how to connect signals to handlers,
how to merge multiple JSON definitions in a single script, etc.
There is also a lot of useful information in the <span class="type">ClutterScript</span>
API reference.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idm140200511239776"></a>1.1. Basic principles of <span class="type">ClutterScript</span></h3></div></div></div><p>Clutter is built on top of
<a class="ulink" href="" target="_top">GObject</a>,
an object system for C. <span class="type">ClutterScript</span>
provides a way to create instances of GObjects and
set their properties. For example:</p><div class="example"><a name="idm140200507669504"></a><p class="title"><b>Example 8.1. Example UI definition in JSON for use with
<span class="type">ClutterScript</span></b></p><div class="example-contents"><div class="programlistingco"><pre class="programlisting">[ <a name="script-ui-introduction-json-list-bracket"></a>(1)
{ <a name="script-ui-introduction-json-object-bracket"></a>(2)
"id" : "stage", <a name="script-ui-introduction-json-id"></a>(3)
"type" : "ClutterStage", <a name="script-ui-introduction-json-type"></a>(4)
"width" : 400,
"height" : 400,
"color" : "#333355ff", <a name="script-ui-introduction-json-color-html"></a>(5)
"children" : [ "box" ] <a name="script-ui-introduction-json-child-by-id"></a>(6)
},
{
"id" : "box",
"type" : "ClutterBox",
"width" : 400,
"height" : 400,
"layout-manager" : { <a name="script-ui-introduction-json-no-id"></a>(7)
"type" : "ClutterBinLayout",
"x-align" : "center", <a name="script-ui-introduction-json-nickname"></a>(8)
"y-align" : "center"
},
"children" : [ <a name="script-ui-introduction-json-child-by-embedding"></a>(9)
{
"id" : "rectangle",
"type" : "ClutterRectangle",
"width" : 200,
"height" : 200,
"color" : "red" <a name="script-ui-introduction-json-color-word"></a>(10)
}
]
}
]</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>N.B. The numbers in brackets in the example further
explain the JSON structure, and are not part of the UI
definition.</p></div><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#script-ui-introduction-json-list-bracket">(1)</a> </p></td><td valign="top" align="left"><p>All the objects defined for the UI sit inside a JSON
list structure, marked with square brackets.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#script-ui-introduction-json-object-bracket">(2)</a> </p></td><td valign="top" align="left"><p>A pair of braces surrounds each object definition;
inside the braces, key-value pairs set properties on the
object. See the
<a class="link" href="script.html#script-introduction-data-types" title="1.2. Data types">section on
datatypes</a> for more about the acceptable values.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#script-ui-introduction-json-id">(3)</a> <a href="#script-ui-introduction-json-no-id">(7)</a> </p></td><td valign="top" align="left"><p>An <code class="varname">id</code> is required for objects which
are referred to elsewhere in the JSON or which need to be
accessible from code (see
<a class="link" href="script-ui.html" title="2. Defining a user interface with JSON">this recipe</a> for the basics of
using object IDs from code).</p><p>In cases where an object doesn't need to be accessible
from code and is not referenced elsewhere in the JSON file,
the <code class="varname">id</code> can be omitted.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#script-ui-introduction-json-type">(4)</a> </p></td><td valign="top" align="left"><p>The <code class="varname">type</code> key is mandatory, and
specifies the type of the object; usually this will be
one of the Clutter object types.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#script-ui-introduction-json-color-html">(5)</a> <a href="#script-ui-introduction-json-color-word">(10)</a> </p></td><td valign="top" align="left"><p>Colors can be set using hexadecimal color code strings,
as used in HTML and CSS; or by using color words. The
range of acceptable values is as for the
<code class="function">pango_color_from_string()</code> function.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#script-ui-introduction-json-child-by-id">(6)</a> <a href="#script-ui-introduction-json-child-by-embedding">(9)</a> </p></td><td valign="top" align="left"><p>Children can be associated with a parent through
the <code class="varname">children</code> property. Children are
either added to the <code class="varname">children</code> list by ID;
or by directly embedding the child JSON object as an element
within the list. The two can be mixed in a single
list of <code class="varname">children</code>.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#script-ui-introduction-json-nickname">(8)</a> </p></td><td valign="top" align="left"><p>This uses the nickname for a value in an enumeration
(in this case, the nickname for
<code class="constant">CLUTTER_BIN_ALIGNMENT_CENTER</code>).</p><p>To get the nickname for an enumeration value, take
the component which is unique to that value in the
enumeration, lowercase it, and replace any underscores
with hyphens. Some examples:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="constant">CLUTTER_ALIGN_X_AXIS</code> has
the nickname <code class="code">x-axis</code></p></li><li class="listitem"><p><code class="constant">CLUTTER_GRAVITY_NORTH</code> has
the nickname <code class="code">north</code></p></li><li class="listitem"><p><code class="constant">CLUTTER_REQUEST_HEIGHT_FOR_WIDTH</code>
has the nickname <code class="code">height-for-width</code></p></li></ul></div></td></tr></table></div></div></div></div><br class="example-break"><p>Once you grasp that Clutter objects are GObjects, and you
are setting their properties, you can work out what is "scriptable"
by referring to the <span class="emphasis"><em>Properties</em></span> sections
of the API reference for each Clutter type. Any of the properties
described there can be set using <span class="type">ClutterScript</span>.</p><p>Having said this, there are some special properties which
aren't obvious, but which can be set via JSON;
<span class="emphasis"><em>layout properties</em></span> are one example. These aren't
listed as properties of <span class="type">ClutterActor</span> but can be set
as part of a <span class="type">ClutterActor</span> object definition
(using the <code class="code">layout::<property name></code>
syntax for the key). Some of these are covered in recipes later in
this chapter.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="script-introduction-data-types"></a>1.2. Data types</h3></div></div></div><p><span class="type">ClutterScript</span> uses the standard JSON format.
It is very important that you respect the data type of the property
you are setting, ensuring that you use the right JSON data type.
You may get unexpected results or errors if you try to set a property
using the wrong data type: for example, setting a property
to an integer <span class="type">number</span> in the JSON, when the Clutter property
is expecting a <span class="type">gfloat</span>, may cause errors.</p><p>To assist in using the right data types in your JSON
definitions, the table below shows how Clutter and GLib data
types map to JSON:</p><div class="informaltable"><table><thead><tr>
<th>C data type (Clutter/GLib)</th>
<th>Maps to JSON</th>
<th>Example (C => JSON)</th>
</tr></thead><tbody><tr>
<td>floating point number (gfloat, gdouble)</td>
<td>number (int frac, int exp, int frac exp)</td>
<td>
<p><code class="code">1.0</code> => <code class="code">1.0</code></p>
<p><code class="code">1e-1</code> => <code class="code">1e-1</code></p>
<p><code class="code">1E-1</code> => <code class="code">1E-1</code></p>
<p><code class="code">0.1E-1</code> => <code class="code">0.1E-1</code></p>
</td>
</tr><tr>
<td>integer (guint8, gint)</td>
<td>number (int)</td>
<td>
<p><code class="code">1</code> => <code class="code">1</code></p>
<p><code class="code">0x00</code> => <code class="code">0</code> (no hex in JSON)</p>
<p><code class="code">01</code> => <code class="code">1</code> (no octal in JSON)</p>
</td>
</tr><tr>
<td>gboolean</td>
<td>true/false</td>
<td>
<p><code class="code">TRUE</code> => <code class="code">true</code></p>
<p><code class="code">FALSE</code> => <code class="code">false</code></p>
</td>
</tr><tr>
<td>gchar</td>
<td>string</td>
<td><code class="code">"hello world"</code> => <code class="code">"hello world"</code></td>
</tr><tr>
<td>enum (e.g. Clutter constants)</td>
<td>string</td>
<td>
<code class="code">CLUTTER_ALIGN_X_AXIS</code> =>
<code class="code">"CLUTTER_ALIGN_X_AXIS"</code> or <code class="code">"x-axis"</code>
(the latter is the GEnum nickname for the constant)
</td>
</tr><tr>
<td>ClutterColor</td>
<td>color string</td>
<td>
<code class="code">clutter_color_new (255, 0, 0, 255)</code> =>
<code class="code">"red"</code> or <code class="code">"#f00f"</code> or
<code class="code">"#ff0000ff"</code>; alternatively,
<code class="code">"#f00"</code> or <code class="code">"#ff0000"</code>
(implicitly sets alpha value to 255)
</td>
</tr><tr>
<td>ClutterActor (or other Clutter type)</td>
<td>object</td>
<td>
<code class="code">clutter_rectangle_new ()</code> =>
<code class="code">{ "type" : "ClutterRectangle" }</code>
</td>
</tr><tr>
<td>Property which takes a list or array of values</td>
<td>array of objects and/or IDs</td>
<td>
<code class="code">clutter_container_add_actor (stage, rectangle)</code> =>
<pre class="programlisting">{
"id" : "stage",
"type" : "ClutterStage",
...,
"children" : [
{
"id" : "rectangle",
"type" : "ClutterRectangle",
...
}
]
}</pre>
</td>
</tr><tr>
<td><code class="code">NULL</code></td>
<td><code class="code">null</code></td>
<td>-</td>
</tr></tbody></table></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="layouts-box.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="script-ui.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4. Arranging actors in a single row or column </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2. Defining a user interface with JSON</td></tr></table></div></body></html>