Sections in the outline below were suggested by Emmanuele, in the order they should appear and with an outline of the minimum each should contain.
The plan divides sections into recipes and topics:
- Recipes explain how to achieve particular objectives (make a user interface do something, accept user input, do something with an actor etc.); they shouldn't just explain lumps of the API.
- Topics are parts of the Clutter API which it would be good to cover in recipes. However, recipes shouldn't be API-focused, but task-focused; and a given topic may make an appearance in one or more recipes. In some cases, topic material may be better in the API docs anyway. So we need to think of recipes which demonstrate topics, rather than just writing them up as topics and jamming them in the cookbook.
Recipes are what we want in the cookbook, but topics are included to give an idea of the areas of the Clutter API which should be given more exposure in recipes.
Legend:
- green entries are done and in master already.
- orange entries have been submitted as patches or merge requests but aren't in master; or are being actively worked on.
- red entries are prioritised for inclusion in the cookbook; currently highest priority is being given to the Animation and Layout management sections, but some other sections might get one or two recipes.
Cookbook outline
Actors
Recipes:
- Knowing when an actor position or size change (DONE)
- Overriding the paint sequence (DONE)
- Making an actor transparent (DONE)
- Explains a bit about opacity and how it's affected by container's transparency
- Shaped pick (non-rectangular actor) (DONE)
- Composing an actor from other actors (DONE)
- based on "subclassing" ClutterBox
- Implement a context menu on top of the scene by having a group at the top, group that the menu can be parented to
- Opacity on whole a group, painting the children offscreen first and then painting the buffer with the group opacity
- explain the issue with the default behaviour opacity on a group with children that have opacity themselves
- wait for an offscreen class? subclass group? implement this as part of group?
Topics:
- Preferred size
- Allocation
- Fixed size/position
- Implementing a container
- Paint order
- Implementing new actors (should we only derive from Actor? why not derive from Group, etc.?)
- Performance issues (best practices when building the scenegraph, managing Clutter textures, ...)
- Gradient opacity/colour
- Anchor points (move/set differences)
Events
Introduction:
- Need to expand the events introduction to talk about clutter_actor_set_reactive() generically, as it's applicable to all these recipes
- Also maybe explain general pattern for handling events, accessors for event properties (no need to cast)
Recipes:
- Handling key events (DONE)
- Detecting when the pointer moves over an actor (example could be a simple hover effect) (DONE)
- enter-event -> ClutterCrossingEvent
- leave-event -> ClutterCrossingEvent
- motion-event -> ClutterMotionEvent
- Detecting a mouse scroll on an actor (example could demonstrate scrolling the clip area of an actor) (DONE)
- scroll-event -> ClutterScrollEvent
- Making an actor respond to mouse buttons (DONE)
- button-press-event -> ClutterButtonEvent
- button-release-event -> ClutterButtonEvent
- ClutterClickAction = press + release
- An example of a synthetic event: Emit BUTTON_PRESS/_RELEASE events with the current coords of the pointer when pressing enter
Topics:
- Detecting enter/leave events on children
- For hover effects on a container when the pointer is on a child
- Drag and drop (ClutterDragAction)
- Capturing events
- Bubbling events
- Emitting events
Textures
Recipes:
- Drawing 2D graphics onto a texture (DONE)
- Maintaining the aspect ratio when loading an image into a texture (DONE)
- Loading image data into a texture (DONE)
- Creating sub textures from a ClutterTexture (DONE)
- Cross-fading between two textures (has been requested on the mailing list and discussed widely recently) (DONE)
- recipe covers two texture and one texture approaches
- basic approach I discussed with Pippin:
- two textures, one placed above the other (e.g. in a ClutterBinLayout)
- load image into the "top" texture
- when loading a second image, set the Cogl texture of the "bottom" texture to that of the top; set transparency of the top to 0; fade in the top to fully opaque
- need to change this approach (e.g. fade out the background texture) if the new image is of a different size or if the top texture is partially transparent
- Updating the data in a texture
- Using clutter_texture_get_cogl_texture() and clutter_texture_set_cogl_texture()
- Highlighting a texture (for instance for mouse over effects)
Topics:
- Scaling
- Mipmapping
- Internals
Animation
Introduction (DONE):
- focuses on:
- implicit animations (clutter_actor_animate())
- ClutterAnimator
- ClutterState
- other parts of the API like ClutterConstraint may be covered under various recipes
- ClutterBehaviour won't get any focus; ClutterAnimator is not recommended for use by application developers, as it's generally intended for toolkit builders
Recipes:
- Inverting an animation (DONE)
- using a timeline and reversing it on "completed" signal being emitted (so you don't need to code the inverse animation)
- "rolling back" an animation: pause it and change its direction
- ClutterState could also be considered for this
- Fading an actor in/out (DONE)
- clutter_actor_animate() for simple animations of opacity property
- also covers ClutterState briefly
- Rotating an actor (DONE)
- Creating complex animations (aka using ClutterAnimator) (DONE)
- Applying the same animation to different actors (DONE)
- a good reason to use ClutterScript to define the animation, creating an animation "rig" which actors can be parented to when they need to be animated; inspired by code in pinpoint
- probably best to do a ClutterScript recipe first, as ClutterAnimator is easier to use from script than through C API
- Moving actors (DONE)
- x,y,z
- the effect of depth on scale and x,y position; perspective
- Looping an animation (DONE)
- Animated scaling of an actor (DONE)
- Using ClutterPath (for curved animation paths) (DONE)
Topics:
(Some of this material is already in the reference guide, and could move to the cookbook instead, maybe)
- Animating multiple actors
- demonstrate how to move between different UI layouts using ClutterState/ClutterAnimator
- Dynamically-generated animations (e.g. based on user interactions with the UI)
- what it does which can't be achieved any other way; perhaps programmatically building up an animation, e.g. add rotation in one direction if one key pressed, then add rotation in another direction when another is pressed, while the animation is running?
- Animating the offset property on a ClutterPathConstraint
- Also mentions and gives small example of curved animation paths just via non-linear easing modes
- Animating colour/effects/other properties
- Probably multiple recipes...
- General point: if the easing mode returns an alpha > 1.0, this may put the property you're scaling out of range (e.g. if you are animating to opacity 255 using CLUTTER_EASE_IN_OUT_ELASTIC, opacity may go > 255 during the animation)
- Custom easing modes
Text
Topics:
- Drawing a shadow (DONE)
- Text entry
- Centering text, multiline text, creating a text entry widget
- Alignment
- Attributes
Layout management
Introduction (DONE):
- Which layout when?
- Layout properties
- how properties of children are set through parent
- Some terminology
- Alignment (x and y)
- Reflowing
- Vertical/horizontal pack/add
- Homogenous rows/columns
- Row/column spacing
- Row/column height/width
- Expand and fill
- Animation of layouts
Recipes:
- Stacking actors on top of each other (DONE)
- stacking actors using ClutterBinLayout
- Binding the size of one actor to the size of another (aka "size tracking") (DONE)
- because this is best done using constraints, and/or with allocation-changed, this could live in "layout management" (maybe)
- perhaps call it "synchronizing an actor with its container", and cover both alignment and binding together
- use ClutterBindConstraint if the actor should be the same size as its container
- use allocation-changed if you need the child to be some % of its container's size
- also cover fitting an actor inside the stage when the stage is resized (the stage is just another actor)
- Arranging actors in a single row or column (DONE)
- using ClutterBoxLayout
- implementing a menu or a toolbar with box layout; NB flow layout might be better for a toolbar, in cases where window is resizable (for example)
- Arranging actors in multiple (reflowing) rows and columns (files? whatever the proper word is for a row or a column)
- Binding the position of one actor to the position of another
- ClutterBindConstraint on x,y,z axes
- Aligning actors with each other
Topics:
- Table (?once it exists)
- LayoutManager (implementing your own)
- SnapConstraint
Script
Introduction (DONE)
- brief overview of why ClutterScript is useful
Recipes:
- Defining a user interface with JSON (DONE)
- basics of ClutterScript for loading UI definition
- externalise UI definition in JSON to make it simpler to refactor
- started with this rather than ClutterAnimator, as the latter suggests using ClutterScript, and it would be good to be able to refer to a recipe for that before explaining how to use it with ClutterAnimator
- Connecting to signals (DONE)
Topics:
- Merge/unmerge
- Using constraints in the JSON definition
- Setting child and layout properties
- Adding custom properties
Effects
Introduction (DONE):
- describes the effects API in overview, and shows how to apply one of the built-in effects
- this was written in tandem with the deform effect recipe, as it didn't make much sense or serve much purpose until it accompanied at least one recipe
Recipes:
- Creating a custom deform effect (DONE)
Topics:
- Basic effect (Elliot: started work on a simple highlight effect which puts a border on top of an actor via post_paint(); and example of a separate background effect with pre_paint(); branch @ http://gitorious.org/clutter-cookbook/clutter-cookbook/commits/cookbook-effects-basic; logged merge request @ http://bugzilla.clutter-project.org/show_bug.cgi?id=2610)
- Add a Cogl drawing on top of an actor
- Creating a drop-shadow effect
- Demonstrates how to use paint volumes to create an effect which draws outside an actor's allocation: get the actor's allocation then add some padding to allow for the drop shadow; may need some fancy blending to make the shadow edges look nice
- ClutterBlurEffect gives an example of changing the paint volume in an effect
- check that pre_paint() doesn't have access to the painted actor, but post_paint() does (not sure if it does or doesn't)
- Offscreen effects
- Shaders (Elliot: I've simplified ClutterColorizeEffect and made it a ClutterShaderEffect subclass - might make an interesting recipe?)
General things to improve the cookbook
- Cross-link to API docs properly (elliot: started some rough work on supporting olinks to Clutter API reference - see http://gitorious.org/clutter-cookbook/clutter-cookbook/commits/cookbook-olinking)
- Make formatting consistent and documented (e.g. same style for referencing functions throughout) (DONE)
- Support inclusion of video in recipes (DONE - see "Contributions" appendix for how to make use of this)
- Add note to "Contributing" section about how to include sample code (DONE)
- Populate doc/cookbook/examples directory with source code for all recipes (where it's available)
- Re take the screen-shots without window decorations