Hi; Attached are some rough notes for documentation Im half way through, which hopefully clear up some things and give clarity to some features. Wanted to spend a bit more time on this before submitting but getting worried as to attention tutorial is seeking when in such an earlier state - i.e it could cause more confusion than good.
Also I would strongly recommend (if not already) you try and create a medium size clutter application as to more understand why parts of the API are the way they are. Things like timelines, behaviours etc went through many iterations of design and practical use before settling on what they currently are. (Not meaning to sound non appreciative here btw) Many thanks; == Matthew On Thu, 2007-12-13 at 13:58 +0100, Murray Cumming wrote: > On Thu, 2007-12-13 at 13:54 +0200, Tommi Komulainen wrote: > [snip stuff I'll do. thanks] > > How is memory management for timelines meant to be done, i.e. when is > > it safe to unref a timeline? (Just had a situation where I wanted to > > make a fire and forget timeline and timeline_new(); start(); unref(); > > didn't actually complete the timeline.) > > I guess that should be made clearer in the API reference too. You could > unref it after the mainloop has stopped but in the real world you'd > actually want to unref it when the timeline stops, which means handling > its completed signal, which would be tedious. > > I'll investigate. > > -- > [EMAIL PROTECTED] > www.murrayc.com > www.openismus.com >
Clutter is a retained mode graphics API. User interfaces are built in clutter by relating, combining and manipulating multiple visual layers called 'Actors' into a persistant scene graph. XXX Mention main loop, events etc here > [Exploded diagram of simple interface showing actor layers] An 'Actor' is essentially a 2D quad that can be; - positioned in 3D space via an origin offset (by defualt 0,0). - rotated in 3D space around points relative the the actors origin - sized. - scaled. - clipped. - made transparent. - hidden/shown. - stacked in respect to others. - grouped with others. - parented and contain children. - made 'reactive' as to recieve input events. When an actor has children, those are positioned relative to there parent. Any tranforms applied to that parent also apply to the child. Every clutter application automatically has a stage created for it. The stage is the top level 'actor' - essentially the canvas or window to which child actors are added. Other types of actors included with clutter include images, solid rectangle, groups, text blocks and more. You can also of course create new or composite types of actors. All actors can respond to user input by means of event signals. Callbacks can attached to actors for various event types. Input events are handled initially by the stage the event will enter a capture phase continue down through children to the 'source' actor of the event (for example the actor that was clicked on) before then entering the 'bubble' phase going back up through parents to the stage. The event can be stopped at any stage by an actor in the event pipeline. [event handling diagram somehow] Actors only recieve input events if certain conditions are met. To receive pointer events an actor must be made reactive, for keyboard events the actor must have key focus. Actors can also get exclusive access to any events by grabbing either the pointer or the keyboard. Actor attributes can be modified as a function of time as to produce animations. At the base of all Clutter animations is the 'Timeline' - A timeline is a defined period of time with a number of frames. Signals are emmitted when a new frame is reached. Code can be bound to such signal to modify actor attributes and thus produce simple animations. Clutter Alphas are functions of time. Referencing a timeline and a function they produce a value between 0 and CLUTTER_ALPHA_MAX dependant on the referenced timelines current position. Such functions include ramps and waves. Clutter effects .... Other. =====
