Guile-GNOME: Clutter version 0.8.0, updated 21 June 2008 Matthew Allum and OpenedHand LTD This manual is for (gnome clutter) (version 0.8.0, updated 21 June 2008) Copyright 2008 OpenedHand LTD Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the GNU Free Documentation License from the Free Software Foundation by visiting their Web site or by writing to: The Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA i Short Contents 1 Overview :::::::::::::::::::::::::::::::::::::::::::: 1 2 ClutterActor ::::::::::::::::::::::::::::::::::::::::: 2 3 ClutterAlpha :::::::::::::::::::::::::::::::::::::::: 33 4 ClutterBackend :::::::::::::::::::::::::::::::::::::: 35 5 ClutterBehaviourBspline :::::::::::::::::::::::::::::: 37 6 ClutterBehaviourDepth ::::::::::::::::::::::::::::::: 39 7 ClutterBehaviourEllipse ::::::::::::::::::::::::::::::: 41 8 ClutterBehaviourOpacity :::::::::::::::::::::::::::::: 44 9 ClutterBehaviourPath :::::::::::::::::::::::::::::::: 45 10 ClutterBehaviourRotate ::::::::::::::::::::::::::::::: 48 11 ClutterBehaviourScale :::::::::::::::::::::::::::::::: 51 12 ClutterBehaviour :::::::::::::::::::::::::::::::::::: 53 13 ClutterChildMeta :::::::::::::::::::::::::::::::::::: 56 14 ClutterCloneTexture :::::::::::::::::::::::::::::::::: 57 15 Colors ::::::::::::::::::::::::::::::::::::::::::::: 58 16 ClutterContainer::::::::::::::::::::::::::::::::::::: 61 17 Clutter Effects::::::::::::::::::::::::::::::::::::::: 64 18 ClutterEntry :::::::::::::::::::::::::::::::::::::::: 65 19 Events ::::::::::::::::::::::::::::::::::::::::::::: 72 20 GL Features :::::::::::::::::::::::::::::::::::::::: 76 21 Fixed Point Support :::::::::::::::::::::::::::::::::: 77 22 ClutterGroup ::::::::::::::::::::::::::::::::::::::: 78 23 ClutterLabel :::::::::::::::::::::::::::::::::::::::: 81 24 ClutterListModel :::::::::::::::::::::::::::::::::::: 87 25 General :::::::::::::::::::::::::::::::::::::::::::: 88 26 ClutterMedia:::::::::::::::::::::::::::::::::::::::: 92 27 ClutterModelIter::::::::::::::::::::::::::::::::::::: 95 28 ClutterModel:::::::::::::::::::::::::::::::::::::::: 96 29 ClutterRectangle ::::::::::::::::::::::::::::::::::::: 99 30 ClutterScore ::::::::::::::::::::::::::::::::::::::: 101 31 ClutterScriptable:::::::::::::::::::::::::::::::::::: 106 32 ClutterScript ::::::::::::::::::::::::::::::::::::::: 107 33 ClutterShader :::::::::::::::::::::::::::::::::::::: 112 34 ClutterStage ::::::::::::::::::::::::::::::::::::::: 115 35 ClutterTexture ::::::::::::::::::::::::::::::::::::: 122 ii 36 ClutterTimeline::::::::::::::::::::::::::::::::::::: 126 37 Unit conversion ::::::::::::::::::::::::::::::::::::: 134 38 Utilities ::::::::::::::::::::::::::::::::::::::::::: 136 39 Versioning Macros ::::::::::::::::::::::::::::::::::: 137 40 Undocumented ::::::::::::::::::::::::::::::::::::: 138 Type Index :::::::::::::::::::::::::::::::::::::::::::: 140 Function Index ::::::::::::::::::::::::::::::::::::::::: 141 Chapter 1: Overview 1 1 Overview (gnome clutter) wraps the Clutter graphical canvas toolkit for Guile. It is a part of Guile-GNOME. See the documentation for (gnome gobject) for more information on Guile-GNOME. Chapter 2: ClutterActor 2 2 ClutterActor Base abstract class for all visual stage actors. 2.1 Overview <clutter-actor> is a base abstract class for all visual elements on the stage. Every object that must appear on the main <clutter-stage> must also be a <clutter-actor>, either by using one of the classes provided by Clutter, or by implementing a new <clutter-actor> subclass. Every actor is a 2D surface positioned and optionally transformed in 3D space. The actor is positioned relative to top left corner of it parent with the childs origin being its anchor point (also top left by default). The actors 2D surface is contained inside its bounding box, described by the <clutter- actor-box> structure: (The missing figure, actor-box The actor box represents the untransformed area occupied by an actor. Each visible actor that has been put on a <clutter-stage> also has a transformed area, depending on the actual transformations applied to it by the developer (scale, rotation). Tranforms will also be applied to any child actors. Also applied to all actors by the <clutter-stage> is a perspective transformation. API is provided for both tranformed and untransformed actor geometry information. The 'modelview' transform matrix for the actor is constructed from the actor settings by the following order of operations: 1. 2. 3. 4. 5. 6. 7. 8. Translation by actor x, y coords, Scaling by scale x, scale y, Negative translation by anchor point x, y, Rotation around z axis, Rotation around y axis, Rotation around x axis, Translation by actor depth (z), Rectangular Clip is applied (this is not an operation on the matrix as such, but it is done as part of the transform set up). Chapter 2: ClutterActor 3 An actor can either be explicitly sized and positioned, using the various size and position accessors, like clutter-actor-set-x or clutter-actor-set-width; or it can have a pre- ferred width and height, which then allows a layout manager to implicitly size and position it by "allocating" an area for an actor. This allows for actors to be manipulate in both a fixed or static parent container (i.e. children of <clutter-group>) and a more automatic or dynamic layout based parent container. When accessing the position and size of an actor, the simple accessors like clutter- actor-get-width and clutter-actor-get-x will return a value depending on whether the actor has been explicitly sized and positioned by the developer or implicitly by the layout manager. Depending on whether you are querying an actor or implementing a layout manager, you should either use the simple accessors or use the size negotiation API. Clutter actors are also able to receive input events and react to them. Events are handled in the following ways: 1. 2. 3. 4. 5. 6. 7. 8. Actors emit pointer events if set reactive, see clutter-actor-set-reactive The stage is always reactive Events are handled by connecting signal handlers to the numerous event signal types. Event handlers must return `#t' if they handled the event and wish to block the event emission chain, or `#f' if the emission chain must continue Keyboard events are emitted if actor has focus, see clutter-stage-set-key-focus Motion events (motion, enter, leave) are not emitted if clutter-set-motion-events- enabled is called with `#f'. See clutter-set-motion-events-enabled documentation for more information. Once emitted, an event emission chain has two phases: capture and bubble. An emitted event starts in the capture phase (see ClutterActor::captured-event) beginning at the stage and traversing every child actor until the event source actor is reached. The emission then enters the bubble phase, traversing back up the chain via parents until it reaches the stage. Any event handler can abort this chain by returning `#t' (meaning "event handled"). Pointer events will 'pass through' non reactive overlapping actors. (The missing figure, event-flow Every '?' box in the diagram above is an entry point for application code. For implementing a new custom actor class, please read the corresponding section of the API reference. Chapter 2: ClutterActor 4 2.2 Usage <clutter-actor-box> [Class] Derives from <gboxed>. This class defines no direct slots. <clutter-geometry> [Class] Derives from <gboxed>. This class defines no direct slots. <clutter-actor> [Class] Derives from <clutter-scriptable>, <g-initially-unowned>. This class defines the following slots: name Name of the actor x X coordinate of the actor y Y coordinate of the actor width Width of the actor height Height of the actor fixed-x Forced X position of the actor fixed-y Forced Y position of the actor fixed-position-set Whether to use fixed positioning for the actor min-width Forced minimum width request for the actor min-width-set Whether to use the min-width property min-height Forced minimum height request for the actor min-height-set Whether to use the min-height property natural-width Forced natural width request for the actor natural-width-set Whether to use the natural-width property natural-height Forced natural height request for the actor natural-height-set Whether to use the natural-height property request-mode The actor's request mode Chapter 2: ClutterActor 5 allocation The actor's allocation depth Depth of actor clip The clip region for the actor has-clip Whether the actor has a clip set or not opacity Opacity of actor visible Whether the actor is visible or not reactive Whether the actor is reactive to events or not scale-x Scale factor on the X axis scale-y Scale factor on the Y axis rotation-angle-x The rotation angle on the X axis rotation-angle-y The rotation angle on the Y axis rotation-angle-z The rotation angle on the Z axis rotation-center-x The rotation center on the X axis rotation-center-y The rotation center on the Y axis rotation-center-z The rotation center on the Z axis anchor-x X coordinate of the anchor point anchor-y Y coordinate of the anchor point show-on-set-parent Whether the actor is shown when parented destroy [Signal on <clutter-actor>] The ::destroy signal is emitted when an actor is destroyed, either by direct invocation of clutter-actor-destroy or when