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 ]
      ]
    }
  ]
}

clutter_state_new ()

ClutterState *
clutter_state_new (void);

Creates a new ClutterState

Since: 1.4

clutter_state_set_state ()

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

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.

Since: 1.4

clutter_state_get_state ()

const gchar *
clutter_state_get_state (ClutterState *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.

Since: 1.4

clutter_state_warp_to_state ()

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

Change to the specified target state immediately with no animation.

See clutter_state_set_state().

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

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.

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.

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.

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

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.

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.

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.

Since: 1.4

clutter_state_get_timeline ()

ClutterTimeline *
clutter_state_get_timeline (ClutterState *state);

Gets the timeline driving the ClutterState

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

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

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

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.

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.

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

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 .

Since: 1.4

clutter_state_key_get_value ()

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

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.

Since: 1.4

clutter_state_key_get_property_type ()

GType
clutter_state_key_get_property_type (const ClutterStateKey *key);

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

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.

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.

Since: 1.4

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

The ClutterStateClass structure contains only private data

Since: 1.4

ClutterStateKey

typedef struct _ClutterStateKey ClutterStateKey;

ClutterStateKey is an opaque structure whose members cannot be accessed directly

Since: 1.4

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.

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.

Flags: Read / Write

Default value: NULL

Since: 1.4

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

Flags: Run Last

Since: 1.4