obj.animate(props, time, ease, call, params, wait, waitedCall, waitedParams, loop, loopCount, loopWait, loopCall, loopParams, loopWaitCall, loopWaitParams, loopPick, rewind, rewindWait, rewindCall, rewindParams, rewindWaitCall, rewindWaitParams, rewindTime, rewindEase, startCall, startParams, animateCall, animateParams, sequence, sequenceCall, sequenceParams, sequenceReverse, sequenceRatio, ticker, cjsProps, css, protect, override, from, set, id, events, sequenceTarget, dynamic, drag, clamp, startPaused, clean, obj, seriesWait, sequenceWait, rate, pauseOnBlur, easeAmount, easeFrequency, timeUnit, timeCheck, noAnimateCall, pathDamp, rewindPick)
zim DisplayObject method
powered by createjs.Tween (TweenJS)
DESCRIPTION
Animate object properties in time (s).
You can set various types of easing like bounce, elastic, back, linear, sine, etc.
Handles callbacks, delays, loops, rewinds, relative, series and sequences of animations.
SEE:
https://zimjs.com/animation
Shape Animation
ZIM animate() lets you animate one Squiggle to another or one Blob to another
See the props parameter under the convenience properties for shape and blobShift
Advanced Animation
ZIM animate() lets you animate along a path made with a zim Squiggle or Blob
These paths can be edited by the user and the animation will still work
The paths themselves can be animated or wiggled.
Orient and Flipping are available.
Dynamic speed can be set with percentSpeed and tied in to Accelerator and MotionController.
Scrubbing animation and path animation is also supported with percentComplete.
This can be used with a Slider, Dial, MotionController, Parallax or general coding.
Dragging along a path is as easy as setting the drag parameter to true.
This can be done with while animating or with the animation paused.
ZIM EXTRA! provides animation based on animation.
This allows for setting zoom, depth, speed, fade, etc. based on target y value while animating on a path
but EXTRA! also opens up endless possibilities as the input and output does not have to be the target.
This means that animation can also control properties of other objects.
SEE:
https://zimjs.com/nio/
NOTE to temporarily prevent animations from starting set ANIMATE to false
NOTE see pauseAnimate(state, ids) and stopAnimate(ids) for controlling tweens when running
NOTE set mouseEnabled of target before calling animate as animate itself sets mouseEnabled and then resets to original after a delay
EXAMPLE
const circle = new Circle(50, red)
.center()
.alp(0)
.sca(0)
.animate({alpha:1, scale:1}, .7, null, done);
function done(target) {
// target is circle if params is not set
target.drag();
}
// or with ZIM DUO and from parameter:
const circle = new Circle(50, red)
.center()
.animate({
props:{alpha:0, scale:0},
time:.7,
from:true
});
// note: there was no need to set alpha and scale to 0 before the animation
// because from will animate from property values in props {alpha:0, scale:0}
// to the present set values - which are 1 and 1 for the default scale and alpha.
// This allows you to place everything how you want it to end up
// and then easily animate to this state.
// An extra advantage of this is that you can use the ANIMATE constant to skip animations while building
// See the https://zimjs.com/ornamate.html example
// RELATIVE animation
// rotate the rectangle 360 degrees from its current rotation
rectangle.animate({rotation:"360"});
// pulse circle
var circle = new Circle(50, red)
.center()
// pulse circle from scale 0 - 1 every second (use ZIM DUO)
.animate({
props:{scale:0},
time:.5,
loop:true,
rewind:true,
from:true
});
// toggle pause the circle when stage is pressed
S.on("stagemousedown", ()=>{
circle.pauseAnimate(!circle.paused);
});
EXAMPLE
// using ZIM VEE value:
// this will animate the alpha to between .5 and 1 in either 1 second or 2 seconds
circle.animate({alpha:{min:.5, max:1}}, [1, 2]);
EXAMPLE
// Dynamic Animation
const rect = new Rectangle(200,200,red)
.centerReg()
.animate({
props:{rotation:360},
loop:true,
time:2,
ease:"linear",
dynamic:true,
set:{percentSpeed:0} // no speed to start
});
// example using a Slider to set speed from 0 to 5 times as fast
const slider = new Slider(0,500)
.pos(100, 100)
.change(()=>{
rect.percentSpeed = slider.value;
});
// example using an Accelerator and MotionController
// to set speed from -200 to 200 percent
// depending on mouse position
// multiple targets including Dynamo and Scroller objects can be added to Accelerator
// if adding multiple objects, use an array new Accelerator([rect, otherObject, anotherObject])
new MotionController({
target:new Accelerator(rect),
type:"mousemove",
minPercentSpeed:-200,
maxPercentSpeed:200
});
EXAMPLE
// using STYLE with animate()
STYLE = {props:{noPick:{scale:2}}, rewind:true};
new Circle(30,orange).pos(100,100,LEFT,BOT).animate();
new Circle(30,orange).pos(100,100,RIGHT,BOT).animate();
EXAMPLE
// Series example animating a circle in square formation
// Also showing that the series can include multiple targets
// Click on the stage to pause or unpause the animation
const rect = new Rectangle({color:pink})
.centerReg()
.sca(0); // hiding it to start
const circle = new Circle({color:purple}) // chaining the rest
.pos(400,300)
.animate({ // circle will be the default object for the inner animations
props:[
// an array of animate configuration objects
{props:{x:600, y:300, scale:2}},
{props:{x:600, y:500, scale:1}, call:function(){zog("part way");}},
{props:{x:400, y:500}, time:.5, ease:"quadInOut"},
{target:rect, props:{scale:3}, time:1, rewind:true, ease:"quadInOut"},
{props:{x:400, y:300}}
],
time:1, // will be the default time for the inner animations
ease:"backOut", // will be the default ease for the inner animations
id:"square", // will override any id set in the inner animations
loop:true,
loopCount:3,
// note - no rewind or from parameters
call:() => {zog("done");}
});
var paused = false;
S.on("stagemousedown", ()=>{
paused = !paused;
pauseAnimate(paused, "square");
});
EXAMPLE
// sequence example to pulse two circles
const circles = new Container(W, H).addTo();
const circle1 = new Circle(50, red).center(circles);
const circle2 = new Circle(50, blue).center(circles).mov(70);
circles.animate({
props:{scale:0},
time:.5,
loop:true,
rewind:true,
from:true,
sequence:.5
});
EXAMPLE
// animate() can animate any object property
// just use the animate function and pass in the object as the first parameter:
const obj = {age:10}
animate(obj, {age:20}, 1);
interval(.05, ()=>{
zog(obj.age);
});
// or if you have a THREEJS mesh
// use quotes to animate a dot property:
animate(mesh, {"rotation.y":360*RAD}, 10);
// or to use the ZIM DUO technique with the animate function (not method),
// the normal obj parameter is called target so as not to conflict
// with the old obj parameter which is now props but is kept for legacy purposes ;-)
animate({
target:mesh,
props:{"rotation.y":360*RAD},
time:10,
loop:true,
rewind:true
});
// or CSS properties - see the CSS parameter for setup info
zss("tagID").opacity = 1; // set this even if it is default
animate(zid("tagID"), {opacity:0}, 2); // etc.
EXAMPLE
// Animate along a Squiggle or Blob path
// see https://zimjs.com/nio/ examples
// see https://zimjs.com/explore/squiggleAnimate.html for more
// see https://zimjs.com/explore/blobAnimate.html for more
// see https://zimjs.com/explore/blobAnimate2.html for more
const line = new Squiggle().center();
new Circle(10, red).addTo().animate({path:line}, 1);
EXAMPLE
// animate across colors
const colors = series("#f0f","#0f0","#00f","#f00","#ff0").mix();
new Rectangle(W,H,colors)
.addTo()
.animate({
props:{color:colors},
loopPick:true,
rewindPick:true
});
PARAMETERS
** supports DUO - parameters or single object with properties below
** supports VEE - parameters marked with ZIM VEE mean a zim Pick() object or Pick Literal can be passed
Pick Literal formats: [1,3,2] - random; {min:10, max:20} - range; series(1,2,3) - order, function(){return result;} - function
** supports OCT - parameter defaults can be set with STYLE control (like CSS)
NOTE: can target parameters in general like
STYLE = {loop:true};
to target animate specifically use
STYLE = {Animate:{loop:true}};
NOT STYLE = {animate:{loop:true}} as lowercase animate conflicts with setting a animate convenience style
NOTE: to target the props, use noPick: STYLE = {props:{noPick:{scale:2}}}
NOTE: target cannot be styled
props - the object literal holding properties and values to animate
Basic examples: {x:200} or {rotation:360, alpha:0} or {scale:4} or {x:300, y:300, scale:"2"} (relative scale)
There are custom options below including Convenience, ZIM VEE, Relative, and Series properties.
** Before ZIM 7.1, this parameter was called obj - as to not conflict with CreateJS TweenJS props (now renamed cjsProps)
obj is still available as a parameter name for backwards compatibility when using a ZIM DUO configuration object
CONVENIENCE PROPERTIES
scale - for scaleX and scaleY
color - on ZIM shapes for setColorRange() and animate colorRange from 0-1
** this property cannot be run in a series - rather animate in a call function to accomplish a series of color changes
note - animate from one note to another when animating a ZIM Synth tone()
note ("A", "C2", "C#" or "Bf", etc.) is coverted to frequency
shape - animate from one ZIM Squiggle to another or one ZIM Blob to another
for now, the matching Sqiggle or Blob must have the same number of points
to pause or stop a shape tween use the animate id parameter
blobShift - a number of points to shift the points of a Blob in clockwise direction
this is when using a shape tween that is a Blob - can be negative
path - pass in a Blob or Squiggle to animate along path
https://zimjs.com/nio/path.html
If the shape has lockControls set to false (the default) then the animation will be dynamic
and adjust as the shape is changed.
If a set animation path is desired then set the shape's lockControls to true
NOTE: Do not re-amimate an object that is being animated on a path
use a Container and animate the container on the path
and animate the object inside the container - otherwise percentComplete conflicts
startPercent - (default 0) set to a percent for where to start the target animating
ZIM Bead objects will be given a startPercent that matches their start percentage
currently not supported when dragging on path - it is very complicated
percent - (default 100) how much percent to animate from the startPercent
by default, the target will travel once along the path from its start position (startPercent)
this can be less than the startPercent to make animation travel backwards on the path
the percent can also be bigger than 100 as well as less than 0
so a percent:300 will travel three times along the path - and then rewind if rewind is set
and a percent of -150 will travel one and half times backwards along the path from the startPercent
currently not supported when dragging on path - it is very complicated
orient - an object with x and y to aim the target at
https://zimjs.com/nio/orient.html
when a path is used this will default to rotate to orient to path
(for a Sprite, add the Sprite to a Container and animate the Container)
can set to false for no rotation
can set to any object with an x, y point such as a circle on the stage - or {x:0, y:0} or a new zim Point, etc.
flip - default true when orient is true
true will flip the object horizontally when its x direction goes negative
https://zimjs.com/nio/flip.html
this will also work with orient to make sure the target is not upside down
if object is pre-rotated then 90,-90,270 should work as ZIM will swap the the scaleX and scaleY
but any unusual starting angles may not flip as desired - so put these in a Container and animate the container
flipVertical - setting flipVertical to true will flip the object vertically when its y direction goes negative
this will also work with orient to make sure the target is not upside down
EXTRA! - the following convenience properties are available for ZIM EXTRA! (also see extra below)
https://zimjs.com/nio/extra.html
zoom - an array that represents scale proportions based on target's y position
[inputMin, inputMax, outputMin(default 0), outputMax(default H)] the outputs will be constrained to the provided values
zoom:[.5,1.5] scales the target based on its y position - animating y or along a path will show scaling
zoom:10 - is like zoom:[0,10]
zoom:true - is like zoom:[0,1]
zoom:[1,3,H/2-100,H/2+200] would scale from 1 to 3 in this region and stay at 1 or 3 outside this region
speed - an array that represents animation percentSpeed based on target's y position
[inputMin, inputMax, outputMin(default 0), outputMax(default H)] the outputs will be constrained to the provided values
speed:[20,100] sets percentSpeed based on target y position - animating y or along a path will have changing speed
speed:40 - is like speed:[0,40]
speed:true - is like speed:[0,100]
** will set dynamic property to true - as percentSpeed needs dynamic property set to true
layer - an array that represents ratio of layer proportions based on target's y position
[inputMin, inputMax, outputMin(default 0), outputMax(default H)] the outputs will be constrained to the provided values
layer:[0,1] sets current layer based on target y position - animating y or along a path will have changing layers
layer:1 - is like layer:[0,1]
layer:true - is like layer:[0,target.parent.numChildren-1]
fade - an array that represents ratio of alpha based on target's y position
[inputMin, inputMax, outputMin(default 0), outputMax(default H)] the outputs will be constrained to the provided values
fade:[.5,1] sets current alpha based on target y position - animating y or along a path will have changing alpha
fade:1 - is like fade:[0,1]
fade:true - is like fade:[0,1]
fade:[0,1,H/2-100,H/2+200] - would change alpha in this y region
extra - in addition to the convenience properties above, ZIM EXTRA! has a more general and complete format:
Pass in a single EXTRA! object or an array of EXTRA! objects: extra:{} or extra:[{},{},{}]
The object has the following properties - all are optional except the outputProp which is required:
|ZIM VEE| - each object below optionally accepts a ZIM VEE value for Pick.choose() to pick randomly from
inputObj - (default target) - the object with the input property - probably the animation target but could be any object
inputProp - (default "y") - a string of the property name for the input - "x", "rotation", etc.
inputMin - (default 0) - the minimum input value for the calculation - also see constrain
inputMax - (default W if x inputProp else H) - the maximum input value for the calculation - also see constrain
outputObj - (default target) - the object whose output property is being changed - probably the animation target but could be any object
outputProp - (default "scale") - a string of the property name of the output - "scale", "layer", "rotation", etc.
outputMin - (default 0) - the minimum output value for the calculation - also see constrain
outputMax - (default 1) - the maximum output value for the calculation - also see constrain
factor - (default 1) setting factor to -1 will reverse the direction of the animation
outputRound - (default false) set to true to receive rounded output values
constrain - (default true) constrain the output value to outputMin and outputMax
set to false to let values go beyond provided mins and maxes
this is quite usual when a proportion is easily figured at a certain range
and continued increase or decrease is desired outside the range - just turn constrain to false.
EXAMPLES:
extra:{outputProp:"scaleX"} would animate the scaleX of the target from 0-1 over the stage height
extra:{outputObj:circle, outputProp:"alpha"} would animate the alpha of circle based on the animated target's y position
extra:{inputObj:circle, inputProp:"x", inputMax:W, outputProp:"level"} would animate the target's child index as the circle's x goes across the screen
** in the last two examples, circle is a different object than the target of the animation - circle might be animating independently or based on a Slider value, etc.
|ZIM VEE| - each props property value optionally accepts a ZIM VEE value for Pick.choose() to pick randomly from (except the EXTRA! properties which accept ZIM VEE values inside)
these will be picked again if the loopPick parameter is true (default false)
RELATIVE VALUES: you can pass in relative values by putting the numbers as strings
rotation:"360" will animate the rotation of the object 360 degrees from its current rotation
whereas rotation:360 will animate the rotation of the object to 360 degrees
DOT PROPERTIES: you can animate properties on properties using quotes:
Here is animate used as a function to animate a threejs mesh
animate(mesh, {"rotation.y":360*RAD}, 5000);
CSS PROPERTIES: animate can animate CSS properties
ZIM's CreateJS 1.3.2 has the CreateJS CSS Pluging installed
Set the css parameter to true and see the CSS parameter for more details
ANIMATION SERIES: if you pass in an array for the props value, then this will run an animation series
The array must hold animate configuration objects:
[{props:{scale:2}, time:1, rewind:true}, {target:different, props:{x:100}}, etc.]
If you run animate as a method on an object then this is the default object for the series
but you can specify a target to override the default
By default, each animation runs after the other, but a negative wait can be set
eg. if wait:-1 is set on the third animation in the series it starts 1 second before the second animation ends
The default time and tween are as provided in the main parameters
but you can specify these to override the default
The id of the main parameters is used for the whole series and cannot be overridden
The override parameter is set to false and cannot be overridden
All other main parameters are available except rewind, sequence and from
(rewind and from are available on the inner tweens - for sequence: the initial animation is considered)
You currently cannot nest animation series
Note: if any of the series has a loop and loops forever (a loopCount of 0 or no loopCount)
then this will be the last of the series to run
Note: color cannot be animated in a series - rather animate in a call function to accomplish a series of color changes
Note: a sequence cannot be seriesed and a series cannot be sequenced
Note: series with dot properties (like rotation.x for threejs) could have problems with from and set
time - |ZIM VEE| (default 1) the time for the tween in seconds (also see ZIM TIME constant)
see also the rate parameter and property to dynamically change the time the animation takes (its speed)
ease - |ZIM VEE| (default "quadInOut") the equation type for easing ("bounceOut", "elasticIn", "backInOut", "linear", etc)
no ease is "linear" or "none"- this is often good for constantly falling or rotating objects
also ZIM preset eases: "snapIn", "snapOut", "snapInOut", "ballisticIn", "ballisticOut", "ballisticInOut", "slowmoIn", "slowmoOut", "slowmoInOut"
** CUSTOM EASE: see
https://zimjs.com/ease for custom ease which can be passed in here as a value like so:
ease:zimEase([.2,.4,.6,.8]) // would be linear
ease:zimEase([[1.45,-0.57,0.67,0.55], [0.34,0.44,1.43,-0.31]]) // is the same as "snapInOut"
// see the zimEase() function in the docs for the Code module
see CreateJS easing:
https://www.createjs.com/docs/tweenjs/classes/Ease.html
also see easeAmount and easeFrequency parameters to adjust certain eases like back and elastic
call - (default null) the function to call when the animation is done
params - (default target) a single parameter for the call function (eg. use object literal or array)
wait - |ZIM VEE| (default 0) seconds to wait before doing animation
can be negative for series to start animation before previous animation ends
also see the waiting property
waitedCall - (default null) calls function after wait is done if there is a wait
waitedParams - (default target) parameters to send waitedCall function
loop - (default false) set to true to loop animation
loopCount - |ZIM VEE| (default 0) if loop is true how many times it will loop (0 is forever)
loopWait - |ZIM VEE| (default 0) seconds to wait before looping - will automatically set loop to true
loopCall - (default null) calls function after loop and loopWait (not including last loop)
loopParams - (default target) parameters to send loopCall function
loopWaitCall - (default null) calls function after at the start of loopWait
loopWaitParams - (default target) parameters to send loopWaitCall function
loopPick - (default false) remake any ZIM VEE (Pick) props for the next loop (thanks GSAP)
rewind - |ZIM VEE| (default false) set to true to rewind (reverse) animation (doubles animation time)
rewindWait - |ZIM VEE| (default 0) seconds to wait in the middle of the rewind
rewindCall - (default null) calls function at middle of rewind after rewindWait
rewindParams - (default target) parameters to send rewindCall function
rewindWaitCall - (default null) calls function at middle of rewind before rewindWait
rewindWaitParams - (default target) parameters to send rewindCall function
rewindTime - (default time) set the time in seconds for the rewind portion of an animation
rewindEase - (default null) overwrite the ease for the rewind direction
this assumes that In is at the start of the rewind and Out is at the end of the rewind
so setting rewindEase:"bounceOut" will bounce back at the start of the animation
note - setting ease:"bounceOut" will bounce at the end of the animation
this allows for a normal start with a bounce and then a normal start at rewind and a bounce
startCall - (default null) calls function at the start of actual animation and after any wait (and waitedCall)
this is basically the same as the waitedCall but will also be called at the start of animation when there is no waitedCall
startParams - (default target) parameters to send startCall function
animateCall - (default null) calls function every animation
this runs an alternate Ticker so does not aversely affect animate without an animateCall
alternatively, can set events:true and capture an "animation" event - but that is only for animations on ZIM objects
wherease animateCall will always be available
for instance, if using the animate() function on object literals, HTML/CSS tags or threejs objects, etc.
animateParams - (default target) parameters to send animateCall function
sequence - (default 0) the delay time in seconds to run on children of a container or an array of target animations
with the addition of ZIM VEE object to the target, you must noPick the array
for example, target = container or target = {noPick:[a,b,c]} and sequence = 1
would run the animation on the first child and then 1 second later, run the animation on the second child, etc.
or in the case of the array, on element a and then 1 second later, element b, etc.
If the loop prop is true then sequenceCall below would activate for each loop
For an array, you must use the zim function with a target parameter - otherwise you can use the ZIM 4TH method
Note: a sequence cannot be seriesed and a series cannot be sequenced
Note: for a sequence animate() give the animate() an id and pauseAnimate() or stopAnimate() that id.
sequenceCall - (default null) the function that will be called for each sequence animation
Note: the value of the sequenceCall parameter will be the object that just ended animation unless there is a sequenceParams value
To get the object about to animate use the startCall parameter
sequenceParams - (default null) a parameter sent to the sequenceCall function
sequenceReverse - |ZIM VEE| (default false) set to true to sequence through container or array backwards
sequenceRatio - (default null) set to a value to adjust the rate based on item ratio property
see
https://zimjs.com/016/normalize.html
see Container() ratio property and normalize() method which give a ratio property.
This will automatically set sequence to 0 so that each item in the container (or tile) is animated individually
the sequenceRate value will be multiplied by the item's ratio and then added to the rate (see rate parameter)
So if the sequenceRate is 2 and the rate is the default 1,
then an item with a ratio property of 0 would be at rate 1
and items with a ratio property of .5 would be at rate 1+2*.5 = 2
and items with a ratio property of 1 would be at rate 1+2*1 = 3
ticker - (default true) set to false to not use an automatic Ticker function
cjsProps - (default {override: true}) legacy - allows you to pass in CreateJS TweenJS configuration properties
css - (default false) set to true if there is no Frame
ZIM's CreateJS 1.3.2 has the CreateJS CSS Pluging installed
But other CreateJS versions will need the plugin available here:
https://d309knd7es5f10.cloudfront.net/CSSPlugin01.js
Add that at the top of your code in a script tag
and at the top of the main script install:
createjs.CSSPlugin.install();
<script>
// other versions of CreateJS need to import and install CSS Plugin
// createjs.CSSPlugin.install();
// the property must be set before you can animate
zss("tagID").opacity = 1; // set this even if it is default
animate(zid("tagID"), {opacity:0}, 2); // etc.
// for transform styles use:
zss("tagID").transform = "translate(20px, 30px)"; // set this even if it is default
animate({
target:zid("tagID"),
props:{transform:"translate(100px, 150px)"},
time:2,
loop:true,
rewind:true
});
</script>
protect - (default false) protects animation from being interrupted before finishing
unless manually interrupted with stopAnimate()
protect will default to true if loop or rewind parameters are set
but this can be overriden if protect is set to false
override - (default true) subesequent tweens of any type on object cancel all earlier tweens on object
set to false to allow multiple tweens of same object
from - |ZIM VEE| (default false) set to true to animate from obj properties to the current properties set on target
set - |ZIM VEE| (default null) an object of properties to set on the target to start (but after the wait time)
id - (default null) set to String to use with pauseAnimate(state, id) and stopAnimate(id) - thanks Sean Berwick for typo catch
series animate gets only one overall id - so no id per animation object
events - (default false) set to true to receive an "animation" event on the target (or Container with a Container sequence)
sequenceTarget - (default null) used internally for processing sequence animations
dynamic - (default false) set to true to turn on dynamic speed animation via the percentSpeed property
setting perecentSpeed (default 100) will adjust the speed of the animation
to change speed with a Slider, Dial, MotionController, Accelerator, etc.
use target.animate({props:{rotation:360}, dynamic:true, set:{percentSpeed:0}}); to start off with no animation
use {dynamic:true, clean:false} to keep using using dynamic after animation has completed
drag - (default false) used with path in props to drag along path
This can be done while animating or while the animation is paused
Setting drag to true will set startPaused to true as well - set startPaused to false to animate and drag
With rewind set, drag lets you change the direction of an animation while animating
To turn drag off use the pause() method that animate() adds to the target
clamp - (default true) used with dynamic and non-looping - set to false to let time pass beyond animation start and end
startPaused - (default false - true if drag is true) Boolean - set to true to start the animation in the paused state
Good for animating manually with the percentComplete property
clean - (default true) set to false to not delete animation ids etc. at end of animate()
Could then use percentComplete to position tween and pauseTween(false) to start animating again
Note... once tween has waited, percentComplete does not include wait period
So clean cannot be used to restart an animation with a wait after the animation has waited
Use the replayTween() method of the target to restart the latest animation on a target
NOTE: clean will be set to true if loop is true (even if loopCount is set)
So to scrub after a loopCount of 2 then remake the animate() in the call callback with a pauseAnimate()
Use {dynamic:true, clean:false} to keep using using dynamic after animation has completed
obj - (depreciated) the old version of props - kept for backwards compatibility
seriesWait - (internal) used internally to hold setting relative values in correct series order
sequenceWait - (internal) used internally to tie sequence in to the animation chain for pauseAnimate and stopAnimate
rate - |ZIM VEE| (default 1) change the speed at which the animation runs
set to .5 to run at half the speed and 2 to run at twice the speed
a ZIM VEE here will update each loop if loopPick is set to true
to change the speed (time) of the animation for each loop
pauseOnBlur - (default true) as of ZIM 10.8.0, animate defaults to pause all animations on blur
blur is when the window is reduced or a different tab gains focus on the Browser
animate uses requestAninationFrame which slows down when the window is not in focus
this can cause animations to go out of sync - pauseOnBlur will prevent this
Can also set zim.pauseAnimateOnBlur=false or true to change this at any time
easeAmount - |ZIM VEE| (default null) set to change the tween effect
Ease amounts are as follows:
quad (default 2) - exponent - this is the default ZIM tween
cubic (default 3) - exponent
quart (default 4) - exponent
quint (default 5) - exponent
back (default 1.7) - strength
elastic (default 1) - amplitude - also see easeFrequency
linear/none, bounce, circ, sin - no affect
Note: used mostly with back and elastic (backIn, backOut, backInOut, etc.)
as setting the tween to quadInOut and then easeAmount to 5
would be the same as a quintInOut.
easeFrequency - |ZIM VEE| (default .3 elasticIn and elasticOut or .3*1.5 elasticInOut)
set to change the elastic ease frequency
so tween:"elasticOut", easeFrequency:.2 is a faster elastic
the time may also need to be increased or decreased as desired
also see easeAmount where easeAmount:3 would be a larger elastic
timeUnit - (default TIME) override the TIME setting to "seconds" / "s" or "milliseconds" / "ms"
timeCheck - (default true) set to false to not have animate() warn of potentially wrong time units - see also TIMECHECK
noAnimateCall - (default true) set to false to not call the callback function if ANIMATE is set to false
pathDamp - (default .15) damping for drag along path
rewindPick - (default false) set to true to pick from props as it rewinds
this will be moved to the other rewind parameters in ZIM 019
also see loopPick - using both loopPick and rewindPick will act like a series
where if the property has a series it will animate one after the other
do not use if the property is just a regular value as it will appear to stop the animation.
Can use a series, results of a function, min max or array for random picks
style - (default true) set to false to ignore styles set with the STYLE - will receive original parameter defaults
group - (default null) set to String (or comma delimited String) so STYLE can set default styles to the group(s) (like a CSS class)
PROPERTIES - zim.animate() adds the following properties to any object it animates:
animating - read-only - true when animating (including when waiting)
see paused (the opposite) and waiting properties
paused - read-only - when animating, paused is set to false
When paused with pauseAnimate() then paused is set to true
When stopped or before animation, paused is undefined or null
There is only one paused property per object so pausing a specific id
on an object with multiple animations will set paused to true
even if other animations are still running.
Pausing multiple objects should work fine.
See the tweenState property to test which ids are animating or paused
For a sequence animate() give the animate() an id and pauseAnimate() or stopAnimate() that id.
waiting - read-only - true when animation is waiting in wait, rewindWait, loopWait
tweenState - an object with tween ids as properties along with an all property (unless no tweens anymore)
these properties are true if animating and false if paused
if all is true then all are animating except for the ids that hold false
if all is false then all are not animating except for the ids that hold true
this is used for pauseAnimateOnBlur to keep track of animations to set back to true when un-blurring
percentSpeed - get or set the percent of the animation speed
100% is regular time, 50% is half as fast, 200% is twice as fast -100% is reverse normal speed, etc.
use target.animate({props:{rotation:360}, dynamic:true, set:{percentSpeed:0}}); to start off with no animation
rate - changes the speed of the animation with 1 as a ratio
so 1 is the default speed (time), .5 would be half the speed, 2 twice the speed, etc.
does what percentSpeed does by changing the CreateJS timeScale property
this does not require dynamic to be set and is probably more efficient
rate might also be affected by sequenceRate
percentComplete - get or set percent complete (0-100) **
this allows you to scrub through an animation with a Slider, Dial, MotionController, etc.
should probably set startPaused parameter of animate() to true
Setting percentComplete to 100 may cause the animation to start at the beginning
but can set rewind:true and then set percentComplete to 50 - this will animate "backwards"
Can use animation event and a test of percentComplete to stop animation at a percentage
see
https://zimjs.com/explore/squigglepart.html
** NOTE: As of ZIM 015, percentComplete includes the wait time
and spans across all animations on the object including animation series.
A percentComplete has also been added to the CreateJS tweens for individual control.
The individual tweens can be found in the zimTweens object
or the latestTween will give access to the latest tween running.
So for setting percentComplete on an animation with a wait you can access the latestTween
in the waited call back function.
METHODS - see pauseAnimate() and stopAnimate() under the METHODS module
Also - zim.animate() adds a pause(state, time) method to the target IF dynamic is set to true (or drag is true)
This matches the pause() of Dynamo and Scroller and is used by Accelerator
state - (default true) true pauses and setting the state to false will unpause the dynamic animation
time - (default 0) time in milliseconds to slow the animation down if pausing or speed it up if unpausing
endTween(callType) - stops the animation and sets the target to the properties at the end of the tween - returns target for chaining
callType defaults to "all" which will run the call function and all the call functions in a series
setting callType to "none" will not run the call function and not run any call function in a series
setting callType to "main" will run the call function but not the call functions in a series
note: any remaining rewindCall and loopCall functions will not be called when using endTween()
note: endTween is complicated with ids, multiple animations, series, sequences, etc.
if there is a problem, try adding the target to a Container and controlling separate animations on container and target
resetTween() - sets the target back to the state at the start of the last animate() call - returns target for chaining
note: resetTween is complicated with ids, multiple animations, series, sequences, etc.
if there is a problem, try adding the target to a Container and controlling separate animations on container and target
replayTween() - resets and runs the last animate() on the target - calls the animate function with the same parameters as the last time - returns target for chaining
note: replayTween is complicated with ids, multiple animations, series, sequences, etc.
if there is a problem, try adding the target to a Container and controlling separate animations on container and target
if there is a series with more than one target then replayTween will only work on the main target
instead, store the series in an object literal: const mySeries = {animation object} and call obj.animate(mySeries) and then later call it again obj.animate({mySeries})
EVENTS - zim animate() will add an "animation" event to the target IF the events parameter is set to true (default is false)
alternatively, see the animateCall and animateParams parameters of animate()
or the "animation" event will be added to the Container for a sequence in a Container
or the "animation" event is added to the targets of an animation series
If dynamic is set to true, will dispatch a "pause" event when animate is paused - could be delayed but time passed in to pause()
RETURNS the target for chaining (or null if no target is provided and run on zim with series)
CODE ▤TOUR😊BITS 
VIDS 
