This file is indexed.

/usr/share/gtk-doc/html/clutter-cookbook/script.html is in libclutter-1.0-doc 1.24.2-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
<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 V1.78.1"><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#idp56994048">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#idp61056752">2.1. Problem</a></span></dt><dt><span class="section"><a href="script-ui.html#idp60313456">2.2. Solution</a></span></dt><dt><span class="section"><a href="script-ui.html#idp60332512">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#idp60336352">3.1. Problem</a></span></dt><dt><span class="section"><a href="script-signals.html#idp60337776">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#idp60976400">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#idp60989392">4.1. Problem</a></span></dt><dt><span class="section"><a href="script-state.html#idp60991152">4.2. Solution</a></span></dt><dt><span class="section"><a href="script-state.html#idp60999600">4.3. Discussion</a></span></dt><dt><span class="section"><a href="script-state.html#idp61079008">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="idp56994048"></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="idp57847728"></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::&lt;property name&gt;</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 =&gt; 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> =&gt; <code class="code">1.0</code></p>
              <p><code class="code">1e-1</code> =&gt; <code class="code">1e-1</code></p>
              <p><code class="code">1E-1</code> =&gt; <code class="code">1E-1</code></p>
              <p><code class="code">0.1E-1</code> =&gt; <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> =&gt; <code class="code">1</code></p>
              <p><code class="code">0x00</code> =&gt; <code class="code">0</code> (no hex in JSON)</p>
              <p><code class="code">01</code> =&gt; <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> =&gt; <code class="code">true</code></p>
              <p><code class="code">FALSE</code> =&gt; <code class="code">false</code></p>
            </td>
          </tr><tr>
            <td>gchar</td>
            <td>string</td>
            <td><code class="code">"hello world"</code> =&gt; <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> =&gt;
              <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> =&gt;
              <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> =&gt;
              <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> =&gt;
              <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>