ClutterState

ClutterState — State machine with animated transitions

Synopsis

                    ClutterState;
                    ClutterStateClass;
ClutterState *      clutter_state_new                   (void);
void                clutter_state_set                   (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name,
                                                         gpointer first_object,
                                                         const gchar *first_property_name,
                                                         gulong first_mode,
                                                         ...);
ClutterState *      clutter_state_set_key               (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name,
                                                         GObject *object,
                                                         const gchar *property_name,
                                                         guint mode,
                                                         const GValue *value,
                                                         gdouble pre_delay,
                                                         gdouble post_delay);
void                clutter_state_set_duration          (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name,
                                                         guint duration);
guint               clutter_state_get_duration          (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name);
GList *             clutter_state_get_states            (ClutterState *state);
GList *             clutter_state_get_keys              (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name,
                                                         GObject *object,
                                                         const gchar *property_name);
void                clutter_state_remove_key            (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name,
                                                         GObject *object,
                                                         const gchar *property_name);
ClutterTimeline *   clutter_state_get_timeline          (ClutterState *state);
void                clutter_state_set_animator          (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name,
                                                         ClutterAnimator *animator);
ClutterAnimator *   clutter_state_get_animator          (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name);
const gchar *       clutter_state_get_target_state      (ClutterState *state);
ClutterTimeline *   clutter_state_change                (ClutterState *state,
                                                         const gchar *target_state_name,
                                                         gboolean animate);

                    ClutterStateKey;
gdouble             clutter_state_key_get_pre_delay     (const ClutterStateKey *state_key);
gdouble             clutter_state_key_get_post_delay    (const ClutterStateKey *state_key);
gulong              clutter_state_key_get_mode          (const ClutterStateKey *state_key);
void                clutter_state_key_get_value         (const ClutterStateKey *state_key,
                                                         GValue *value);
GObject *           clutter_state_key_get_object        (const ClutterStateKey *state_key);
const gchar *       clutter_state_key_get_property_name (const ClutterStateKey *state_key);
const gchar *       clutter_state_key_get_source_state_name
                                                        (const ClutterStateKey *state_key);
const gchar *       clutter_state_key_get_target_state_name
                                                        (const ClutterStateKey *state_key);

Object Hierarchy

  GObject
   +----ClutterState

Implemented Interfaces

ClutterState implements ClutterScriptable.

Properties

  "target-state"             gchar*                : Read / Write

Signals

  "completed"                                      : Run Last

Description

ClutterState controls the tweening of properties on multiple actors between a set of named states.

Details

ClutterState

typedef struct _ClutterState ClutterState;

The ClutterState structure contains only private data and should be accessed using the provided API

Since 1.4


ClutterStateClass

typedef struct {
  void (* completed) (ClutterState *state);
} ClutterStateClass;

The ClutterStateClass structure contains only private data

completed ()

class handler for the "completed" signal

Since 1.4


clutter_state_new ()

ClutterState *      clutter_state_new                   (void);

Creates a new ClutterState

Returns :

the newly create ClutterState instance

clutter_state_set ()

void                clutter_state_set                   (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name,
                                                         gpointer first_object,
                                                         const gchar *first_property_name,
                                                         gulong first_mode,
                                                         ...);

Adds multiple keys to a named state of a ClutterState instance, specifying the easing mode and value a given property of an object should have at a given progress of the animation.

The mode specified is the easing mode used when going to from the previous key to the specified key.

For instance, the code below:

1
2
3
4
5
clutter_state_set (state, "default", "hover",
                   button, "opacity", 255, CLUTTER_LINEAR,
                   button, "scale-x", 1.2, CLUTTER_EASE_OUT_CUBIC,
                   button, "scale-y", 1.2, CLUTTER_EASE_OUT_CUBIC,
                   NULL);

will create a transition between the "default" and "hover" state; the button object will have the "opacity" property animated to a value of 255 using CLUTTER_LINEAR as the animation mode, and the "scale-x" and "scale-y" properties animated to a value of 1.2 using CLUTTER_EASE_OUT_CUBIC as the animation mode. To change the state (and start the transition) you can use the clutter_state_change() function:

1
clutter_state_change (state, "hover", TRUE);

If a given object, state_name, property tuple already exist in the ClutterState instance, then the mode and value will be replaced with the new specified values.

If a property name is prefixed with "delayed::" two additional arguments per key are expected: a value relative to the full state time to pause before transitioning and a similar value to pause after transitioning, e.g.:

1
2
3
4
clutter_state_set (state, "hover", "toggled",
                   button, "delayed::scale-x", 1.0, 0.2, 0.2,
                   button, "delayed::scale-y", 1.0, 0.2, 0.2,
                   NULL);

will pause for 20% of the duration of the transition before animating, and 20% of the duration after animating.

state :

a ClutterState instance.

source_state_name :

the name of the source state keys are being added for

target_state_name :

the name of the target state keys are being added for

first_object :

a GObject

first_property_name :

a property of first_object to specify a key for

first_mode :

the id of the alpha function to use

... :

the value first_property_name should have in target_state_name, followed by object, property name, mode, value tuples, terminated by NULL

Since 1.4


clutter_state_set_key ()

ClutterState *      clutter_state_set_key               (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name,
                                                         GObject *object,
                                                         const gchar *property_name,
                                                         guint mode,
                                                         const GValue *value,
                                                         gdouble pre_delay,
                                                         gdouble post_delay);

Sets one specific end key for a state_name, object, property_name combination.

state :

a ClutterState instance.

source_state_name :

the source transition to specify transition for

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

Returns :

the ClutterState instance, allowing chaining of multiple calls

Since 1.4


clutter_state_set_duration ()

void                clutter_state_set_duration          (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name,
                                                         guint duration);

Sets the duration of a transition.

If both state names are NULL 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 ClutterState

source_state_name :

the name of the source state, or NULL. [allow-none]

target_state_name :

the name of the target state, or NULL. [allow-none]

duration :

the duration of the transition, in milliseconds

Since 1.4


clutter_state_get_duration ()

guint               clutter_state_get_duration          (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name);

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 ClutterState

source_state_name :

the name of the source state to get the duration of, or NULL. [allow-none]

target_state_name :

the name of the source state to get the duration of, or NULL. [allow-none]

Returns :

the duration, in milliseconds

Since 1.4


clutter_state_get_states ()

GList *             clutter_state_get_states            (ClutterState *state);

Gets a list of all the state names managed by this ClutterState.

state :

a ClutterState instance.

Returns :

a newly allocated GList of state names. The contents of the returned GList are owned by the ClutterState and should not be modified or freed. Use g_list_free() to free the resources allocated by the returned list when done using it. [transfer container][element-type utf8]

Since 1.4


clutter_state_get_keys ()

GList *             clutter_state_get_keys              (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name,
                                                         GObject *object,
                                                         const gchar *property_name);

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

state :

a ClutterState instance.

source_state_name :

the source transition name to query, or NULL for all source states. [allow-none]

target_state_name :

the target transition name to query, or NULL for all target states. [allow-none]

object :

the specific object instance to list keys for, or NULL for all managed objects. [allow-none]

property_name :

the property name to search for, or NULL for all properties. [allow-none]

Returns :

a newly allocated GList of ClutterStateKeys. The contents of the returned list are owned by the ClutterState and should not be modified or freed. Use g_list_free() to free the resources allocated by the returned list when done using it. [transfer container][element-type ClutterStateKey]

Since 1.4


clutter_state_remove_key ()

void                clutter_state_remove_key            (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name,
                                                         GObject *object,
                                                         const gchar *property_name);

Removes all keys matching the search criteria passed in arguments.

state :

a ClutterState instance.

source_state_name :

the source state name to query, or NULL for all source states. [allow-none]

target_state_name :

the target state name to query, or NULL for all target states. [allow-none]

object :

the specific object instance to list keys for, or NULL for all managed objects. [allow-none]

property_name :

the property name to search for, or NULL for all properties. [allow-none]

Since 1.4


clutter_state_get_timeline ()

ClutterTimeline *   clutter_state_get_timeline          (ClutterState *state);

Gets the timeline driving the ClutterState

state :

a ClutterState

Returns :

the ClutterTimeline that drives the state change animations. The returned timeline is owned by the ClutterState and it should not be unreferenced directly. [transfer none]

Since 1.4


clutter_state_set_animator ()

void                clutter_state_set_animator          (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name,
                                                         ClutterAnimator *animator);

Specifies a ClutterAnimator 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 other allowed by the simple tweening of properties defined in the ClutterState keys.

If animator is NULL it will unset an existing animator.

ClutterState will take a reference on the passed animator, if any

state :

a ClutterState instance.

source_state_name :

the name of a source state

target_state_name :

the name of a target state

animator :

a ClutterAnimator instance, or NULL to unset an existing ClutterAnimator. [allow-none]

Since 1.4


clutter_state_get_animator ()

ClutterAnimator *   clutter_state_get_animator          (ClutterState *state,
                                                         const gchar *source_state_name,
                                                         const gchar *target_state_name);

Retrieves the ClutterAnimator that is being used for transitioning between the two states, if any has been set

state :

a ClutterState instance.

source_state_name :

the name of a source state

target_state_name :

the name of a target state

Returns :

a ClutterAnimator instance, or NULL. [transfer none]

Since 1.4


clutter_state_get_target_state ()

const gchar *       clutter_state_get_target_state      (ClutterState *state);

Queries the currently set target state.

During a transition this function will also return the current target.

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

state :

a ClutterState

Returns :

a string containing the target state. The returned string is owned by the ClutterState and should not be modified or freed

Since 1.4


clutter_state_change ()

ClutterTimeline *   clutter_state_change                (ClutterState *state,
                                                         const gchar *target_state_name,
                                                         gboolean animate);

Change the current state of ClutterState to target__name

If animate is FALSE, the state transition will happen immediately; otherwise, the state transition will be animated over the duration set using clutter_state_set_duration()

state :

a ClutterState

target_state_name :

the state to transition to

animate :

whether we should animate the transition or not

Returns :

the ClutterTimeline that drives the state transition

Since 1.4


ClutterStateKey

typedef struct _ClutterStateKey ClutterStateKey;

ClutterStateKey is an opaque structure whose members cannot be accessed directly

Since 1.4


clutter_state_key_get_pre_delay ()

gdouble             clutter_state_key_get_pre_delay     (const ClutterStateKey *state_key);

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

state_key :

a ClutterStateKey

Returns :

the pre delay used before starting the transition.

Since 1.4


clutter_state_key_get_post_delay ()

gdouble             clutter_state_key_get_post_delay    (const ClutterStateKey *state_key);

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

state_key :

a ClutterStateKey

Returns :

the post delay, used after doing the transition.

Since 1.4


clutter_state_key_get_mode ()

gulong              clutter_state_key_get_mode          (const ClutterStateKey *state_key);

Retrieves the easing mode used for state_key.

state_key :

a ClutterStateKey

Returns :

the mode of a ClutterStateKey

Since 1.4


clutter_state_key_get_value ()

void                clutter_state_key_get_value         (const ClutterStateKey *state_key,
                                                         GValue *value);

Copies of the value for a ClutterStateKey into value

The GValue needs to be already initialized for the value type of the property or to a transformable type

state_key :

a ClutterStateKey

value :

a GValue initialized with the correct type for the state_key

Since 1.4


clutter_state_key_get_object ()

GObject *           clutter_state_key_get_object        (const ClutterStateKey *state_key);

Retrieves the object instance this ClutterStateKey applies to.

state_key :

a ClutterStateKey

Returns :

the object this state key applies to. [transfer none]

Since 1.4


clutter_state_key_get_property_name ()

const gchar *       clutter_state_key_get_property_name (const ClutterStateKey *state_key);

Retrieves the name of the property this ClutterStateKey applies to

state_key :

a ClutterStateKey

Returns :

the name of the property. The returned string is owned by the ClutterStateKey and should never be modified or freed

Since 1.4


clutter_state_key_get_source_state_name ()

const gchar *       clutter_state_key_get_source_state_name
                                                        (const ClutterStateKey *state_key);

Retrieves the name of the source state of the state_key

state_key :

a ClutterStateKey

Returns :

the name of the source state for this key, or NULL if this is the generic state key for the given property when transitioning to the target state. The returned string is owned by the ClutterStateKey and should never be modified or freed

Since 1.4


clutter_state_key_get_target_state_name ()

const gchar *       clutter_state_key_get_target_state_name
                                                        (const ClutterStateKey *state_key);

Get the name of the source state this ClutterStateKey contains, or NULL if this is the generic state key for the given property when transitioning to the target state.

state_key :

a ClutterStateKey

Returns :

the name of the source state for this key, or NULL if the key is generic

Since 1.4

Property Details

The "target-state" property

  "target-state"             gchar*                : Read / Write

The currently set target state, setting it causes the state machine to transition to the new state, use clutter_state_change() directly to directly jump to a state.

Default value: "default"

Signal Details

The "completed" signal

void                user_function                      (ClutterState *state,
                                                        gpointer      user_data)      : Run Last

The ::completed signal is emitted when a ClutterState reaches the target state specified by clutter_state_change()

state :

the ClutterState that emitted the signal

user_data :

user data set when the signal handler was connected.

Since 1.4