控件动画

控件动画是一种很常见的动画，常用于入场动画、离场动画、装饰用户界面和吸引用户注意力等。

一、动画类型

AWTK目前支持的动画有：

  • move：通过改变控件的位置形成动画效果。
  • value：通过改变控件的值形成动画效果。
  • opacity：通过改变控件的透明度形成动画效果。
  • scale：通过改变控件的缩放比例形成动画效果(目前需要vgcanvas)。
  • rotation：通过改变控件的旋转角度形成动画效果(目前需要vgcanvas)。
  • 其它任何数值型的属性。如x/y/w/h等等。

二、主要特色

  • 支持逆向模式。
  • 支持停止和暂停。
  • 支持定时(延迟)执行。
  • 支持重复模式(可指定次数)。
  • 支持往返模式(可指定次数)。
  • 支持多种插值算法(如加速和减速等)。
  • 支持同一控件多个动画并行执行。
  • 支持同一控件多个动画串行执行。
  • 支持时间倍率，让时间变快和变慢。
  • 支持按名称去开始、暂停、停止和销毁动画。

三、使用方法

1.方法一：通过函数widget_create_animator。

示例：

1.创建动画

  1. widget_create_animator(image1, "opacity(to=0, duration=500, yoyo_times=1000)");

2.暂停指定的动画

  1. widget_pause_animator(image1, "opacity");

3.暂停全部动画

  1. widget_pause_animator(NULL, NULL);

4.恢复/启动全部动画

  1. widget_start_animator(NULL, NULL);

在缺省情况下，动画创建后自动启动，完成后自动销毁。可以指定auto_start=false禁止创建后自动启动，指定参数auto_destroy=false禁止完成时自动销毁(控件销毁时仍然会自动销毁)。

动画创建、播放、暂停、停止、设置时间倍率和销毁等相关函数如下：

  1. /**
  2.  * @method widget_create_animator
  3.  * 创建动画。
  4.  * 除非指定auto_start=false，动画创建后自动启动。
  5.  * 除非指定auto_destroy=false，动画播放完成后自动销毁。
  6.  * 参数的格式类似函数调用, 如:
  7.  * opacity(from=0, to=255, yoyo_times=1000, duration=1000)
  8.  * move(x_from=10, x_to=100, y_from=10, y_to=100, duration=1000)
  9.  * 参考：https://github.com/zlgopen/awtk/blob/master/docs/widget_animator.md
  10.  *
  11.  * @annotation ["scriptable"]
  12.  * @param {widget_t*} widget 控件对象。
  13.  * @param {const char*} animation 动画参数。
  14.  *
  15.  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  16.  */
  17. ret_t widget_create_animator(widget_t* widget, const char* animation);
  19. /**
  20.  * @method widget_start_animator
  21.  * 播放动画。
  22.  * 1.widget为NULL时，播放所有名称为name的动画。
  23.  * 2.name为NULL时，播放所有widget相关的动画。
  24.  * 3.widget和name均为NULL，播放所有动画。
  25.  * @annotation ["scriptable"]
  26.  * @param {widget_t*} widget 控件对象。
  27.  * @param {const char*} name 动画名称。
  28.  *
  29.  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  30.  */
  31. ret_t widget_start_animator(widget_t* widget, const char* name);
  33. /**
  34.  * @method widget_set_animator_time_scale
  35.  * 设置动画的时间倍率，<0: 时间倒退，<1: 时间变慢，>1 时间变快。
  36.  * 1.widget为NULL时，设置所有名称为name的动画的时间倍率。
  37.  * 2.name为NULL时，设置所有widget相关的动画的时间倍率。
  38.  * 3.widget和name均为NULL，设置所有动画的时间倍率。
  39.  * @annotation ["scriptable"]
  40.  * @param {widget_t*} widget 控件对象。
  41.  * @param {const char*} name 动画名称。
  42.  * @param {float_t} time_scale 时间倍率。
  43.  *
  44.  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  45.  */
  46. ret_t widget_set_animator_time_scale(widget_t* widget, const char* name, float_t time_scale);
  48. /**
  49.  * @method widget_pause_animator
  50.  * 暂停动画。
  51.  * 1.widget为NULL时，暂停所有名称为name的动画。
  52.  * 2.name为NULL时，暂停所有widget相关的动画。
  53.  * 3.widget和name均为NULL，暂停所有动画。
  54.  * @annotation ["scriptable"]
  55.  * @param {widget_t*} widget 控件对象。
  56.  * @param {char*} name 动画名称。
  57.  *
  58.  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  59.  */
  60. ret_t widget_pause_animator(widget_t* widget, const char* name);
  62. /**
  63.  * @method widget_stop_animator
  64.  * 停止动画(控件的相应属性回归原位)。
  65.  * 1.widget为NULL时，停止所有名称为name的动画。
  66.  * 2.name为NULL时，停止所有widget相关的动画。
  67.  * 3.widget和name均为NULL，停止所有动画。
  68.  * @annotation ["scriptable"]
  69.  * @param {widget_t*} widget 控件对象。
  70.  * @param {char*} name 动画名称。
  71.  *
  72.  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  73.  */
  74. ret_t widget_stop_animator(widget_t* widget, const char* name);
  76. /**
  77.  * @method widget_destroy_animator
  78.  * 销毁动画。
  79.  * 1.widget为NULL时，销毁所有名称为name的动画。
  80.  * 2.name为NULL时，销毁所有widget相关的动画。
  81.  * 3.widget和name均为NULL，销毁所有动画。
  82.  * @annotation ["scriptable"]
  83.  * @param {widget_t*} widget 控件对象。
  84.  * @param {char*} name 动画名称。
  85.  *
  86.  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  87.  */
  88. ret_t widget_destroy_animator(widget_t* widget, const char* name);

2.方法二：在XML中指定

animation参数的格式，类似与函数调用。多个参数可以用『;』分隔。如：

  1.  <button name="inc_value" text="Inc" animation="opacity(from=0, to=255, yoyo_times=1000, duration=1000)"/>
  2.  <button name="dec_value" text="Dec" animation="move(x_from=10, x_to=100, y_from=10, y_to=100, duration=1000);opacity(from=0, to=255, yoyo_times=1000, duration=1000)"/>

此方法最为简单，后续可以在程序中通过动画名字，对动画进行启动和暂停等控制。

3.方法三：直接使用(不再推荐)

使用控件动画时，一般需要创建动画、设置参数、设置模式和启动动画四个步骤。如：

  1.   animator = widget_animator_move_create(image, 1000, delay, EASING_SIN_INOUT);
  2.   widget_animator_move_set_params(animator, image->x, image->y, image->x + 100, image->y + 100);
  3.   widget_animator_set_yoyo(animator, 10);
  4.   widget_animator_start(animator);

此方法比较麻烦，不再推荐使用。

四、可用参数

1.公共参数

  • name 动画名称(缺省为动画的类型如move)。
  • delay 延迟启动时间(毫秒)。
  • duration 时长(毫秒)。
  • easing 插值算法(见后面描述)。
  • yoyo_times 往返的次数(x2)，为0视为永久播放。
  • repeat_times 重复的次数，为0视为永久播放。
  • auto_start 创建后自动启动(缺省为true)。
  • auto_destroy 完成后自动销毁(缺省为true)。

以下参数的缺省值为控件当前对应的值。

2. widget_animator_move动画的参数

  • x_from x起始位置。
  • y_from y起始位置。
  • x_to x结束位置。
  • y_to y结束位置。

3. widget_animator_value动画的参数

  • from 起始值。
  • to 结束值。

4. widget_animator_opacity动画的参数

  • from 起始值(0-255)。
  • to 结束值(0-255)。

5. widget_animator_scale动画的参数

  • x_from x方向缩放起始值。
  • y_from y方向缩放起始值。
  • x_to x方向缩放结束值。
  • y_to y方向缩放结束值。

6. widget_animator_rotation动画的参数

  • from 起始值(弧度)。
  • to 结束值(弧度)。

7. 其它数值型属性动画的参数

  • from 起始值。
  • to 结束值。

五、插值算法名称(easing)

请参考：插值算法名称

六、完整示例

完整示例请参考：demos/demo_animator_app.c

运行下列命令查看各种动画的效果：

  1. ./bin/demo_animator

五、其它

1.动画对象一般不需主动销毁，在动画结束或控件被销毁时自动销毁。

2.如使用控件的入场动画，一般不要启用窗口动画。