From: gastal Date: Thu, 16 Jun 2011 18:13:03 +0000 (+0000) Subject: Elementary: elm_animator documentation and example. X-Git-Tag: REL_F_I9500_20120323_1~17^2~2554 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=6f61d0bb114017aedf2c62df6c44fe6694d8ff6f;p=framework%2Fuifw%2Felementary.git Elementary: elm_animator documentation and example. git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/elementary@60405 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- diff --git a/doc/img/elm_animator_curve_style.png b/doc/img/elm_animator_curve_style.png new file mode 100644 index 0000000..8802b2b Binary files /dev/null and b/doc/img/elm_animator_curve_style.png differ diff --git a/src/examples/animator_example_01.c b/src/examples/animator_example_01.c new file mode 100644 index 0000000..eea2bb6 --- /dev/null +++ b/src/examples/animator_example_01.c @@ -0,0 +1,103 @@ +//Compile with: +//gcc -g `pkg-config --cflags --libs elementary` animator_example_01.c -o animator_example_01 + +#include +#include + +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() diff --git a/src/lib/Elementary.h.in b/src/lib/Elementary.h.in index 45924dc..8d6eb50 100644 --- a/src/lib/Elementary.h.in +++ b/src/lib/Elementary.h.in @@ -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 diff --git a/src/lib/elm_animator.c b/src/lib/elm_animator.c index 3d1993b..5808495 100644 --- a/src/lib/elm_animator.c +++ b/src/lib/elm_animator.c @@ -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) {