rtk.queue_animation(kwargs) ¶

Low level function to begin an animation.

Warning

Using rtk.Widget:animate() instead is strongly preferred. You probably never need to call this global function directly, unless you're doing some low level operation and want to animate a non-widget attribute.

The arguments are the same as rtk.Widget:animate(), plus:

• key: a globally unique string that identifies this animation. Any active animation with the same key is cancelled and replaced if the dst value is different, otherwise the rtk.Future from the current running animation is returned.
• widget: an optional rtk.Widget to act upon. If defined, the attr field specifies a particular attribute to animate. If nil, you'll want to specify update in order to receive frame updates during the animation.
• attr: if widget is not nil, this is the widget's attribute that's being animated.
• update: an optional function that's invoked on each step of the animation, and which receives as arguments (value, target, attr, anim), where value is the current mid-animation value, target and attr correspond to the fields in the table passed to this function, and anim is the overall table holding the animation state (see below). The update callback is useful when you want to animate something other than a widget attribute.
• target: the target table against which the animation is occurring. This defaults to widget if nil.
• stepfunc: a function invoked to yield the next step of the animation, which is manditory when src/dst are neither scalar numbers nor tables containing numbers. The function takes two arguments (target, anim) which are the same as described in the update field above. The function must return the attribute value for the next frame in the animation.
• doneval: when the animation is finished, the target attribute will be set to this final value. Defaults to dst if not specified. If doneval needs to be nil, then use rtk.Attribute.NIL explicitly.

The animation state table passed to stepfunc is also the same table returned here and by rtk.Widget:get_animation(). It contains all user-supplied fields, fully resolved src and dst values, as well as these fields:

• pct: the percentage of the next step in the animation (from 0.0 to 1.0)
• pctstep: the percentage increase for each step in the animation (from 0.0 to 1.0). This is adaptive based on the value of rtk.fps at the time the animation is started.
• easingfunc: the easing function that the easing name resolved to
• future: an rtk.Future representing the state of the running animation
• resolve: a convenience function that can be used by custom step functions to translate pct value (from 0.0 to 1.0) to the actual value between src and dst.

Custom stepfunc functions can use the above fields from the animation state table to determine the attribute value for each frame in the animation. When stepfunc is invoked, the pct field represents the current value that's needed.

Parameters

kwargs

(table)

of attributes describing the animation

Return Values

(rtk.Future)

a Future object tracking the state of the asynchronous animation

Easing functions control the rate of change of the attribute being animated over time, and define the basic contour of the animation.

These easing function names can be used as the easing argument to either rtk.Widget:animate() (the preferred way to animate a widget) or rtk.queue_animation().

You can add custom easing functions to this table as well, keyed on the easing function name. The function receives one parameter -- a value between 0.0 and 1.0 that represents the animation's current position in time within the animation -- and returns the transformed value.