JSignage:Animation timing and values

Introduction

The animateColor, animateOpacity, animateMotion, animateZoom and svgAnimation functions take a common set of attributes as arguments that define the timing and values of the animated target.

For a normative definition of all the animation parameters presented below, see Specifying the simple animation function in the SMIL 2.1 specification and Animation section in the SVG Tiny 1.2 specification.

These attributes are divided into two main categories:

1. Attributes to control the timing of the animation.
2. Attributes to define animation values over time.

Attributes to control the timing of the animation

• begin

  Type: Number or String. Default: 0.

  Defines when the animation effect should begin (relative to the start time of the layer in which the animated element is inserted) or 'indefinite' (if the animation will be started using the .begin() function).

• dur

  Type: Number or String. Default: 0.

  Duration (in seconds) of the animation effect or 'indefinite'.

• fill

  Type: String. Default: 'remove'.

  Can be 'freeze' or 'remove'. The animation effect is either frozen (at the last value) or removed when the active duration of the animation is over.

• repeatCount

  Type: Number or String. Default: 1.

  Number of iterations of the animation function or 'indefinite'.

• repeatDur

  Type: Number or String. No default value.

  The total duration to repeat the animation function or 'indefinite'.

Attributes to define animation values over time

Note: See more details here: http://www.w3.org/TR/SVGMobile12/animate.html#ValueAttributes.

• accumulate

  Type: String. Default: 'none'.

  Either 'none' or 'sum'. Controls whether each animation iteration builds on the value of the previous iteration ('sum') or if the repeat iterations are not cumulative ('none').

• additive

  Type: String. Default: 'replace'.

  Either 'sum' or 'replace'. Controls whether the specified values override the target value ('replace') or are added to it ('sum').

• by

  Type: Number or String. Default: none.

  Specifies a relative offset value for the animation. Ignored if a values attribute is provided.

• calcMode

  Type: String. Default: 'linear' except for .animateMotion() where it is 'paced'.

  Specifies the interpolation mode for the animation. Can be 'discrete, 'linear', 'paced' or 'spline'.

• from

  Type: Number or String. Default: none.

  Specifies the starting value of the animation. Ignored if a values attribute is provided.

• keySplines

  Type: Array.<String> or String. Default: none.

  List of Bézier control points associated with the 'keyTimes' list, defining a cubic Bézier function that controls interval pacing. Use array notation for animate*** functions and string notation for svgAnimation(). Each control point has the form 'x1 y1 x2 y2' and there must be one fewer set of control points than there are keyTimes. This attribute is used only when the calcMode is set to 'spline'.

• keyTimes

  Type: Array.<Number> or String. Default: none.

  List of time values used to control the pacing of the animation. Use array notation for animate*** functions and string notation for svgAnimation().

  Each time value in the list corresponds to a value in the values attribute list, is specified as a floating point value between 0 and 1 (inclusive), representing a proportional offset into the simple duration of the animation element, and defines when the value is used in the animation function.

  If keyTimes is not specified, all the values defined in the values attribute list have the same duration.

• to

  Type: Number or String. Default: none.

  Specifies the ending value of the animation. Ignored if a values attribute is provided.

• values

  Type: Array or String. Default: none.

  Array of successive values for the animated target for animate*** functions. The type of acceptable values is dependent on the animation function: colors for .animateColor(), opacity values for .animateOpacity(), pairs of x, y coordinates for .animateMotion() and zoom factors for .animateZoom().

  A string containing a semicolon-separated list of values for svgAnimation function, where each individual value is expressed as described here.

Rules

The animation values shall be specified in one of these three ways (exclusively):

• with the values array,
• with from and to,

  a "from-to" animation is equivalent to a values array with [ from, to ].

• or with by

  a "by" animation is equivalent to a values array with [ 0, by ] and additive set to 'sum'.

When multiple animation are programmed for the same target, they may overlap in time which creates a conflict (unless they are both additive). Conflicts are resolved according to the following rules:

1. The animation which started last has priority over animations which started earlier.
2. When two animations start at the same time, the one which was specified last has priority over animations specified before in the script.