Module animate

Synopsis

Functions
rtk.queue_animation()

Low level function to begin an animation

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
  • 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.

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

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().

Visual aid

See easings.net for an excellent visual aid on the behavior of each easing functions. All the easing functions listed on that website are supported by rtk.

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.

linear

linear

in-sine

in-sine

out-sine

out-sine

in-out-sine

in-out-sine

in-quad

in-quad

out-quad

out-quad

in-out-quad

in-out-quad

in-cubic

in-cubic

out-cubic

out-cubic

in-out-cubic

in-out-cubic

in-quart

in-quart

out-quart

out-quart

in-out-quart

in-out-quart

in-quint

in-quint

out-quint

out-quint

in-out-quint

in-out-quint

in-expo

in-expo

out-expo

out-expo

in-out-expo

in-out-expo

in-circ

in-circ

out-circ

out-circ

in-out-circ

in-out-circ

in-back

in-back

out-back

out-back

in-out-back

in-out-back

in-elastic

in-elastic

out-elastic

out-elastic

in-out-elastic

in-out-elastic

in-bounce

in-bounce

out-bounce

out-bounce

in-out-bounce

in-out-bounce