## ClutterState ClutterState — State machine with animated transitions |

## Functions

ClutterState * | clutter_state_new ()
ClutterTimeline * | clutter_state_set_state ()
const gchar * | clutter_state_get_state ()
ClutterTimeline * | clutter_state_warp_to_state ()
void | clutter_state_set ()
ClutterState * | clutter_state_set_key ()
void | clutter_state_set_duration ()
guint | clutter_state_get_duration ()
GList * | clutter_state_get_states ()
GList * | clutter_state_get_keys ()
void | clutter_state_remove_key ()
ClutterTimeline * | clutter_state_get_timeline ()
void | clutter_state_set_animator ()
ClutterAnimator * | clutter_state_get_animator ()
const gchar * | clutter_state_key_get_source_state_name ()
const gchar * | clutter_state_key_get_target_state_name ()
GObject * | clutter_state_key_get_object ()
const gchar * | clutter_state_key_get_property_name ()
gulong | clutter_state_key_get_mode ()
gboolean | clutter_state_key_get_value ()
GType | clutter_state_key_get_property_type ()
gdouble | clutter_state_key_get_pre_delay ()
gdouble | clutter_state_key_get_post_delay ()

## Properties

guint | duration | Read / Write
gchar * | state | Read / Write

## Signals

void | completed | Run Last

## Types and Values

| ClutterState
struct | ClutterStateClass
| ClutterStateKey

## Object Hierarchy

        GObject
        ╰── ClutterState

## Implemented Interfaces

ClutterState implements ClutterScriptable.

## Description

ClutterState is an object controlling the tweening of properties on multiple actors between a set of named states. ClutterStateKey<!-- -->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.

ClutterState is available since Clutter 1.4.

ClutterState has been deprecated in Clutter 1.12.

#### Using ClutterState

The following example defines a "base" and a "hover" state in a ClutterState instance.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    ClutterState *state = clutter_state_new ();
    ClutterColor color = { 0, };

    // transition from any state to the "base" state
    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);

    // transition from the "base" state to the "hover" state
    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);

    // the default duration of any transition
    clutter_state_set_duration (state, NULL, NULL, 500);

    // set "base" as the initial state
    clutter_state_warp_to_state (state, "base");

The actor then uses the ClutterState to animate through the two states using callbacks for the “enter-event” and “leave-event” signals.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    static gboolean
    on_enter (ClutterActor *actor,
              ClutterEvent *event,
              ClutterState *state)
    {
      clutter_state_set_state (state, "hover");

      return CLUTTER_EVENT_STOP;
    }

    static gboolean
    on_leave (ClutterActor *actor,
              ClutterEvent *event,
              ClutterState *state)
    {
      clutter_state_set_state (state, "base");

      return CLUTTER_EVENT_STOP;
    }

#### ClutterState description for ClutterScript

ClutterState defines a custom `transitions` JSON object member which allows describing the states.

The `transitions` property has the following syntax:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    {
      "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 and order as `clutter_state_set_key()` function arguments.

The source and target values control the source and target state of the transition. The key and animator properties are mutually exclusive.

The pre-delay and post-delay values are optional.

The example below is a translation into a ClutterScript definition of the code in the ClutterState example above.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    {
      "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 ]
          ]
        }
      ]
    }

## Functions

### clutter_state_new ()

    ClutterState *
    clutter_state_new (void);

`clutter_state_new` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

Creates a new ClutterState

#### Returns

the newly create ClutterState instance

Since 1.4

### clutter_state_set_state ()

    ClutterTimeline *
    clutter_state_set_state (ClutterState *state,
                             const gchar *target_state_name);

`clutter_state_set_state` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

Change the current state of ClutterState to `target_state_name` .

The state will animate during its transition, see clutter_state_warp_to_state for animation-free state switching.

Setting a `NULL` state will stop the current animation and unset the current state, but keys will be left intact.

#### Parameters

state | a ClutterState |
target_state_name | the state to transition to |

#### Returns

the ClutterTimeline that drives the state transition. The returned timeline is owned by the ClutterState and it should not be unreferenced.

[transfer none]

Since 1.4

### clutter_state_get_state ()

    const gchar *
    clutter_state_get_state (ClutterState *state);

`clutter_state_get_state` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

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.

#### Parameters

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_warp_to_state ()

    ClutterTimeline *
    clutter_state_warp_to_state (ClutterState *state,
                                 const gchar *target_state_name);

`clutter_state_warp_to_state` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

Change to the specified target state immediately with no animation.

See `clutter_state_set_state()`.

#### Parameters

state | a ClutterState |
target_state_name | the state to transition to |

#### Returns

the ClutterTimeline that drives the state transition. The returned timeline is owned by the ClutterState and it should not be unreferenced.

[transfer none]

Since 1.4

### 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,
                       ...);

`clutter_state_set` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

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, NULL, "hover",
                       button, "opacity", CLUTTER_LINEAR, 255,
                       button, "scale-x", CLUTTER_EASE_OUT_CUBIC, 1.2,
                       button, "scale-y", CLUTTER_EASE_OUT_CUBIC, 1.2,
                       NULL);

will create a transition from any state (a `source_state_name` or NULL is treated as a wildcard) and a state named "hover"; 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_set_state()` function:

    1
    clutter_state_set_state (state, "hover");

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", CLUTTER_LINEAR, 1.0, 0.2, 0.2,
                       button, "delayed::scale-y", CLUTTER_LINEAR, 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.

#### Parameters

state | a ClutterState instance. |
source_state_name | the name of the source state keys are being added for. | [allow-none]
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);

`clutter_state_set_key` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

Sets one specific end key for a state name, `object` , `property_name` combination.

#### Parameters

state | a ClutterState instance. |
source_state_name | the source transition to specify transition for, or `NULL` to specify the default fallback when a more specific source state doesn't exist. | [allow-none]
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.

[transfer none]

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);

`clutter_state_set_duration` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

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.

#### Parameters

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);

`clutter_state_get_duration` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

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()`

#### Parameters

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);

`clutter_state_get_states` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

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

#### Parameters

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);

`clutter_state_get_keys` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

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

#### Parameters

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 ClutterStateKey<!-- -->s. 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 Clutter.StateKey]

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);

`clutter_state_remove_key` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

Removes all keys matching the search criteria passed in arguments.

#### Parameters

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);

`clutter_state_get_timeline` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

Gets the timeline driving the ClutterState

#### Parameters

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);

`clutter_state_set_animator` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

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 allowed by the 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

#### Parameters

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);

`clutter_state_get_animator` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

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

#### Parameters

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_key_get_source_state_name ()

    const gchar *
    clutter_state_key_get_source_state_name
                                   (const ClutterStateKey *state_key);

`clutter_state_key_get_source_state_name` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

Retrieves the name of the source state of the `state_key`

#### Parameters

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);

`clutter_state_key_get_target_state_name` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

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.

#### Parameters

state_key | a ClutterStateKey |

#### Returns

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

Since 1.4

### clutter_state_key_get_object ()

    GObject *
    clutter_state_key_get_object (const ClutterStateKey *state_key);

`clutter_state_key_get_object` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

Retrieves the object instance this ClutterStateKey applies to.

#### Parameters

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);

`clutter_state_key_get_property_name` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

Retrieves the name of the property this ClutterStateKey applies to

#### Parameters

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_mode ()

    gulong
    clutter_state_key_get_mode (const ClutterStateKey *state_key);

`clutter_state_key_get_mode` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

Retrieves the easing mode used for `state_key` .

#### Parameters

state_key | a ClutterStateKey |

#### Returns

the mode of a ClutterStateKey

Since 1.4

### clutter_state_key_get_value ()

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

`clutter_state_key_get_value` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

Retrieves a copy of the value for a ClutterStateKey.

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.

#### Parameters

state_key | a ClutterStateKey |
value | a GValue initialized with the correct type for the `state_key` |

#### Returns

`TRUE` if the value was successfully retrieved, and `FALSE` otherwise

Since 1.4

### clutter_state_key_get_property_type ()

    GType
    clutter_state_key_get_property_type (const ClutterStateKey *key);

`clutter_state_key_get_property_type` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

Retrieves the GType of the property a key applies to

You can use this type to initialize the GValue to pass to `clutter_state_key_get_value()`

#### Parameters

key | a ClutterStateKey |

#### Returns

the GType of the property

Since 1.4

### clutter_state_key_get_pre_delay ()

    gdouble
    clutter_state_key_get_pre_delay (const ClutterStateKey *state_key);

`clutter_state_key_get_pre_delay` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

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

#### Parameters

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);

`clutter_state_key_get_post_delay` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

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

#### Parameters

state_key | a ClutterStateKey |

#### Returns

the post delay, used after doing the transition.

Since 1.4

## Types and Values

### ClutterState

    typedef struct _ClutterState ClutterState;

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

Since 1.4

### struct ClutterStateClass

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

`ClutterStateClass` has been deprecated since version 1.12 and should not be used in newly-written code.

The ClutterStateClass structure contains only private data

#### Members

`completed` () | class handler for the “completed” signal |

Since 1.4

### ClutterStateKey

    typedef struct _ClutterStateKey ClutterStateKey;

ClutterStateKey is an opaque structure whose members cannot be accessed directly

Since 1.4

## Property Details

### The `“duration”` property

      “duration”                 guint

Default duration used if an duration has not been specified for a specific source/target state pair. The values is in milliseconds.

`ClutterState:duration` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

Flags: Read / Write

Allowed values: <= 86400000

Default value: 1000

Since 1.4

### The `“state”` property

      “state”                    gchar *

The currently set target state, setting it causes the state machine to transition to the new state, use `clutter_state_warp_to_state()` to change state without a transition.

`ClutterState:state` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

Flags: Read / Write

Default value: NULL

Since 1.4

## Signal Details

### The `“completed”` signal

    void
    user_function (ClutterState *state,
                   gpointer      user_data)

The ::completed signal is emitted when a ClutterState reaches the target state specified by `clutter_state_set_state()` or `clutter_state_warp_to_state()`.

`ClutterState::completed` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterKeyframeTransition and ClutterTransitionGroup instead

#### Parameters

state | the ClutterState that emitted the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since 1.4