This recipe explains how to "reuse" the same animation
definition for different actors, by creating a new
instance of a "rig" (empty container) and animation
for the rig each time the animation is required.
An actor is then re-parented to the rig and animated
using it, rather than being animated directly.
JSON is used to define the rig + animator, to make
creating new instances of them simpler. The recipe
also discusses various caveats around using this
approach, rather than directly animating an actor.
Modified the "animation reuse" sample code to provide
a simpler example to explain in the recipe.
Also modified variable names to mirror the names used
for the previous "complex animation" example and added
some more comments, to further simplify and support the
recipe.
With some help from pippin, moved variable declarations
into more sensible positions within their functions,
changed a function name, and found a better way
to unref a script once its associated actor has
been destroyed.
Extracted the animation into its own JSON definition,
then create a new script and get the animation each
time a rectangle is clicked.
Removes the need to reparent onto the background and
copy property values to the rectangle after the animation,
and generally much cleaner.
Added an example showing how to reuse a ClutterAnimator
instance to animate multiple actors at different times
using an animatable rig, combined with reparenting.
Uses ClutterAnimator to implement a reasonably complex
animation of a single actor (movement along a path with
simultaneous scaling).
Provides a metaphor for thinking about ClutterAnimator
animations (stage directions) and explains keys and key
frames in some depth. Also compares ClutterAnimator
with other possible approaches to this type of animation
(implicit animations, ClutterState).
Added another JSON example to show how transitions can
be easily overlapped when using ClutterAnimator (two
sequences of 5 transitions, simultaneous with two
sequences of 1 transition).
Modified the C JSON loader program so it can be used with
this example as well.
Added a recipe explaining how to connect signals to handlers
in the JSON definition used by ClutterScript; also shows
how to connect the signals in code once the JSON has been
loaded.
Includes guidelines on writing handlers (i.e. need to use
-export-dynamic and non-static functions) and example
which connects a handler for motion events on a rectangle.
GEnum nicknames can be used to set properties in JSON
definitions, so added a callout to the JSON example explaining
this, and showing how to derive the nickname for an enumeration
value.
Modified the example code to use nicknames as well.
As JSON can make use of nicknames for GEnum properties,
mentioned this in the table mapping C property values
to their JSON equivalents (as the nick name is a much
shorter and cleaner way of setting a property in JSON).
Wrote an introduction to using ClutterScript with JSON. Focus
is on explaining why you might want to use it, basic principles
of operation (with annotated JSON sample), and how to map
data types from C to JSON.
Written simultaneously with a short recipe (uses the same sample
code) showing how to load a JSON file and retrieve objects
from it in code.
Commented the ClutterScript example so it can be used
inline as part of the recipe, rather than as an
example in the appendix (it's too simple to warrant
a separate appendix).
New script chapter needs an introduction.
While writing the introduction, also slightly changed the
emphasis of the recipe (towards refactoring an existing
application to use ClutterScript) and incorporated example
code into documentation.
Set a parameter on the XSLT transform so that callout elements
are rendered as text rather than graphics (removes the need
to add callout graphics to the build).
There was too much in the example code to cover in a single
recipe, so I trimmed it down to demonstrate simple
UI building (no constraints, effects, animations, or signals).
Added a simple script and program to load it, to support
recipe on ClutterScript for UI definitions.
Also amended the Makefile (following the pattern of
the tests/interactive Makefile) to enable signal
connection from ClutterScript by passing -export-dynamic
to linker.
* elliot/cookbook-textures-crossfade:
cookbook: Use GdkPixbuf instead of getting data from a texture
cookbook: Added a recipe for cross-fading between two images
cookbook: Modified COGL example for consistency
cookbook: Added video of two texture cross-fade
cookbook: Removed unused constant
cookbook: Renamed front/back to top/bottom in cross-fade example
cookbook: Don't need to set keep-aspect-ratio for simple example
cookbook: Modified ordering of statements in cross-fade example
cookbook: Added a longer slideshow example
cookbook: Made code examples more consistent
cookbook: Added example code for texture cross-fading
Post-release version bump to 1.3.13
Release Clutter 1.3.12 (developers snapshot)
Conflicts:
doc/cookbook/examples/Makefile.am
Added a recipe about handling enter, leave, and motion events
on an actor.
Gives some pointers to data available from motion events,
explains a bit about stage-relative and actor-relative coords,
and covers how overlapping actors and reactivity of actors
can affect events occurring.
Examples include a simple scribble app showing how to integrate
pointer events into a more useful context.
Added another example (used for a screenshot) to demonstrate
how pointer events pass through non-reactive actors and how
depth ordering affects whether an actor will emit a pointer
motion signal.
Use clutter_event_get_coords() to get x and y position,
rather than casting to the right event type then directly
accessing members of the event struct.
Decided might be better to cover crossing and motion under
a broader "pointer motion" recipe, so renamed the example
(which only shows pointer crossing event handling).
Rewrote example for single texture + COGL to use
a GdkPixbuf to load images, rather than reading data
out of another CoglTexture.
The data is then loaded from the pixbuf to a region of
the CoglTexture (as before).
The recipe covers a two texture approach (using the Clutter API)
and a single texture approach (using COGL).
It also discusses issues with cross-fading between images of
different sizes with the COGL API, and gives a longer
example of cycling through multiple images in a slideshow
application.
Added a video showing the two texture cross-fade.
Modified the example code to animate on key press, so
this video could be captured.
Also altered the stage size to minimise the video size.
Front/back seems like the wrong terminology when discussing
actors arranged in layers. Top/bottom fits better with Clutter
API function names and other recipes, so renamed variables.
Cross-fading between two images is straightforward,
but cycling between more than two is more efficient
if done by copying COGL textures between the
two textures, rather than trying to reposition the
textures.
The example demonstrates how to reuse a pair of
textures to cycle through multiple images.
Modified the code example for the Clutter API version
of the cross-fade to use the same command line
as the COGL version.
This also simplifies the explanation in the recipe.
Also made the COGL code sample more consistent with
the Clutter API code sample.
Added simple image viewer which loads image file names
from a directory, displays the first one, then displays
the next in the list with each key press. Uses the
primitive fade front in/fade back out approach.
Also adapted Emmanuele's example code which uses Cogl
to produce a similar effect, but within a single texture.
This code loads two images specified on the command
line and cross-fades between them.
The tests/accessibility, tests/micro-bench and the examples directory
in the coobook create a lot of non-installed binaries. Since we know who
they are, and we ignore them, we can auto-generate the ignore files as
well.
The rest of Clutter is covered by the main ignore file.
Added some extra explanation, referencing the sample code, to
try to make the scrollable actor example easier to follow. Basically
demonstrates the principles described in the paragraph about
setting the y coordinate for the scrollable actor, but using actual
numbers.
Added a new recipe for creating a non-rectangular
actor using ClutterPath (aka "shaped pick") and
the Cogl primitives API.
Also cleaned up XML alignment in the actors.xml
file.
The generated cookbook files (either HTML or PDF) do not only depend on
clutter-cookbok.xml but also on all the chapters that compose the
cookbook. Add this dependency to the Makefile rules to have make rebuild
the book when a chapter changes.
Since XML_FILES is now the list of source files, move recipe-template.xml
to EXTRA_DIST.
New recipe covering how to animate rotation of
an actor (in all axes).
Covers various factors affecting rotation animation
(like orientation of axes, parent rotation/orientation),
as well as trying to make rotations easier to visualise
(e.g. describing how rotation direction is affected by
those factors, how a rotation can be expected to look
when animated). Uses implicit animations for code examples.
Also refers to a full code example which uses ClutterState.
The simple key press example in the cookbook used a brittle
and incorrect switch statement to test modifier values. Instead,
use logical "&" of the state with the modifiers we're interested
in to check which keys were pressed.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2223
The cookbook should also include fully functional code examples. We can
even XInclude them into the docbook XML itself.
The examples should be built with the coobook, so that we can always
make sure they are up to date.
* elliot/cookbook-include-videos:
cookbook: Tweak so that videos sit inside a paragraph for better spacing
docs: Note the P_() macro in the HACKING file
cookbook: Added support for inline video
Conflicts:
doc/cookbook/Makefile.am
Explains how to make an actor transparent so that other actors
are visible through it.
Also explains a bit more generally about opacity and how
it's computed from the actor, container, and color; and how actor
visibility is affected by depth (fog) and depth order.
Amended Makefile to copy content of videos directory into
installation directories. Also copies videos and images
into the html/ directory during the build, so that the
built cookbook can be viewed locally (for testing without
having to install).
Added an XSLT template to transform Docbook <inlinemediaobject>
elements into HTML 5 <video> elements, with a fallback to
link to the video displayed for browsers without HTML 5 support.
Added note to "Contributing" appendix explaining how to put
video into a recipe.
Introduces basic concepts (timelines, alphas, frames)
common to different parts of the Clutter animation API.
Gives a high level overview of the three different
approaches to animation (implicit, ClutterAnimator,
ClutterState).
Added a new recipe (based on the skeleton in the
animations section of the cookbook) about inverting
an animation by reversing the direction of its timeline.
Uses clutter_actor_animate() as the basic approach,
but mentions ClutterState and ClutterAnimator as well.
I had changed the build so CSS files get put into
the HTML build directory; but done it in such
a way that they were then being ignored during
install. Fixed this.
There was a note about constants for keys and
where they are defined in Clutter header files; but
the sentence about where key modifiers are defined
was outside the note. Logically, they belong
together.
In some cases, there were blocks of text which
were really asides/interrupts to the flow, but
which weren't explicitly marked as such. I fixed
them by turning them into <note> blocks.
Made usage of docbook elements consistent across
recipes; to ensure the conventions are kept by others,
added a section about how to write and style recipes.
Create two HTML versions of the cookbook:
• single page
• multiple pages
Use the online version of the DocBook XHTML XSL, and disable the PDF
generation until we can restore it.
Use a modified version of the Poky Handbook CSS for the HTML version of
the Cookbook.
Promote Elliot as author.
Re-license from the GPLv2.0 to the CC BY-NC-SA 2.0.
Apparently, xsltproc recognizes a directory if it has a '/' at the end
of its path, and not by doing the sensible thing and stat()'ing the
argument for the --output option.
Attached patch contains a cookbook recipe about key press event
handling.
It covers both a simple approach (connecting a callback to a
key-press-event signal which manually analyses the key and
modifiers), and a more complicated one based on a binding pool.
There's also some discussion of the two approaches.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2162
Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>
The cookbook contains a commented-out recipe covering scaling images
inside a texture while retaining their aspect ratio; the attached
patch fleshes out this recipe.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2163
Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>
The Clutter cookbook has a chapter for textures. It would be useful to
provide a recipe on simple uses of ClutterCairoTexture as part of that.
Some suggested content is attached.
• Make the manual a DevHelp book
• Make the generation of PDFs of the cookbook and the manual optional
• Consequently, make the hard dependency on jw optional
• Clean up the checks and build for the additional documentation
Instead of creating stand-alone HTML files, use XSLT to transform the
DocBook into a DevHelp file, so that we can read the Cookbook inside
DevHelp -- just like the API reference.
The first recipe shows how to be notified when the relative position
and size of an actor changes using the notify:: signal on the actor's
dimensional and positional properties.
The "Clutter Cookbook" is a document designed to contain solutions
to common problems applications developers might encounter when using
Clutter. It is meant as a companion to the API reference but it
requires knowledge of the Clutter API and framework.
