Next: , Previous: ClutterStage, Up: Top

63 ClutterState

State machine with animated transitions

63.1 Overview

<clutter-state> is an object controlling the tweening of properties on multiple actors between a set of named states. <clutter-state-key>s define how the properties are animated. If the source_state_name for a key is NULL it is used for transition to the target state unless a specific key exists for transitioning from the current state to the requested state.

The following example defines a "base" and a "hover" state in a <clutter-state> instance. 

     
     ClutterState *state = clutter_state_new ();
     ClutterColor color = { 0, };
     
     /&#x002A; transition from any state to the "base" state &#x002A;/
     clutter_color_from_string (&color, "rgb(255, 0, 0)");
     clutter_state_set (state, NULL, "base",
                        actor, "color", CLUTTER_LINEAR, &color,
                        actor, "scale-x", CLUTTER_EASE_IN_BOUNCE, 1.0,
                        actor, "scale-y", CLUTTER_EASE_IN_BOUNCE, 1.0,
                        NULL);
     
     /&#x002A; transition from the "base" state to the "hover" state &#x002A;/
     clutter_color_from_string (&color, "rgb(0, 0, 255)");
     clutter_state_set (state, "base", "hover",
                        actor, "color", CLUTTER_LINEAR, &color,
                        actor, "scale-x", CLUTTER_EASE_OUT_BOUNCE, 1.7,
                        actor, "scale-y", CLUTTER_EASE_OUT_BOUNCE, 1.7,
                        NULL);
     
     /&#x002A; the default duration of any transition &#x002A;/
     clutter_state_set_duration (state, NULL, NULL, 500);
     
     /&#x002A; set "base" as the initial state &#x002A;/
     clutter_state_warp_to_state (state, "base");

The actor then uses the <clutter-state> to animate through the two states using callbacks for the <"enter-event"> and <"leave-event"> signals. 

     
     static gboolean
     on_enter (ClutterActor *actor,
               ClutterEvent *event,
               ClutterState *state)
     {
       clutter_state_set_state (state, "hover");
     
       return TRUE;
     }
     
     static gboolean
     on_leave (ClutterActor *actor,
               ClutterEvent *event,
               ClutterState *state)
     {
       clutter_state_set_state (state, "base");
     
       return TRUE;
     }

63.2 ClutterState description for <clutter-script>

<clutter-state> defines a custom transitions property which allows describing the states.

The transitions property has the following syntax: 

     
     {
       "transitions" : [
         {
           "source" : "<source-state>",
           "target" : "<target-state>",
           "duration" : <milliseconds>,
           "keys" : [
             [
               "<object-id>",
               "<property-name>",
               "<easing-mode>",
               "<final-value>",
             ],
             [
               "<object-id>",
               "<property-name>",
               "<easing-mode>",
               "<final-value>",
               <pre-delay>,
               <post-delay>
             ],
             ...
           ]
         },
         {
           "source" : "<source-state>",
           "target" : "<target-state>",
           "duration" : <milliseconds>,
           "animator" : "<animator-definition>"
         },
         ...
       ]
     }

Each element of the transitions array follows the same rules as clutter-state-set-key.

The source and target values control the source and target state of the transition. The key and animator are mutually exclusive. The pre-delay and post-delay values are optional.

The example below is a translation into a <clutter-script> definition of the code in the example above. 

     
     {
       "id" : "button-state",
       "type" : "ClutterState",
       "duration" : 500,
       "transitions" : [
         {
           "source" : "*",
           "target" : "base",
           "keys" : [
             [ "button", "color", "linear", "rgb(255, 0, 0)" ],
             [ "button", "scale-x", "easeInBounce", 1.0 ],
             [ "button", "scale-y", "easeInBounce", 1.0 ]
           ]
         },
         {
           "source" : "base",
           "target" : "hover",
           "keys" : [
             [ "button", "color", "linear", "rgb(0, 0, 255)" ],
             [ "button", "scale-x", "easeOutBounce", 1.7 ],
             [ "button", "scale-y", "easeOutBounce", 1.7 ]
           ]
         }
       ]
     }

<clutter-state> is available since Clutter 1.4.

63.3 Usage

— Function: clutter-state-new ⇒  (ret <clutter-state>)

Creates a new <clutter-state>

ret
the newly create <clutter-state> instance
— Function: clutter-state-set-state (self <clutter-state>) (target_state_name mchars) ⇒  (ret <clutter-timeline>)
— Method: set-state

Change the current state of <clutter-state> to target-state-name.

The state will animate during its transition, see <clutter-state-warp-to-state> for animation-free state switching.

Setting a ‘#f’ state will stop the current animation and unset the current state, but keys will be left intact.

state
a <clutter-state>
target-state-name
the state to transition to
ret
the <clutter-timeline> that drives the state transition. The returned timeline is owned by the <clutter-state> and it should not be unreferenced.

Since 1.4

— Function: clutter-state-get-state (self <clutter-state>) ⇒  (ret mchars)
— Method: get-state

Queries the currently set target state.

During a transition this function will return the target of the transition.

This function is useful when called from handlers of the <"completed"> signal.

state
a <clutter-state>
ret
a string containing the target state. The returned string is owned by the <clutter-state> and should not be modified or freed

Since 1.4

— Function: clutter-state-warp-to-state (self <clutter-state>) (target_state_name mchars) ⇒  (ret <clutter-timeline>)
— Method: warp-to-state

Change to the specified target state immediately with no animation.

See clutter-state-set-state.

state
a <clutter-state>
target-state-name
the state to transition to
ret
the <clutter-timeline> that drives the state transition. The returned timeline is owned by the <clutter-state> and it should not be unreferenced.

Since 1.4

— Function: clutter-state-set-key (self <clutter-state>) (source_state_name mchars) (target_state_name mchars) (object <gobject>) (property_name mchars) (mode unsigned-int) (value <gvalue>) (pre_delay double) (post_delay double) ⇒  (ret <clutter-state>)
— Method: set-key

Sets one specific end key for a state name, object, property-name combination.

state
a <clutter-state> instance.
source-state-name
the source transition to specify transition for, or ‘#f’ to specify the default fallback when a more specific source state doesn't exist.
target-state-name
the name of the transition to set a key value for.
object
the <gobject> to set a key for
property-name
the property to set a key for
mode
the id of the alpha function to use
value
the value for property_name of object in state_name
pre-delay
relative time of the transition to be idle in the beginning of the transition
post-delay
relative time of the transition to be idle in the end of the transition
ret
the <clutter-state> instance, allowing chaining of multiple calls.

Since 1.4

— Function: clutter-state-set-duration (self <clutter-state>) (source_state_name mchars) (target_state_name mchars) (duration unsigned-int)
— Method: set-duration

Sets the duration of a transition.

If both state names are ‘#f’ the default duration for state is set.

If only target-state-name is specified, the passed duration becomes the default duration for transitions to the target state.

If both states names are specified, the passed duration only applies to the specified transition.

state
a <clutter-state>
source-state-name
the name of the source state, or ‘#f’.
target-state-name
the name of the target state, or ‘#f’.
duration
the duration of the transition, in milliseconds

Since 1.4

— Function: clutter-state-get-duration (self <clutter-state>) (source_state_name mchars) (target_state_name mchars) ⇒  (ret unsigned-int)
— Method: get-duration

Queries the duration used for transitions between a source and target state pair

The semantics for the query are the same as the semantics used for setting the duration with clutter-state-set-duration

state
a <clutter-state>
source-state-name
the name of the source state to get the duration of, or ‘#f’.
target-state-name
the name of the source state to get the duration of, or ‘#f’.
ret
the duration, in milliseconds

Since 1.4

— Function: clutter-state-get-states (self <clutter-state>) ⇒  (ret glist-of)
— Method: get-states

Gets a list of all the state names managed by this <clutter-state>.

state
a <clutter-state> instance.
ret
a newly allocated <g-list> of state names. The contents of the returned <g-list> are owned by the <clutter-state> and should not be modified or freed. Use g-list-free to free the resources allocated by the returned list when done using it.

Since 1.4

— Function: clutter-state-get-keys (self <clutter-state>) (source_state_name mchars) (target_state_name mchars) (object <gobject>) (property_name mchars) ⇒  (ret glist-of)
— Method: get-keys

Returns a list of pointers to opaque structures with accessor functions that describe the keys added to an animator.

state
a <clutter-state> instance.
source-state-name
the source transition name to query, or ‘#f’ for all source states.
target-state-name
the target transition name to query, or ‘#f’ for all target states.
object
the specific object instance to list keys for, or ‘#f’ for all managed objects.
property-name
the property name to search for, or ‘#f’ for all properties.
ret
a newly allocated <g-list> of <clutter-state-key>s. The contents of the returned list are owned by the <clutter-state> and should not be modified or freed. Use g-list-free to free the resources allocated by the returned list when done using it.

Since 1.4

— Function: clutter-state-remove-key (self <clutter-state>) (source_state_name mchars) (target_state_name mchars) (object <gobject>) (property_name mchars)
— Method: remove-key

Removes all keys matching the search criteria passed in arguments.

state
a <clutter-state> instance.
source-state-name
the source state name to query, or ‘#f’ for all source states.
target-state-name
the target state name to query, or ‘#f’ for all target states.
object
the specific object instance to list keys for, or ‘#f’ for all managed objects.
property-name
the property name to search for, or ‘#f’ for all properties.

Since 1.4

— Function: clutter-state-get-timeline (self <clutter-state>) ⇒  (ret <clutter-timeline>)
— Method: get-timeline

Gets the timeline driving the <clutter-state>

state
a <clutter-state>
ret
the <clutter-timeline> that drives the state change animations. The returned timeline is owned by the <clutter-state> and it should not be unreferenced directly.

Since 1.4

— Function: clutter-state-set-animator (self <clutter-state>) (source_state_name mchars) (target_state_name mchars) (animator <clutter-animator>)
— Method: set-animator

Specifies a <clutter-animator> to be used when transitioning between the two named states.

The animator allows specifying a transition between the state that is more elaborate than the basic transitions allowed by the tweening of properties defined in the <clutter-state> keys.

If animator is ‘#f’ it will unset an existing animator.

<clutter-state> will take a reference on the passed animator, if any

state
a <clutter-state> instance.
source-state-name
the name of a source state
target-state-name
the name of a target state
animator
a <clutter-animator> instance, or ‘#f’ to unset an existing <clutter-animator>.

Since 1.4

— Function: clutter-state-get-animator (self <clutter-state>) (source_state_name mchars) (target_state_name mchars) ⇒  (ret <clutter-animator>)
— Method: get-animator

Retrieves the <clutter-animator> that is being used for transitioning between the two states, if any has been set

state
a <clutter-state> instance.
source-state-name
the name of a source state
target-state-name
the name of a target state
ret
a <clutter-animator> instance, or ‘#f’.

Since 1.4

— Function: clutter-state-key-get-object (self <clutter-state-key>) ⇒  (ret <gobject>)

Retrieves the object instance this <clutter-state-key> applies to.

state-key
a <clutter-state-key>
ret
the object this state key applies to.

Since 1.4

— Function: clutter-state-key-get-property-name (self <clutter-state-key>) ⇒  (ret mchars)

Retrieves the name of the property this <clutter-state-key> applies to

state-key
a <clutter-state-key>
ret
the name of the property. The returned string is owned by the <clutter-state-key> and should never be modified or freed

Since 1.4

— Function: clutter-state-key-get-mode (self <clutter-state-key>) ⇒  (ret unsigned-long)

Retrieves the easing mode used for state-key.

state-key
a <clutter-state-key>
ret
the mode of a <clutter-state-key>

Since 1.4

— Function: clutter-state-key-get-value (self <clutter-state-key>) (value <gvalue>) ⇒  (ret bool)

Retrieves a copy of the value for a <clutter-state-key>.

The <gvalue> needs to be already initialized for the value type of the property or to a type that allow transformation from the value type of the key.

Use g-value-unset when done.

state-key
a <clutter-state-key>
value
a <gvalue> initialized with the correct type for the state-key
ret
‘#t’ if the value was successfully retrieved, and ‘#f’ otherwise

Since 1.4

— Function: clutter-state-key-get-property-type (self <clutter-state-key>) ⇒  (ret <gtype>)

Retrieves the <g-type> of the property a key applies to

You can use this type to initialize the <gvalue> to pass to clutter-state-key-get-value

key
a <clutter-state-key>
ret
the <g-type> of the property

Since 1.4

— Function: clutter-state-key-get-pre-delay (self <clutter-state-key>) ⇒  (ret double)

Retrieves the pause before transitioning starts as a fraction of the total transition time.

state-key
a <clutter-state-key>
ret
the pre delay used before starting the transition.

Since 1.4

— Function: clutter-state-key-get-post-delay (self <clutter-state-key>) ⇒  (ret double)

Retrieves the duration of the pause after transitioning is complete as a fraction of the total transition time.

state-key
a <clutter-state-key>
ret
the post delay, used after doing the transition.

Since 1.4