Elementary: elm_animator documentation and example.

SVN revision: 60405
This commit is contained in:
Jonas M. Gastal 2011-06-16 18:13:03 +00:00
parent a4cb2b2f0e
commit 718cca963c
4 changed files with 355 additions and 140 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 23 KiB

View File

@ -0,0 +1,103 @@
//Compile with:
//gcc -g `pkg-config --cflags --libs elementary` animator_example_01.c -o animator_example_01
#include <Elementary.h>
#include <limits.h>
static void
on_done(void *data, Evas_Object *obj, void *event_info)
{
elm_exit();
}
static void
_op_cb(void *data, Elm_Animator *animator, double frame)
{
evas_object_resize(data, 100 * frame, 100 * frame);
evas_object_move(data, 50 * frame, 50 * frame);
evas_object_color_set(data, 255 * frame, 0, 255 * (1 - frame), 255);
}
static void
_end_cb(void *data)
{
printf("Wow, you're very patient!\n");
}
static void
_pause_resume(void *data, Evas_Object *obj, void *event_info)
{
static Eina_Bool paused = EINA_FALSE;
if (!paused)
{
elm_animator_pause(data);
elm_button_label_set(obj, "Resume");
paused = EINA_TRUE;
}
else
{
elm_animator_resume(data);
elm_button_label_set(obj, "Pause");
paused = EINA_FALSE;
}
}
static void
_stop(void *data, Evas_Object *obj, void *event_info)
{
elm_animator_stop(data);
}
EAPI int
elm_main(int argc, char **argv)
{
Evas_Object *win, *bg, *button, *rectangle;
Elm_Animator *animator;
win = elm_win_add(NULL, "animator", ELM_WIN_BASIC);
elm_win_title_set(win, "Animator");
evas_object_smart_callback_add(win, "delete,request", on_done, NULL);
bg = elm_bg_add(win);
elm_win_resize_object_add(win, bg);
evas_object_resize(bg, 200, 200);
evas_object_show(bg);
rectangle = evas_object_rectangle_add(evas_object_evas_get(win));
evas_object_color_set(rectangle, 0, 0, 255, 255);
evas_object_show(rectangle);
animator = elm_animator_add(NULL);
elm_animator_duration_set(animator, 1);
elm_animator_auto_reverse_set(animator, EINA_TRUE);
elm_animator_repeat_set(animator, UINT_MAX);
elm_animator_curve_style_set(animator, ELM_ANIMATOR_CURVE_IN_OUT);
elm_animator_operation_callback_set(animator, _op_cb, rectangle);
elm_animator_completion_callback_set(animator, _end_cb, NULL);
elm_animator_animate(animator);
button = elm_button_add(win);
elm_button_label_set(button, "Pause");
evas_object_resize(button, 50, 30);
evas_object_move(button, 10, 210);
evas_object_smart_callback_add(button, "clicked", _pause_resume, animator);
evas_object_show(button);
button = elm_button_add(win);
elm_button_label_set(button, "Stop");
evas_object_resize(button, 50, 30);
evas_object_move(button, 70, 210);
evas_object_smart_callback_add(button, "clicked", _stop, animator);
evas_object_show(button);
evas_object_resize(win, 200, 250);
evas_object_show(win);
elm_run();
evas_object_del(rectangle);
elm_animator_del(animator);
return 0;
}
ELM_MAIN()

View File

@ -3304,7 +3304,120 @@ EAPI Elm_Genlist_Item *elm_genlist_item_sorted_insert(Evas_Object *obj, const El
* default
*/
/* animator */
/**
* @page elm_animator_example_page_01 Animator usage
* @dontinclude animator_example_01.c
*
* For this example we will be using a bit of evas, you could animate a
* elementary widget in much the same way, but to keep things simple we use
* an evas_object_rectangle.
*
* As every other example we start with our include and a simple callback to
* exit the app when the window is closed:
* @skipline #include
* @until }
*
* This next callback is the one that actually creates our animation, it
* changes the size, position and color of a rectangle given to it in @a
* data:
* @until }
*
* Next we have a callback that prints a string, nothing special:
* @until }
*
* This next callback is a little more interesting, it has a state variable
* to know if the animation is currently paused or running, and it toogles
* the state of the animation accordingly:
* @until }
* @until }
* @until }
*
* Finally we have a callback to stop the animation:
* @until }
*
* As with every example we need to do a bit of setup before we can actually
* use an animation, but for the purposes of this example that's not relevant
* so let's just skip to the good stuff, creating an animator:
* @skipline animator_add
* @note Since elm_animator is not a widget we can give it a NULL parent.
*
* Now that we have an elm_animator we set it's duration to 1 second:
* @line duration_set
*
* We would also like our animation to be reversible, so:
* @line reverse_set
*
* We also set our animation to repeat as many times as possible, which will
* mean that _end_cb will only be called after UINT_MAX * 2 seconds(UINT_MAX
* for the animation running forward and UNIT_MAX for the animation running
* backwards):
* @line repeat_set
*
* To add some fun to our animation we will use the IN_OUT curve style:
* @line curve_style
*
* To actually animate anything we need an operation callback:
* @line operation_callback
*
* Even though we set our animation to repeat for a very long time we are
* going to set a end callback to it:
* @line completion_callback
* @note Notice that stoping the animation with the stop button will not make
* _end_cb be called.
*
* Now that we have fully set up our animator we can tell it to start
* animating:
* @line animate
*
* There's a bit more of code that doesn't really matter to use so we skip
* right down to our last interesting point:
* @skipline animator_del
* @note Because we created our animator with no parent we need to delete it
* ourselves.
*
* The full source code for this example can be found @ref
* animator_example_01_c "here"
*/
/**
* @page animator_example_01_c Animator example 01
* @include animator_example_01.c
* @example animator_example_01.c
*/
/**
* @addtogroup Animator Animator
* @ingroup Elementary
*
* @brief Functions to ease creation of animations.
*
* elm_animator is designed to provide an easy way to create animations.
* Creating an animation with elm_animator is as simple as setting a
* duration, an operating callback and telling it to run the animation.
* However that is not the full extent of elm_animator's ability, animations
* can be paused and resumed, reversed and the animation need not be linear.
*
* To run an animation you must specify at least a duration and operation
* callback, not setting any other properties will create a linear animation
* that runs once and is not reversed.
*
* @ref elm_animator_example_page_01 "This" example should make all of that
* very clear.
*
* @warning elm_animator is @b not a widget.
* @{
*/
/**
* @brief Type of curve desired for animation.
*
* The speed in which an animation happens doesn't have to be linear, some
* animations will look better if they're accelerating or decelerating, so
* elm_animator provides four options in this regard:
* @image html elm_animator_curve_style.png
* As can be seen in the image the speed of the animation will be:
* @li ELM_ANIMATOR_CURVE_LINEAR constant
* @li ELM_ANIMATOR_CURVE_IN_OUT start slow, speed up and then slow down
* @li ELM_ANIMATOR_CURVE_IN start slow and then speed up
* @li ELM_ANIMATOR_CURVE_OUT start fast and then slow down
*/
typedef enum
{
ELM_ANIMATOR_CURVE_LINEAR,
@ -3326,22 +3439,160 @@ EAPI Elm_Genlist_Item *elm_genlist_item_sorted_insert(Evas_Object *obj, const El
*/
typedef void (*Elm_Animator_Completion_Cb) (void *data);
/**
* @brief Create a new animator.
*
* @param[in] parent Parent object
*
* The @a parent argument can be set to NULL for no parent. If a parent is set
* there is no need to call elm_animator_del(), when the parent is deleted it
* will delete the animator.
*/
EAPI Elm_Animator* elm_animator_add(Evas_Object *parent);
/**
* Deletes the animator freeing any resources it used. If the animator was
* created with a NULL parent this must be called, otherwise it will be
* automatically called when the parent is deleted.
*
* @param[in] animator Animator object
*/
EAPI void elm_animator_del(Elm_Animator *animator) EINA_ARG_NONNULL(1);
/**
* Set the duration of the animation.
*
* @param[in] animator Animator object
* @param[in] duration Duration in second
*/
EAPI void elm_animator_duration_set(Elm_Animator *animator, double duration) EINA_ARG_NONNULL(1);
/**
* @brief Set the callback function for animator operation.
*
* @param[in] animator Animator object
* @param[in] func @ref Elm_Animator_Operation_Cb "Callback" function pointer
* @param[in] data Callback function user argument
*
* The @p func callback will be called with a frame value in range [0, 1] which
* indicates how far along the animation should be. It is the job of @p func to
* actually change the state of any object(or objects) that are being animated.
*/
EAPI void elm_animator_operation_callback_set(Elm_Animator *animator, Elm_Animator_Operation_Cb func, void *data) EINA_ARG_NONNULL(1);
/**
* Set the callback function for the when the animation ends.
*
* @param[in] animator Animator object
* @param[in] func Callback function pointe
* @param[in] data Callback function user argument
*
* @warning @a func will not be executed if elm_animator_stop() is called.
*/
EAPI void elm_animator_completion_callback_set(Elm_Animator *animator, Elm_Animator_Completion_Cb func, void *data) EINA_ARG_NONNULL(1);
/**
* @brief Stop animator.
*
* @param[in] animator Animator object
*
* If called before elm_animator_animate() it does nothing. If there is an
* animation in progress the animation will be stopped(the operation callback
* will not be executed again) and it can't be restarted using
* elm_animator_resume().
*/
EAPI void elm_animator_stop(Elm_Animator *animator) EINA_ARG_NONNULL(1);
/**
* Set the animator repeat count.
*
* @param[in] animator Animator object
* @param[in] repeat_cnt Repeat count
*/
EAPI void elm_animator_repeat_set(Elm_Animator *animator, unsigned int repeat_cnt) EINA_ARG_NONNULL(1);
/**
* @brief Start animation.
*
* @param[in] animator Animator object
*
* This function starts the animation if the nescessary properties(duration
* and operation callback) have been set. Once started the animation will
* run until complete or elm_animator_stop() is called.
*/
EAPI void elm_animator_animate(Elm_Animator *animator) EINA_ARG_NONNULL(1);
/**
* Sets the animation @ref Elm_Animator_Curve_Style "acceleration style".
*
* @param[in] animator Animator object
* @param[in] cs Curve style. Default is ELM_ANIMATOR_CURVE_LINEAR
*/
EAPI void elm_animator_curve_style_set(Elm_Animator *animator, Elm_Animator_Curve_Style cs) EINA_ARG_NONNULL(1);
/**
* Gets the animation @ref Elm_Animator_Curve_Style "acceleration style".
*
* @param[in] animator Animator object
* @param[in] cs Curve style. Default is ELM_ANIMATOR_CURVE_LINEAR
*/
EAPI Elm_Animator_Curve_Style elm_animator_curve_style_get(const Elm_Animator *animator); EINA_ARG_NONNULL(1);
/**
* @brief Sets wether the animation should be automatically reversed.
*
* @param[in] animator Animator object
* @param[in] reverse Reverse or not
*
* This controls wether the animation will be run on reverse imediately after
* running forward. When this is set together with repetition the animation
* will run in reverse once for each time it ran forward.@n
* Runnin an animation in reverse is accomplished by calling the operation
* callback with a frame value starting at 1 and diminshing until 0.
*/
EAPI void elm_animator_auto_reverse_set(Elm_Animator *animator, Eina_Bool reverse) EINA_ARG_NONNULL(1);
/**
* Gets wether the animation will automatically reversed
*
* @param[in] animator Animator object
*/
EAPI Eina_Bool elm_animator_auto_reverse_get(const Elm_Animator *animator) EINA_ARG_NONNULL(1);
/**
* Gets the status for the animator operation. The status of the animator @b
* doesn't take in to account elm_animator_pause() or elm_animator_resume(), it
* only informs if the animation was started and has not ended(either normally
* or through elm_animator_stop()).
*
* @param[in] animator Animator object
*/
EAPI Eina_Bool elm_animator_operating_get(const Elm_Animator *animator) EINA_ARG_NONNULL(1);
/**
* Gets how many times the animation will be repeated
*
* @param[in] animator Animator object
*/
EAPI unsigned int elm_animator_repeat_get(const Elm_Animator *animator) EINA_ARG_NONNULL(1);
/**
* Pause the animator.
*
* @param[in] animator Animator object
*
* This causes the animation to be temporarily stopped(the operation callback
* will not be called). If the animation is not yet running this is a no-op.
* Once an animation has been paused with this function it can be resumed
* using elm_animator_resume().
*/
EAPI void elm_animator_pause(Elm_Animator *animator) EINA_ARG_NONNULL(1);
/**
* @brief Resumes the animator.
*
* @param[in] animator Animator object
*
* Resumes an animation that was paused using elm_animator_pause(), after
* calling this function calls to the operation callback will happen
* normally. If an animation is stopped by means of elm_animator_stop it
* @b can't be restarted with this function.@n
*
* @warning When an animation is resumed it doesn't start from where it was paused, it
* will go to where it would have been if it had not been paused. If an
* animation with a duration of 3 seconds is paused after 1 second for 1 second
* it will resume as if it had ben animating for 2 seconds, the operating
* callback will be called with a frame value of aproximately 2/3.
*/
EAPI void elm_animator_resume(Elm_Animator *animator) EINA_ARG_NONNULL(1);
/**
* @}
*/
/* calendar */
typedef enum

View File

@ -14,18 +14,6 @@
} while (0)
/**
* @addtogroup Animator Animator
* @ingroup Elementary
*
* elm_animator is designed to provides animation frame.
* It is somewhat different with any others widgets however elm_animator
* might useful when your GUIs have animation.
* Basically, it computes normalized frame value for animation,
* provides additional functions to adjust this also.
*
*/
struct _Elm_Animator
{
#define ELM_ANIMATOR_MAGIC 0x40777770
@ -164,14 +152,6 @@ _animator_parent_del(void *data, Evas *evas __UNUSED__,
elm_animator_del(data);
}
/**
* Get the value of reverse mode.
*
* @param[in] animator Animator object
* @return EINA_TRUE is reverse mode
*
* @ingroup Animator
*/
EAPI Eina_Bool
elm_animator_auto_reverse_get(const Elm_Animator *animator)
{
@ -179,14 +159,6 @@ elm_animator_auto_reverse_get(const Elm_Animator *animator)
return animator->auto_reverse;
}
/**
* Get the value of repeat count.
*
* @param[in] animator Animator object
* @return Repeat count
*
* @ingroup Animator
*/
EAPI unsigned int
elm_animator_repeat_get(const Elm_Animator *animator)
{
@ -194,14 +166,6 @@ elm_animator_repeat_get(const Elm_Animator *animator)
return animator->repeat_cnt;
}
/**
* Set the animation acceleration style.
*
* @param[in] animator Animator object
* @param[in] cs Curve style. Default is ELM_ANIMATOR_CURVE_LINEAR
*
* @ingroup Animator
*/
EAPI Elm_Animator_Curve_Style
elm_animator_curve_style_get(const Elm_Animator *animator)
{
@ -209,14 +173,6 @@ elm_animator_curve_style_get(const Elm_Animator *animator)
return animator->curve_style;
}
/**
* Set auto reverse function.
*
* @param[in] animator Animator object
* @param[in] reverse Reverse or not
*
* @ingroup Animator
*/
EAPI void
elm_animator_auto_reverse_set(Elm_Animator *animator, Eina_Bool reverse)
{
@ -231,14 +187,6 @@ elm_animator_auto_reverse_set(Elm_Animator *animator, Eina_Bool reverse)
_animator_compute_no_reverse_repeat_count(animator->repeat_cnt);
}
/**
* Set the animation acceleration style.
*
* @param[in] animator Animator object
* @param[in] cs Curve style. Default is ELM_ANIMATOR_CURVE_LINEAR
*
* @ingroup Animator
*/
EAPI void
elm_animator_curve_style_set(Elm_Animator *animator,
Elm_Animator_Curve_Style cs)
@ -246,15 +194,6 @@ elm_animator_curve_style_set(Elm_Animator *animator,
ELM_ANIMATOR_CHECK_OR_RETURN(animator);
animator->curve_style = cs;
}
/**
* Set the operation duration.
*
* @param[in] animator Animator object
* @param[in] duration Duration in second
*
* @ingroup Animator
*/
EAPI void
elm_animator_duration_set(Elm_Animator *animator, double duration)
{
@ -263,16 +202,6 @@ elm_animator_duration_set(Elm_Animator *animator, double duration)
animator->duration = duration;
}
/**
* Set the callback function for animator operation.
* The range of callback function frame data is to 0 ~ 1
* User can refer this frame value for one's animation frame data.
* @param[in] animator Animator object
* @param[in] func Callback function pointer
* @param[in] data Callback function user argument
*
* @ingroup Animator
*/
EAPI void
elm_animator_operation_callback_set(Elm_Animator *animator,
Elm_Animator_Operation_Cb func,
@ -284,14 +213,6 @@ elm_animator_operation_callback_set(Elm_Animator *animator,
animator->animator_arg = data;
}
/**
* Add new animator.
*
* @param[in] parent Parent object
* @return animator object
*
* @ingroup Animator
*/
EAPI Elm_Animator *
elm_animator_add(Evas_Object *parent)
{
@ -307,14 +228,6 @@ elm_animator_add(Evas_Object *parent)
return animator;
}
/**
* Get the status for the animator operation.
*
* @param[in] animator Animator object
* @return EINA_TRUE is animator is operating.
*
* @ingroup Animator
*/
EAPI Eina_Bool
elm_animator_operating_get(const Elm_Animator *animator)
{
@ -322,13 +235,6 @@ elm_animator_operating_get(const Elm_Animator *animator)
return animator->on_animating;
}
/**
* Delete animator.
*
* @param[in] animator Animator object
*
* @ingroup Animator
*/
EAPI void
elm_animator_del(Elm_Animator *animator)
{
@ -342,15 +248,6 @@ elm_animator_del(Elm_Animator *animator)
free(animator);
}
/**
* Set the callback function for the animator end.
*
* @param[in] animator Animator object
* @param[in] func Callback function pointe
* @param[in] data Callback function user argument
*
* @ingroup Animator
*/
EAPI void
elm_animator_completion_callback_set(Elm_Animator *animator,
Elm_Animator_Completion_Cb func,
@ -362,13 +259,6 @@ elm_animator_completion_callback_set(Elm_Animator *animator,
animator->completion_arg = data;
}
/**
* Pause the animator.
*
* @param[in] animator Animator object
*
* @ingroup Animator
*/
EAPI void
elm_animator_pause(Elm_Animator *animator)
{
@ -377,13 +267,6 @@ elm_animator_pause(Elm_Animator *animator)
ecore_animator_freeze(animator->animator);
}
/**
* Resume the animator.
*
* @param[in] animator Animator object
*
* @ingroup Animator
*/
EAPI void
elm_animator_resume(Elm_Animator *animator)
{
@ -392,13 +275,6 @@ elm_animator_resume(Elm_Animator *animator)
ecore_animator_thaw(animator->animator);
}
/**
* Stop animator.
*
* @param[in] animator Animator object
*
* @ingroup Animator
*/
EAPI void
elm_animator_stop(Elm_Animator *animator)
{
@ -407,14 +283,6 @@ elm_animator_stop(Elm_Animator *animator)
_delete_animator(animator);
}
/**
* Set the animator repeat count.
*
* @param[in] animator Animator object
* @param[in] repeat_cnt Repeat count
*
* @ingroup Animator
*/
EAPI void
elm_animator_repeat_set(Elm_Animator *animator, unsigned int repeat_cnt)
{
@ -424,13 +292,6 @@ elm_animator_repeat_set(Elm_Animator *animator, unsigned int repeat_cnt)
animator->repeat_cnt = _animator_compute_reverse_repeat_count(repeat_cnt);
}
/**
* Animate now.
*
* @param[in] animator Animator object
*
* @ingroup Animator
*/
EAPI void
elm_animator_animate(Elm_Animator *animator)
{