--- /dev/null
+//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()
* 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,
*/
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
} 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
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)
{
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)
{
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)
{
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)
{
_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)
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)
{
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,
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)
{
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)
{
return animator->on_animating;
}
-/**
- * Delete animator.
- *
- * @param[in] animator Animator object
- *
- * @ingroup Animator
- */
EAPI void
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,
animator->completion_arg = data;
}
-/**
- * Pause the animator.
- *
- * @param[in] animator Animator object
- *
- * @ingroup Animator
- */
EAPI void
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)
{
ecore_animator_thaw(animator->animator);
}
-/**
- * Stop animator.
- *
- * @param[in] animator Animator object
- *
- * @ingroup Animator
- */
EAPI void
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)
{
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)
{