Alfred Hitchcock 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".

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 ("Where did I set the color of that rectangle?") and make sure your edits don't break any behaviour. Other 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. ClutterScript enables a similar separation: you can define the UI declaratively using JSON; then load the UI from the JSON and handle interactions with it through Clutter code (in C, Python, Vala or some other language). This has several benefits, including: Separation of UI element declarations from control logic (see above). More concise code: typically, describing a UI in JSON requires far fewer characters than the equivalent procedural code. 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. Creating and configuring some objects (e.g. animations, layouts) becomes much simpler in JSON. Less compilation (if you're using a compiled language): because you can edit the UI by editing external JSON files, you can make changes to it without needing to recompile the whole application. The ClutterScript API reference describes many of its useful features. However, the following sections are intended to give an overview of how ClutterScript works, and how to use it in an application. The recipes in this chapter give more detail about particular aspects of ClutterScript, such as how to connect signals and how merge multiple JSON definitions in a single script.

Clutter is built on top of GObject, an object system for C. As in other object systems, properties are fundamental to GObject. ClutterScript effectively provides a way to create instances of GObjects and set their properties. For example: [ { "id" : "stage", "type" : "ClutterStage", "is-default" : true, "width" : 400, "height" : 400, "color" : "#333355ff", "children" : [ "box" ] }, { "id" : "box", "type" : "ClutterBox", "width" : 400, "height" : 400, "layout-manager" : { "type" : "ClutterBinLayout", "x-align" : "CLUTTER_BIN_ALIGNMENT_CENTER", "y-align" : "CLUTTER_BIN_ALIGNMENT_CENTER" }, "children" : [ { "id" : "rectangle", "type" : "ClutterRectangle", "width" : 200, "height" : 200, "color" : "red" } ] } ] N.B. The numbers in brackets in the example further explain the JSON structure, and are not part of the UI definition. See below for more details. list bracket??? object bracket??? ID??? type??? color??? referencing a child by ID??? no ID for implicit objects??? embedded child??? color??? Once you grasp that Clutter objects are GObjects, and you are setting their properties, you can determine what is scriptable by referring to the Properties sections in the Clutter API reference. Any of the properties described there can be set using ClutterScript.

The next important consideration is the data type of the property.??? null, float, int, string, color special properties which aren't obvious: layout::* ??? perhaps leave to the appropriate recipe properties with multiple values??? e.g. children, constraints objects as property values??? referencing by ID??? objects without IDs???

???

???

???converting an existing program to ClutterScript

a code sample should be here... but isn't a code sample should be here... but isn't