Low level function to begin an animation
Low level function to begin an animation.
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
key: a globally unique string that identifies this animation. Any active animation with the same key is cancelled and replaced if the
dstvalue is different, otherwise the
rtk.Futurefrom the current running animation is returned.
widget: an optional
rtk.Widgetto act upon. If defined, the
attrfield specifies a particular attribute to animate. If nil, you'll want to specify
updatein order to receive frame updates during the animation.
widgetis 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
valueis the current mid-animation value,
attrcorrespond to the fields in the table passed to this function, and
animis the overall table holding the animation state (see below). The
updatecallback 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
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
updatefield 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
dstif not specified. If
donevalneeds to be nil, then use
The animation state table passed to
stepfunc is also the same table returned here and
rtk.Widget:get_animation(). It contains all user-supplied fields, fully resolved
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.fpsat the time the animation is started.
easingfunc: the easing function that the
easingname resolved to
rtk.Futurerepresenting the state of the running animation
resolve: a convenience function that can be used by custom step functions to translate
pctvalue (from 0.0 to 1.0) to the actual value between
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.
of attributes describing the animation
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.
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.