Ecore Animator functions
Ecore » Ecore main loop

Ecore animators are a helper to simplify creating animations. More...

## Data Structures

struct | Ecore_Animator
| Opaque handle to manage Ecore Animator objects. More...

## Typedefs

typedef Eina_Bool(* | Ecore_Timeline_Cb) (void *data, double pos)
| A callback run for a task (animators with runtimes).
typedef struct _Ecore_Animator | Ecore_Animator

## Enumerations

enum | Ecore_Animator_Source { ECORE_ANIMATOR_SOURCE_TIMER , ECORE_ANIMATOR_SOURCE_CUSTOM }
| Defines the timing sources for animators. More...
enum | Ecore_Pos_Map { ECORE_POS_MAP_LINEAR = 0 , ECORE_POS_MAP_ACCELERATE , ECORE_POS_MAP_DECELERATE , ECORE_POS_MAP_SINUSOIDAL , ECORE_POS_MAP_ACCELERATE_FACTOR , ECORE_POS_MAP_DECELERATE_FACTOR , ECORE_POS_MAP_SINUSOIDAL_FACTOR , ECORE_POS_MAP_DIVISOR_INTERP , ECORE_POS_MAP_BOUNCE , ECORE_POS_MAP_SPRING , ECORE_POS_MAP_CUBIC_BEZIER }
| Defines the position mappings for the animation. More...

## Functions

void | ecore_animator_frametime_set (double frametime)
| Sets the animator call interval in seconds.
double | ecore_animator_frametime_get (void)
| Gets the animator call interval in seconds.
double | ecore_animator_pos_map (double pos, Ecore_Pos_Map map, double v1, double v2)
| Maps an input position from 0.0 to 1.0 along a timeline to a position in a different curve.
double | ecore_animator_pos_map_n (double pos, Ecore_Pos_Map map, int v_size, double *v)
| Maps an input position from 0.0 to 1.0 along a timeline to a position in a different curve.
void | ecore_animator_source_set (Ecore_Animator_Source source)
| Sets the source of animator ticks for the mainloop.
Ecore_Animator_Source | ecore_animator_source_get (void)
| Gets the animator source currently set.
void | ecore_animator_custom_source_tick_begin_callback_set (Ecore_Cb func, const void *data)
| Sets the function that begins a custom animator tick source.
void | ecore_animator_custom_source_tick_end_callback_set (Ecore_Cb func, const void *data)
| Sets the function that ends a custom animator tick source.
void | ecore_animator_custom_tick (void)
| Triggers a custom animator tick.
Ecore_Animator * | ecore_animator_add (Ecore_Task_Cb func, const void *data)
| Adds an animator to call `func` at every animation tick during main loop execution.
Ecore_Animator * | ecore_animator_timeline_add (double runtime, Ecore_Timeline_Cb func, const void *data)
| Adds an animator that runs for a limited time.
void * | ecore_animator_del (Ecore_Animator *animator)
| Deletes the specified animator from the animator list.
void | ecore_animator_freeze (Ecore_Animator *animator)
| Suspends the specified animator.
void | ecore_animator_thaw (Ecore_Animator *animator)
| Restores execution of the specified animator.

## Detailed Description

Ecore animators are a helper to simplify creating animations.

Creating an animation is as simple as saying for how long it should be run and having a callback that does the animation, something like this:

static Eina_Bool
_do_animation(void *data, double pos)
{
evas_object_move(data, 100 * pos, 100 * pos);
... do some more animating ...
}
...
ecore_animator_timeline_add(2, _do_animation, my_evas_object);
Eina_Bool
unsigned char Eina_Bool
Type to mimic a boolean.
Definition eina_types.h:527
evas_object_move
EVAS_API void evas_object_move(Evas_Object *obj, Evas_Coord x, Evas_Coord y)
Move the given Evas object to the given location inside its canvas' viewport.
Definition evas_object_main.c:1171

In the sample above we create an animation to move `my_evas_object` from position (0,0) to (100,100) in 2 seconds.

If your animation will run for an unspecified amount of time you can use ecore_animator_add(), which is like using ecore_timer_add() with the interval being the framerate. Note that this has tangible benefits to creating a timer for each animation in terms of performance.

For a more detailed example that show several animation see Ecore animator example.

## Enumeration Type Documentation

## Ecore_Animator_Source

enum Ecore_Animator_Source

Defines the timing sources for animators.

Enumerator
ECORE_ANIMATOR_SOURCE_TIMER | The default system clock/timer based animator that ticks every "frametime" seconds.
ECORE_ANIMATOR_SOURCE_CUSTOM | A custom animator trigger that you need to call ecore_animator_custom_tick() to make it tick.

## Ecore_Pos_Map

enum Ecore_Pos_Map

Defines the position mappings for the animation.

Enumerator
ECORE_POS_MAP_LINEAR | Linear 0.0 -> 1.0.
ECORE_POS_MAP_ACCELERATE | Start slow then speed up.
ECORE_POS_MAP_DECELERATE | Start fast then slow down.
ECORE_POS_MAP_SINUSOIDAL | Start slow, speed up then slow down at end.
ECORE_POS_MAP_ACCELERATE_FACTOR | Start slow then speed up, v1 being a power factor, 0.0 being linear, 1.0 being normal accelerate, 2.0 being much more pronounced accelerate (squared), 3.0 being cubed, etc.
ECORE_POS_MAP_DECELERATE_FACTOR | Start fast then slow down, v1 being a power factor, 0.0 being linear, 1.0 being normal decelerate, 2.0 being much more pronounced decelerate (squared), 3.0 being cubed, etc.
ECORE_POS_MAP_SINUSOIDAL_FACTOR | Start slow, speed up then slow down at end, v1 being a power factor, 0.0 being linear, 1.0 being normal sinusoidal, 2.0 being much more pronounced sinusoidal (squared), 3.0 being cubed, etc.
ECORE_POS_MAP_DIVISOR_INTERP | Start at gradient * v1, interpolated via power of v2 curve.
ECORE_POS_MAP_BOUNCE | Start at 0.0 then "drop" like a ball bouncing to the ground at 1.0, and bounce v2 times, with decay factor of v1.
ECORE_POS_MAP_SPRING | Start at 0.0 then "wobble" like a spring rest position 1.0, and wobble v2 times, with decay factor of v1.
ECORE_POS_MAP_CUBIC_BEZIER | Follow the cubic-bezier curve calculated with the control points (x1, y1), (x2, y2).

## Function Documentation

## ecore_animator_frametime_set()

void ecore_animator_frametime_set | ( | double | frametime | ) |

Sets the animator call interval in seconds.

Parameters

  frametime | The time in seconds in between animator ticks.

This function sets the time interval (in seconds) between animator ticks. At every tick the callback of every existing animator will be called.

Warning
  Too small a value may cause performance issues and too high a value may cause your animation to seem "jerky".

Note
  The default `frametime` value is 1/60th of a second.

References EINA_DBL_EQ, and EINA_MAIN_LOOP_CHECK_RETURN.

Referenced by edje_frametime_set().

## ecore_animator_frametime_get()

double ecore_animator_frametime_get | ( | void |  | ) |

Gets the animator call interval in seconds.

Returns
  The time in second in between animator ticks.

This function retrieves the time in seconds between animator ticks.

See also
  ecore_animator_frametime_set()

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

Referenced by ecore_con_ssl_client_upgrade(), ecore_con_ssl_server_upgrade(), and edje_frametime_get().

## ecore_animator_pos_map()

double ecore_animator_pos_map | ( | double | pos,
|  | Ecore_Pos_Map | map,
|  | double | v1,
|  | double | v2 )

Maps an input position from 0.0 to 1.0 along a timeline to a position in a different curve.

Parameters

  pos | The input position to map
  map | The mapping to use
  v1 | A parameter use by the mapping (pass 0.0 if not used)
  v2 | A parameter use by the mapping (pass 0.0 if not used)

Returns
  The mapped value

Takes an input position (0.0 to 1.0) and maps to a new position (normally between 0.0 and 1.0, but it may go above/below 0.0 or 1.0 to show that it has "overshot" the mark) using some interpolation (mapping) algorithm.

This function useful to create non-linear animations. It offers a variety of possible animation curves to be used:

- ECORE_POS_MAP_LINEAR - Linear, returns `pos`
- ECORE_POS_MAP_ACCELERATE - Start slow then speed up
- ECORE_POS_MAP_DECELERATE - Start fast then slow down
- ECORE_POS_MAP_SINUSOIDAL - Start slow, speed up then slow down at end
- ECORE_POS_MAP_ACCELERATE_FACTOR - Start slow then speed up, v1 being a power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_ACCELERATE, 2.0 being much more pronounced accelerate (squared), 3.0 being cubed, etc.
- ECORE_POS_MAP_DECELERATE_FACTOR - Start fast then slow down, v1 being a power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_DECELERATE, 2.0 being much more pronounced decelerate (squared), 3.0 being cubed, etc.
- ECORE_POS_MAP_SINUSOIDAL_FACTOR - Start slow, speed up then slow down at end, v1 being a power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_SINUSOIDAL, 2.0 being much more pronounced sinusoidal (squared), 3.0 being cubed, etc.
- ECORE_POS_MAP_DIVISOR_INTERP - Start at gradient * v1, interpolated via power of v2 curve
- ECORE_POS_MAP_BOUNCE - Start at 0.0 then "drop" like a ball bouncing to the ground at 1.0, and bounce v2 times, with decay factor of v1
- ECORE_POS_MAP_SPRING - Start at 0.0 then "wobble" like a spring rest position 1.0, and wobble v2 times, with decay factor of v1
  Note
    When not listed v1 and v2 have no effect.

One way to use this would be:

double pos; // input position in a timeline from 0.0 to 1.0
double out; // output position after mapping
int x1, y1, x2, y2; // x1 & y1 are start position, x2 & y2 are end position
int x, y; // x & y are the calculated position
out = ecore_animator_pos_map(pos, ECORE_POS_MAP_BOUNCE, 1.8, 7);
x = (x1 * out) + (x2 * (1.0 - out));
y = (y1 * out) + (y2 * (1.0 - out));
move_my_object_to(myobject, x, y);
ecore_animator_pos_map
double ecore_animator_pos_map(double pos, Ecore_Pos_Map map, double v1, double v2)
Maps an input position from 0.0 to 1.0 along a timeline to a position in a different curve.
Definition ecore_anim.c:833
ECORE_POS_MAP_BOUNCE
@ ECORE_POS_MAP_BOUNCE
Start at 0.0 then "drop" like a ball bouncing to the ground at 1.0, and bounce v2 times,...
Definition Ecore_Common.h:2792

This will make an animation that bounces 7 each times diminishing by a factor of 1.8.

See also
  Ecore_Pos_Map

Since
  1.1.0

References ecore_animator_pos_map_n().

## ecore_animator_pos_map_n()

double ecore_animator_pos_map_n | ( | double | pos,
|  | Ecore_Pos_Map | map,
|  | int | v_size,
|  | double * | v )

Maps an input position from 0.0 to 1.0 along a timeline to a position in a different curve.

Parameters

  pos | The input position to map
  map | The mapping to use
  v_size | The size of the v array.
  v | An array with the double parameters to be used by the mapping. NULL if not used.

Returns
  The mapped value

Takes an input position (0.0 to 1.0) and maps to a new position (normally between 0.0 and 1.0, but it may go above/below 0.0 or 1.0 to show that it has "overshot" the mark) using some interpolation (mapping) algorithm.

This function useful to create non-linear animations. It offers a variety of possible animation curves to be used:

- ECORE_POS_MAP_LINEAR - Linear, returns `pos`
- ECORE_POS_MAP_ACCELERATE - Start slow then speed up
- ECORE_POS_MAP_DECELERATE - Start fast then slow down
- ECORE_POS_MAP_SINUSOIDAL - Start slow, speed up then slow down at end
- ECORE_POS_MAP_ACCELERATE_FACTOR - Start slow then speed up, v[0] being a power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_ACCELERATE, 2.0 being much more pronounced accelerate (squared), 3.0 being cubed, etc.
- ECORE_POS_MAP_DECELERATE_FACTOR - Start fast then slow down, v[0] being a power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_DECELERATE, 2.0 being much more pronounced decelerate (squared), 3.0 being cubed, etc.
- ECORE_POS_MAP_SINUSOIDAL_FACTOR - Start slow, speed up then slow down at end, v[0] being a power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_SINUSOIDAL, 2.0 being much more pronounced sinusoidal (squared), 3.0 being cubed, etc.
- ECORE_POS_MAP_DIVISOR_INTERP - Start at gradient * v[0], interpolated via power of v2 curve
- ECORE_POS_MAP_BOUNCE - Start at 0.0 then "drop" like a ball bouncing to the ground at 1.0, and bounce v2 times, with decay factor of v[0]
- ECORE_POS_MAP_SPRING - Start at 0.0 then "wobble" like a spring rest position 1.0, and wobble v2 times, with decay factor of v[0]
- ECORE_POS_MAP_CUBIC_BEZIER - Use an interpolated cubic-bezier curve adjusted with parameters from v[0] to v[3].
  Note
    When not listed v has no effect.

One way to use this would be:

double pos; // input position in a timeline from 0.0 to 1.0
double out; // output position after mapping
int x1, y1, x2, y2; // x1 & y1 are start position, x2 & y2 are end position
int x, y; // x & y are the calculated position
double v[2] = {1.8, 7};
out = ecore_animator_pos_map(pos, ECORE_POS_MAP_BOUNCE, 2, v);
x = (x1 * out) + (x2 * (1.0 - out));
y = (y1 * out) + (y2 * (1.0 - out));
move_my_object_to(myobject, x, y);

This will make an animation that bounces 7 each times diminishing by a factor of 1.8.

See also
  Ecore_Pos_Map

References ECORE_POS_MAP_ACCELERATE, ECORE_POS_MAP_ACCELERATE_FACTOR, ECORE_POS_MAP_BOUNCE, ECORE_POS_MAP_CUBIC_BEZIER, ECORE_POS_MAP_DECELERATE, ECORE_POS_MAP_DECELERATE_FACTOR, ECORE_POS_MAP_DIVISOR_INTERP, ECORE_POS_MAP_LINEAR, ECORE_POS_MAP_SINUSOIDAL, ECORE_POS_MAP_SINUSOIDAL_FACTOR, ECORE_POS_MAP_SPRING, and EINA_F32P32_PI.

Referenced by ecore_animator_pos_map().

## ecore_animator_source_set()

void ecore_animator_source_set | ( | Ecore_Animator_Source | source | ) |

Sets the source of animator ticks for the mainloop.

Parameters

  source | The source of animator ticks to use

This sets the source of animator ticks. When an animator is active the mainloop will "tick" over frame by frame calling all animators that are registered until none are. The mainloop will tick at a given rate based on the animator source. The default source is the system clock timer source - ECORE_ANIMATOR_SOURCE_TIMER. This source uses the system clock to tick over every N seconds (specified by ecore_animator_frametime_set(), with the default being 1/60th of a second unless set otherwise). You can set a custom tick source by setting the source to ECORE_ANIMATOR_SOURCE_CUSTOM and then drive it yourself based on some input tick source (like another application via ipc, some vertical blanking interrupt, and etc.) using ecore_animator_custom_source_tick_begin_callback_set() and ecore_animator_custom_source_tick_end_callback_set() to set the functions that will be called to start and stop the ticking source, which when it gets a "tick" should call ecore_animator_custom_tick() to make the "tick" over 1 frame.

See also
  ecore_animator_source_get()

References DBG, ECORE_ANIMATOR_SOURCE_CUSTOM, ECORE_ANIMATOR_SOURCE_TIMER, and EINA_MAIN_LOOP_CHECK_RETURN.

## ecore_animator_source_get()

Ecore_Animator_Source ecore_animator_source_get | ( | void |  | ) |

Gets the animator source currently set.

Returns
  The current animator source

This gets the current animator source.

See also
  ecore_animator_source_set()

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

## ecore_animator_custom_source_tick_begin_callback_set()

void ecore_animator_custom_source_tick_begin_callback_set | ( | Ecore_Cb | func,
|  | const void * | data )

Sets the function that begins a custom animator tick source.

Parameters

  func | The function to call when ticking is to begin
  data | The data passed to the tick begin function as its parameter

The Ecore Animator infrastructure handles tracking if animators are needed or not and which ones need to be called and when, but when the tick source is custom, you have to provide a tick source by calling ecore_animator_custom_tick() to indicate a frame tick happened. In order to allow the source of ticks to be dynamically enabled or disabled as needed, the `func` when set is called to enable the tick source to produce tick events that call ecore_animator_custom_tick(). If `func` is `NULL` then no function is called to begin custom ticking.

Warning
  Do not use this function unless you know what you are doing.

See also
  ecore_animator_source_set()
  ecore_animator_custom_source_tick_end_callback_set()
  ecore_animator_custom_tick()

References EINA_MAIN_LOOP_CHECK_RETURN.

## ecore_animator_custom_source_tick_end_callback_set()

void ecore_animator_custom_source_tick_end_callback_set | ( | Ecore_Cb | func,
|  | const void * | data )

Sets the function that ends a custom animator tick source.

Parameters

  func | The function to call when ticking is to end
  data | The data passed to the tick end function as its parameter

This function is a matching pair to the function set by ecore_animator_custom_source_tick_begin_callback_set() and is called when ticking is to stop. If `func` is `NULL` then no function will be called to stop ticking. For more information please see ecore_animator_custom_source_tick_begin_callback_set().

Warning
  Do not use this function unless you know what you are doing.

See also
  ecore_animator_source_set()
  ecore_animator_custom_source_tick_begin_callback_set()
  ecore_animator_custom_tick()

References EINA_MAIN_LOOP_CHECK_RETURN.

## ecore_animator_custom_tick()

void ecore_animator_custom_tick | ( | void |  | ) |

Triggers a custom animator tick.

When animator source is set to ECORE_ANIMATOR_SOURCE_CUSTOM, then calling this function triggers a run of all animators currently registered with Ecore as this indicates a "frame tick" happened. This will do nothing if the animator source(set by ecore_animator_source_set()) is not set to ECORE_ANIMATOR_SOURCE_CUSTOM.

Warning
  Do not use this function unless you know what you are doing.

See also
  ecore_animator_source_set()
  ecore_animator_custom_source_tick_begin_callback_set
  ecore_animator_custom_source_tick_end_callback_set()()

References ECORE_ANIMATOR_SOURCE_CUSTOM, and EINA_MAIN_LOOP_CHECK_RETURN.

## ecore_animator_add()

Ecore_Animator * ecore_animator_add | ( | Ecore_Task_Cb | func,
|  | const void * | data )

Adds an animator to call `func` at every animation tick during main loop execution.

Parameters

  func | The function to call when it ticks off
  data | The data to pass to the function

Returns
  A handle to the new animator

This function adds an animator and returns its handle on success and `NULL` on failure. The function `func` will be called every N seconds where N is the `frametime` interval set by ecore_animator_frametime_set(). The function will be passed the `data` pointer as its parameter.

When the animator `func` is called, it must return a boolean value. If it returns `EINA_TRUE` (or `ECORE_CALLBACK_RENEW`), it will be called again at the next tick, or if it returns `EINA_FALSE` (or `ECORE_CALLBACK_CANCEL`) it will be deleted automatically making any references/handles for it invalid.

See also
  ecore_animator_timeline_add()
  ecore_animator_frametime_set()

Note
  The default `frametime` value is 1/30th of a second.

Referenced by elm_transit_go().

## ecore_animator_timeline_add()

Ecore_Animator * ecore_animator_timeline_add | ( | double | runtime,
|  | Ecore_Timeline_Cb | func,
|  | const void * | data )

Adds an animator that runs for a limited time.

Parameters

  runtime | The time to run in seconds
  func | The function to call when it ticks off
  data | The data to pass to the function

Returns
  A handle to the new animator

This function is just like ecore_animator_add() except the animator only runs for a limited time specified in seconds by `runtime`. Once the runtime the animator has elapsed (animator finished) it will automatically be deleted. The callback function `func` can return `ECORE_CALLBACK_RENEW` to keep the animator running or `ECORE_CALLBACK_CANCEL` or stop it and have it be deleted automatically at any time. Just like timers, the start of The animation is "now" (when the loop woke up - gettable with ecore_loop_time_get()).

The `func` will ALSO be passed a position parameter that will be in value from 0.0 to 1.0 to indicate where along the timeline (0.0 start, 1.0 end) the animator run is at. If the callback wishes not to have a linear transition it can "map" this value to one of several curves and mappings via ecore_animator_pos_map().

See also
  ecore_animator_add()
  ecore_animator_pos_map()

Note
  The default `frametime` value is 1/30th of a second.
  The first position parameter passed to the callback will never be 0.

Since
  1.1.0

References ecore_loop_time_get().

## ecore_animator_del()

void * ecore_animator_del | ( | Ecore_Animator * | animator | ) |

Deletes the specified animator from the animator list.

Parameters

  animator | The animator to delete

Returns
  The data pointer set for the animator on add

Deletes the specified `animator` from the set of animators that are executed during main loop execution. This function returns the data parameter that was being passed to the callback on success, or `NULL` on failure. After this call returns the specified animator object `animator` is invalid and should not be used again. It will not get called again after deletion.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL, and EINA_TRUE.

Referenced by elm_box_transition_free(), and elm_transit_go().

## ecore_animator_freeze()

void ecore_animator_freeze | ( | Ecore_Animator * | animator | ) |

Suspends the specified animator.

Parameters

  animator | The animator to delete

The specified `animator` will be temporarily removed from the set of animators that are executed during main loop.

Warning
  Freezing an animator doesn't freeze accounting of how long that animator has been running. Therefore if the animator was created with ecore_animator_timeline_add() the `pos` argument given to the callback will increase as if the animator hadn't been frozen and the animator may have it's execution halted if `runtime` elapsed.

References EINA_MAIN_LOOP_CHECK_RETURN, and EINA_TRUE.

Referenced by elm_transit_paused_set().

## ecore_animator_thaw()

void ecore_animator_thaw | ( | Ecore_Animator * | animator | ) |

Restores execution of the specified animator.

Parameters

  animator | The animator to delete

The specified `animator` will be put back in the set of animators that are executed during main loop.

References EINA_FALSE, and EINA_MAIN_LOOP_CHECK_RETURN.

Referenced by elm_transit_paused_set().