A tween - inbetween animation - is a small, targeted, time-limited animation where we define the start and end points (key frames) of the animation, and a method for calculating the intermediate values between the two (interpolation, using an easing function).
Scrawl-canvas includes a full range of functionality to implement tweening. Any Scrawl-canvas object that includes a set function, which accepts a {key:value} object as its single argument, can be tweened.
makeTween factory function.targets Array - one Tween may animate many objects.definitions Array which sets out the details of the animation to be performed.definitions Array can include multiple objects, each defining a change to a specific attribute that needs to be applied to the target objects.12.5%) and measurement Strings (20px).packet functionality: they can be saved, and cloned.Scrawl-canvas separates the timing aspects of its Tweens from their definitions.
We don’t recommend using other tween factories - such as Greensock - with Scrawl-canvas objects at this time.
set, setDelta and related functions, which take a single Javascript object as their argument.dirty flags get set (among other work), so the object can update itself appropriately at the most convenient time for itself.dirty flags - thus the object will not know that it needs to do work.TODO: basic packet and kill functionality tested in Demo DOM-004, but there’s a lot of Ticker/Tween/Action functionality that needs to be explored and tested further (see Ticker TODO section for issues and suggested work).
import { constructors, animationtickers, radian } from '../core/library.js';
import { mergeOver, pushUnique, xt, xtGet, xto, convertTime, λnull, easeEngines, Ωempty } from '../core/utilities.js';
import { makeTicker } from './ticker.js';
import baseMix from '../mixin/base.js';
import tweenMix from '../mixin/tween.js';const Tween = function (items = Ωempty) {
let tn;
this.makeName(items.name);
this.register();
this.set(this.defs);
this.set(items);
this.setDefinitionsValues();status magic numbers: -1 = “before”; 0 = “running”; 1 = “after”.
this.status = -1;
this.calculateEffectiveTime();
this.calculateEffectiveDuration();All Tweens require a Ticker to act as their timeline.
if (animationtickers[items.ticker]) this.addToTicker(items.ticker);
else {
tn = `${this.name}_ticker`;
makeTicker({
name: tn,
order: this.order,
subscribers: this.name,
duration: this.effectiveDuration,
eventChoke: xtGet(items.eventChoke, 0),
cycles: xtGet(items.cycles, 1),
killOnComplete: xtGet(items.killOnComplete, false)
});
this.ticker = tn;
animationtickers[tn].recalculateEffectiveDuration();
}
return this;
};let P = Tween.prototype = Object.create(Object.prototype);
P.type = 'Tween';
P.lib = 'tween';
P.isArtefact = false;
P.isAsset = false;P = baseMix(P);
P = tweenMix(P);let defaultAttributes = {definitions - Array of objects defining the animations to be performed by the Tween. Object attributes include:
Scrawl-canvas includes functionality to allow start and end values to be defined as Strings, with a measurement suffix (%, px, etc) attached to the number.
set function.set function that takes an object as its argument can be tweened. definitions: null,duration - can accept a variety of values:
'500ms', '0.5s'.20% - a relative value measured against the Ticker’s effective duration. For example, if the Ticker has an effective duration of 5000 (5 seconds), and the Tween wants to run for 20% of that time, the Tween’s effective duration will be 1000 (1 second). duration: 0,killOnComplete - Boolean flag; if set, the Tween will kill itself when it completes
killOnComplete: false,The Tween object supports some tween animation hook functions:
run function is invokedrun function is invokedhalt function is invokedresume function is invokedreverse function is invokedseekTo function is invokedseekFor function is invoked commenceAction: null,
onRun: null,
onHalt: null,
onResume: null,
onReverse: null,
onSeekTo: null,
onSeekFor: null,
completeAction: null,ticker - String name of Ticker object which this Tween will associate itself with.
name attribute) to associate with. defs object.The following Ticker-related attributes are not stored in the Tween object:
};
P.defs = mergeOver(P.defs, defaultAttributes);P.packetExclusions = pushUnique(P.packetExclusions, ['definitions', 'targets']);
P.packetFunctions = pushUnique(P.packetFunctions, ['commenceAction', 'completeAction', 'onRun', 'onHalt', 'onResume', 'onReverse', 'onSeekTo', 'onSeekFor', 'action']);
P.finalizePacketOut = function (copy, items) {
if (Array.isArray(this.targets)) copy.targets = this.targets.map(t => t.name);
if (Array.isArray(this.definitions)) {
copy.definitions = this.definitions.map(d => {
let res = {};
res.attribute = d.attribute;
res.start = d.start;
res.end = d.end;
if (d.engine && d.engine.substring) res.engine = d.engine.substring;
else {
if (xt(d.engine) && d.engine !== null) {
let e = this.stringifyFunction(d.engine);
if (e) {
res.engine = e;
res.engineIsFunction = true;
}
}
}
return res;
});
}
return copy;
};When cloning a ticker, we can use an additional attribute in the clone function’s argument object:
P.postCloneAction = function(clone, items) {
if (items.useNewTicker) {
let ticker = animationtickers[this.ticker];
if (xt(items.cycles)) clone.cycles = items.cycles;
else if (ticker) clone.cycles = ticker.cycles;
else clone.cycles = 1;
let cloneTicker = animationtickers[clone.ticker];
cloneTicker.cycles = clone.cycles;
if (xt(items.duration)) {
clone.duration = items.duration;
clone.calculateEffectiveDuration();
if (cloneTicker) cloneTicker.recalculateEffectiveDuration();
}
}
if (Array.isArray(clone.definitions)) {
clone.definitions.forEach((def, index) => {
if (def.engineIsFunction) def.engine = this.definitions[index].engine;
});
}
return clone;
};No additional kill functionality required
killOnComplete flag has been set to true.let G = P.getters,
S = P.setters;definitions
G.definitions = function() {
return [].concat(this.definitions);
};
S.definitions = function (item) {
this.definitions = [].concat(item);
this.setDefinitionsValues();
};commenceAction
S.commenceAction = function (item) {
this.commenceAction = item;
if (typeof this.commenceAction !== 'function') this.commenceAction = λnull;
};completeAction
S.completeAction = function (item) {
this.completeAction = item;
if (typeof this.completeAction !== 'function') this.completeAction = λnull;
};set - we perform some additional functionality in the Tween set function
P.set = function (items = Ωempty) {
let key, i, iz, s,
setters = this.setters,
keys = Object.keys(items),
d = this.defs,
ticker = (xt(items.ticker)) ? this.ticker : false;
for (i = 0, iz = keys.length; i < iz; i++) {
key = keys[i];
if (key !== 'name') {
s = setters[key];
if (s) s.call(this, items[key]);
else if (typeof d[key] !== 'undefined') this[key] = items[key];
}
}
if (ticker) {
this.ticker = ticker;
this.addToTicker(items.ticker);
}
else if (xto(items.time, items.duration)) {
this.calculateEffectiveTime();
this.calculateEffectiveDuration();
}
return this;
};getEndTime - Ticker-related help function
P.getEndTime = function () {
return this.effectiveTime + this.effectiveDuration;
};calculateEffectiveDuration
P.calculateEffectiveDuration = function (item) {
let tweenDuration = xtGet(item, this.duration),
calculatedDur = convertTime(tweenDuration),
cDur = calculatedDur[1],
cType = calculatedDur[0],
ticker = this.ticker,
myticker,
tickerDuration = 0;
this.effectiveDuration = 0;
if (cType === '%') {
if (ticker) {
myticker = animationtickers[ticker];
if (myticker) {
tickerDuration = myticker.effectiveDuration;
this.effectiveDuration = tickerDuration * (cDur / 100);
}
}
}
else this.effectiveDuration = cDur;
return this;
};update - main animation function, invoked by the Ticker that this Tween subscribes to; runs once per RequestAnimationFrame while the Ticker is running.
items argument is a Ticker ResultObject - Ticker handles all the request and release functionality for this pool object. Treat the items object as read-only.status magic numbers: -1 = “before”; 0 = “running”; 1 = “after”.P.update = function (items = Ωempty) {
let starts, ends,
tick = items.tick || 0,
revTick = items.reverseTick || 0,
status = 0,
effectiveTime = this.effectiveTime,
effectiveDuration = this.effectiveDuration,
reversed = this.reversed;Should we do work for this Tween?
if (!reversed) {
starts = effectiveTime;
ends = effectiveTime + effectiveDuration;
if (tick < starts) status = -1;
else if (tick > ends) status = 1;
}
else {
starts = effectiveTime + effectiveDuration;
ends = effectiveTime;
if (revTick > starts) status = 1;
else if (revTick < ends) status = -1;
}For Tweens with a duration > 0
if (effectiveDuration) {
if (!status || status != this.status) {
this.status = status;
this.doSimpleUpdate(items);
if (!items.next) this.status = (reversed) ? -1 : 1;
}
}For Tweens with a duration == 0
else {
if (status != this.status) {
this.status = status;
this.doSimpleUpdate(items);
if (!items.next) this.status = (reversed) ? -1 : 1;
}
}
if (items.willLoop) {
if (this.reverseOnCycleEnd) this.reversed = !reversed;
else this.status = -1;
}
};doSimpleUpdate - internal function called by update function.
P.doSimpleUpdate = function (items = Ωempty) {We create handles to a bunch of attributes so that we only need to look them up once each time the function runs
let starts = this.effectiveTime,
effectiveTick,
actions = this.engineActions,
effectiveDuration = this.effectiveDuration,
status = this.status,
definitions = this.definitions,
targets = this.targets,
action = this.action,
i, iz, j, jz, progress,We store the setObj object as an attribute on the Tween object for convenience, and to cut down on the number of objects created during the lifetime of the Tween.
setObj = this.setObj || {};
let def, engine, val, effectiveStart, effectiveChange, int, suffix, attribute;
let round = Math.round;
effectiveTick = (this.reversed) ? items.reverseTick - starts : items.tick - starts;
if (effectiveDuration && !status) progress = effectiveTick / effectiveDuration;
else progress = (status > 0) ? 1 : 0;
for (i = 0, iz = definitions.length; i < iz; i++) {
def = definitions[i];
engine = def.engine;
effectiveStart = def.effectiveStart;
effectiveChange = def.effectiveChange;
int = def.integer;
suffix = def.suffix;
attribute = def.attribute;Invoke the appropriate easing function for this particular definition object
if (engine.substring) val = actions(engine, effectiveStart, effectiveChange, progress);
else val = engine(effectiveStart, effectiveChange, progress);
if (int) val = round(val);
if (suffix) val += suffix;
setObj[attribute] = val;
}
for (j = 0, jz = targets.length; j < jz; j++) {
targets[j].set(setObj);
}
this.setObj = setObj;We call the action attribute function (if it is defined) at the completion of every update.
if (action) action();
};engineActions - internal function to run built-in easing engines
core/utilities file effectiveStart value, in milliseconds.effectiveEnd - effectiveStart).Scrawl-canvas easing engines use the following metaphor to define their names:
out indicates an acceleration. Think of a train leaving the station.in indicates a deceleration. Think of a train arriving the station.P.engineActions = function(engine, start, change, position) {
const e = (null != easeEngines[engine]) ? engine : 'linear';
return start + (change * easeEngines[e](position));
};setDefinitionsValues - convert start and end values into float Numbers.
start and end values to be defined as Strings, with a measurement suffix (%, px, etc) attached to the numberP.setDefinitionsValues = function () {
let i, iz, temp, def,
parseDefinitionsValue = this.parseDefinitionsValue,
definitions = this.definitions;
for (i = 0, iz = definitions.length; i < iz; i++) {
def = definitions[i];
if (def) {
temp = parseDefinitionsValue(def.start);
def.effectiveStart = temp[1];
def.suffix = temp[0];
temp = parseDefinitionsValue(def.end);
def.effectiveEnd = temp[1];The default easing function is linear
if (!xt(def.engine)) def.engine = 'linear';
def.effectiveChange = def.effectiveEnd - def.effectiveStart;
}
}
return this;
};parseDefinitionsValue - internal function invoked by setDefinitionsValues function.
P.parseDefinitionsValue = function (item) {
let result = ['', 0],
a;
if (xt(item)) {
if (item.toFixed) result[1] = item;
else if (item.substring) {
a = item.match(/^-?\d+\.?\d*(\D*)/);
if (xt(a[0])) result[1] = parseFloat(a);
if (xt(a[1])) result[0] = a[1];
}
}
return result;
};P.run = function () {
let t = animationtickers[this.ticker];
if (t) {
this.commenceAction();
t.run();
if (typeof this.onRun === 'function') this.onRun();
}
return this;
};isRunning - check to see if Tween is in a running state.
P.isRunning = function () {
let tick = animationtickers[this.ticker];
if (tick) return tick.isRunning();
return false;
};P.halt = function() {
let t = animationtickers[this.ticker];
if (t) {
t.halt();
if (typeof this.onHalt === 'function') this.onHalt();
}
return this;
};P.reverse = function() {
let t = animationtickers[this.ticker];
if (t) {
t.reverse();
if (typeof this.onReverse === 'function') this.onReverse();
}
return this;
};P.resume = function() {
let t = animationtickers[this.ticker];
if (t) {
t.resume();
if (typeof this.onResume === 'function') this.onResume();
}
return this;
};seekTo
onSeekTo function.P.seekTo = function(milliseconds) {
let t = animationtickers[this.ticker];
if (t) {
t.seekTo(milliseconds);
if (typeof this.onSeekTo === 'function') this.onSeekTo();
}
return this;
};seekFor
onSeekFor function.P.seekFor = function(milliseconds) {
let t = animationtickers[this.ticker];
if (t) {
t.seekFor(milliseconds);
if (typeof this.onSeekFor === 'function') this.onSeekFor();
}
return this;
};scrawl.makeTween({
name: 'my-tween',
duration: 2500,
targets: scrawl.artefact['my-phrase'],
definitions: [
{
attribute: 'textPathPosition',
start: 1,
end: 0,
engine: 'easeIn'
},
{
attribute: 'globalAlpha',
start: 0,
end: 1,
engine: 'easeIn'
},
{
attribute: 'scale',
start: 0.4,
end: 1,
engine: 'easeIn'
},
]
});
const makeTween = function (items) {
if (!items) return false;
return new Tween(items);
};
constructors.Tween = Tween;export {
makeTween,
};