Concert.js Reference: Class: Sequence

new Sequence(transformationSetopt) → {Object}

Represents an animation sequence, or, more broadly, a series of changes which are applied to a collection of objects over time. A sequence contains a set of transformations that are applied to DOM Elements, JavaScript objects, or anything else that can be manipulated with JavasScript. It contains methods that allow defining those transformations, seeking to any point in the sequence timeline, and running the sequence in various ways.

Parameters:

Name	Type	Attributes	Description
`transformationSet`	Object	<optional>	An object defining an initial set of transformations to add to the sequence. The layout of this object is the same as used in the addTransformations method.

Source:

Concert.js, line 1255

Returns:

A new Sequence object.

Type: Object

Methods

addTransformations(transformationSet)

Adds a set of transformations (i.e., changes applied to objects over time) to the sequence.

Terminology:

-A transformation is a single change applied over time to a single feature of a single object. Its properties include which object to modify and what feature of it will be altered, a start time and starting value, and end time and ending value. For instance, a transformation may represent changing the "width" style of a DIV element from "100px" at time 1000 to "200px" at time 2000.

-A sequence is a collection of transformations that are to be applied together as a group.

-A target object is anything that will be modified by a transformation (e.g., a DOM element or a JavaScript object).

-A target feature is the aspect of the target object that will be modified (e.g., for a DOM element this might be "width").

-A unit is an optional (initially defaults to null) string appended to a calculated value when applying it to a target feature (e.g., for a DOM style property this might be "px").

-A calculator is a function that looks at the start and end values of a target feature and calculates a current value to apply based on the current distance along the timeline. Ordinarily this is set to one of the pre-defined calculator functions in the Concert.Calculators namespace (initially defaulting to Concert.Calculators.Linear), but can also be a custom function, as explained further below.

-An applicator is a function that takes the values computed by the calculator function and applies them to the target feature. For instance, different applicators would be used for setting JavaScript object properties, DOM element styles, or SVG element attributes. Ordinarily this is set to one of the pre-defined applicator functions in the Concert.Applicators namespace (initially defaulting to Concert.Applicators.Property), but can also be a custom function, as explained further below.

-An easing is a function which modifies the rate at which a transformation moves from beginning to end. For instance, it may progress steadily from the start time to the end time, or it may accelerate and decelerate to make motion appear smoother. Ordinarily this is set to one of the pre-defined easing functions in the Concert.EasingFunctions namespace (initially defaulting to Concert.EasingFunctions.ConstantRate) but can also be a custom function, as explained further below.

Note: The easing function could easily be confused with the calculator function, because many animation libraries combine these two concepts. Here, however, they can be set independently. Essentially, a calculator function, given a start value, an end value, and the current time (in the form of a fractional distance between the start time and end time of the transformation), calculates a current value to apply. The easing function is what computes the current time that will be passed into the calculator function, allowing the rate at which a transformation proceeds to change over time. The reason for separating these becomes apparent when we consider that different types of calculation are necessary for different types of features. A function calculating an animated transition from one RGB color value to another uses a different algorithm than one calculating the animation of a simple, numeric value, for instance, or a complex calculator function that takes multiple inputs and calculates rotational movement. Because Concert.js allows anything at all to be animated, it supports the ability to choose any method of calculating values, and then (regardless of which one is used) specifying any easing function to alter the rate at which the animation takes place. Easing functions are specified at the level of the transformation (not the full sequence, although it is possible to set a default easing function for a sequence), so a single sequence can contain different transformations using a different easing functions.

Parameters:

Name Type Description

Name	Type	Description
`transformationSet`	Object	An object or array describing a set of changes which will be applied at specified times to specified target objects. (A target object being anything that will be modified by the sequence, such as a DOM element or a JavaScript object.) The `transformationSet` parameter is either a single object whose properties define a set of transformations, or an array of such objects. Certain of the properties (as indicated below) are optional, and each sequence maintains its own settings for what default values will be applied to transformations when the optional properties are not defined. (Note: these defaults are applied at the time the transformations are added, not at run-time, so changing the defaults for a sequence will never alter transformations which have already been added to that sequence.) Important note: Adding two animation segments that overlap in time, and both try to modify the same feature of the same target object, produces undefined behavior. The expected layout of the object passed into this method is defined as follows (also see examples below): transformationSet = TransformationsObject OR transformationSet = [ TransformationsObject₁, TransformationsObject₂, ...] *TransformationsObject* = { target: TargetObjectDefinition, AND/OR targets: [ TargetObjectDefinition₁, TargetObjectDefinition₂, ...], feature: FeatureDefinition, // If absent, uses sequence's default value [unit: UnitDefinition,] // If absent, uses sequence's default value [applicator: ApplicatorFunction,] // If absent, uses sequence's default value [calculator: CalculatorFunction,] [calculatorModifiers: CalculatorModifiersObject,] // If absent, uses sequence's default value [easing: EasingFunction,] [userProperties: UserPropertiesObject,] keyframes: KeyframesDefinition OR segments: SegmentDefinition OR [ SegmentDefinition₁, SegmentDefinition₂, ...] }; `TargetObjectDefinition = The object to be modified by these transformations.` Often this will be a DOM object, but it can be anything at all. Multiple targets can be specified, by using the `targets` (plural) property, as a shorthand method of duplicating the transformation definitions to target all the included target objects. `FeatureDefinition = The feature of the target object which will be modified, OR an array of such features.` In most cases, this will be a string (for example, when animating a DOM style, this might be "width") or an array of strings. Arrays are allowed as a shorthand method of defining multiple features, values, and units together in a more compact notation. The first feature in the array will be matched with the first unit and the first value in those arrays, and so on. See below samples for an example of using arrays in this way. `UnitDefinition = A string to be appended to calculated values before they are applied to the target (for example, when animating a DOM style, this might be "px"), OR an array of such strings.` Arrays are allowed as a shorthand method of defining multiple features, values, and units together in a more compact notation. The first unit in the array will be matched with the first feature and the first value in those arrays, and so on. See below samples for an example of using arrays in this way. Use null if nothing should be appended to the calculated values for this transformation. `ApplicatorFunction = Function used to apply the calculated current value to the feature.` Because different types of features (e.g., DOM element styles as contrasted to plain JavaScript object properties) are applied in different ways, different applicator functions are needed. This can be set to one of the functions defined in the Concert.Applicators namespace, or to any function with the signature: function applicatorFunction(target, feature, value, unit) See below examples for a sample of a custom applicator. `CalculatorFunction = Function used to calculate a current value to apply to the target feature.` This can be set to one of the functions defined in the Concert.Calculators namespace, or to any function returning an approprate value for this transformation's target feature and having the signature: `function calculatorFunction(distanceFraction, startValue, endValue, addlProperties)` See below examples for a sample of a custom calculator. `CalculatorModifiersObject = Object used to apply additional factors used to modify calculations during the animation of these transformations.` Several such factors can be specified. For non-rotational transformations, takes the form: { [multiply: multiplicationFactorValue,] [modulo: moduloFactorValue,] [roundFactor: roundFactorValue,] [offset: offsetValue,] } These options are modifiers to the animation calculation engine, applied in the following ways and in the following order: `multiplicationFactorValue`: While animating the target object, the value to be applied to the target feature is multiplied by this number. `moduloFactorValue`: While animating the target object, the value to be applied to the target feature is divided by this number, and the remainder is actually what is applied. `roundFactorValue`: While animating the target property, the value to be applied is rounded to the nearest multiple of this number. `offsetValue`: While animating the target property, this value is added to the value to be applied to the target feature. When the `Rotational` calculator (see Concert.Calculators) is being used (i.e., when this transformation is animating rotational motion), the object should be of the form: { [centerX: CalculatorModifiersObject,] [centerY: CalculatorModifiersObject,] [radius:CalculatorModifiersObject,] [angle: CalculatorModifiersObject,] [offsetX: CalculatorModifiersObject,] [offsetY: CalculatorModifiersObject] } Each individual `CalculatorModifiersObject` specified is an object of the form described above (an object with some or all of these properties: multiply, modulo, roundFactor, offset). This allows a separate set of modifiers to be applied to each of the values that can be animated in a rotational transformation. For instance, the angle could be rounded to the nearest multiple of a number. A very common use case would be specifying an offset so that the center of an element is what is rotated around the specified center point rather than its upper left corner. `EasingFunction = Function used to compute the current time (as a fractional proportion of the distance traversed, from 0 to 1, between the start time and end time of the transformation).` This can be set to one of the functions defined in the Concert.EasingFunctions namespace, or to any function returning a value from 0 to 1 and having the signature: `function easingFunction(startTime, endTime, currentTime)` See below examples for a sample of a custom easing function. `UserPropertiesObject = Object used to apply additional, optional, user properties to each of transformations being added.` The primary use case of this object is when employing user-defined, custom calculator functions. If the Transformation uses a custom calculator, this UserPropertiesObject is passed into the calculator function as an argument. This allows setting user-defined properties on the Transformation object that can be used by a user-defined calculator function. *KeyframesDefinition* = { times: KeyframeTimesArray, [values: KeyframeValuesArray] OR [valueGenerators: ValueGeneratorsArray] }; *SegmentDefinition* = { // Start time of this transformation t0: TimeDefinition, // End time: must be >= t0. t1: TimeDefinition, // Value applied at the start time v0: ValueDefinition, // Value applied at the end time v1: ValueDefinition, // OR // // Function to calculate v0 v0Generator: ValueGenerator, // Function to calculate v1 v1Generator: ValueGenerator, // If absent, falls back to the calculator // defined at the TransformationsObject // level; if also absent there, to the // sequence's default calculator. [calculator: CalculatorFunction,] // If absent, falls back to the // calculatorModifiers object defined // at the TransformationsObject level; // if also absent there, to the sequence's // default calculatorModifiers object. [calculatorModifers: CalculatorModifiersObject,] // If absent, falls back to easing function // defined at the TransformationsObject // level; if also absent there, to the // sequence's default easing. [easing: EasingFunction,] // If absent, falls back to the unit defined // at the TransformationsObject level; // if also absent there, to the sequence's // default unit. [unit: UnitDefinition,] // If absent, falls back to userProperties // object defined at the // TransformationsObject level; // if also absent there, to the sequence's // default userProperties object. [userProperties: userPropertiesObject] }; `KeyframeTimesArray = An array of the form [ TimeDefinition₁, TimeDefinition₂, ...]` This defines the timeline points used as keyframes for this transformation series, to be matched up with the values in the corresponding `KeyframeValuesArray`. A null element has the effect of breaking the keyframe string into two segments. For example, the array `[0, 100, 1000, 2000]` defines a constant flow of transition with four keyframes. The array `[0, 100, null, 1000, 2000]`, on the other hand, defines a flow that is broken in two pieces: one animated segment with keyframes at time 0 and 100, then no further animation at all until until time 1000, followed by another period of animation between the keyframes at times 1000 and 2000. Important: Keyframe times for each null-separated segment (or for the whole array, if there are no null breaks) must be passed to the function in ascending order. (That is, an array of times such as [1000, 2000, 0, 500] will not work properly. But it is perfectly okay to use an array of times such as [1000, 2000, null, 0, 500], because that actually produces two entirely separate animation segments, and each of them is specified ascending time order.) `KeyframeValuesArray = An array of the form [ValueDefinition₁, ValueDefinition₂, ...].` This defines the values applied at each keyframe point, as matched up with the keyframe points defined in the corresponding KeyframeTimesArray. Note that null values appearing in this array work exactly the same way (and should match up with) null values in the KeyframeTimesArray. Both arrays must have the same number of elements. `ValueGeneratorsArray = An array of the form [ValueGenerator₁, ValueGenerator₂, ...].` This defines the functions that calculate values applied at each keyframe point, as matched up with the keyframe points defined in the corresponding KeyframeTimesArray. `TimeDefinition = A number indicating a point along the sequence timeline.` When synchronizing to a media object or running by the system clock, this should ordinarily be specified as a number of milliseconds (1/1000's of a second). Otherwise, there is no restriction; it simply indicates a numeric point on the overall timeline, with no particular unit implied. For instance, a sequence could be synchronized to the value of a slider or other user control, in which case this number would just be anything from the minimum to the maximum values of that control. `ValueDefinition = A value to be applied to the target object feature, or an array of such values.` This value can be of any type, although it needs to be one appropriate to the target feature, calculator, and applicator being used. If a unit is specified, the value will be treated as a string and the unit will be appended to it before application. Arrays are allowed as a shorthand method of defining multiple features, values, and units together in a more compact notation. The first value in the array will be matched with the first unit and the first feature in those arrays, and so on. See below samples for an example of using arrays in this way. `ValueGenerator = A function which returns a valid ValueDefinition and has the signature: function generatorFunction(sequence)` This is a mechanism that allows specifying functions that will calculate start and end values for a transformation, instead of using fixed values determined at the time the transformation is initially specified. This can be helpful if the same transformation will be run more than once with different start and end values, such as a motion that might be repeated in more than one place on the screen at different times, or if the transformation is being added to the sequence before the actual start and end values are yet known. This is not to be confused with a Calculator function. A Calculator takes a start and end value along with the current time and calculates the current value. This function, by contrast, is called prior to running the sequence and determines what the start and end values are that the Calculator will look at during run-time of the sequence. All of the value generator functions for an entire sequence are called at once, either manually by calling the sequence's generateValues method, or at the time the sequence is run, by specifying `true` for the `generateValues` option when calling the run, begin, follow, or syncTo methods. The generator function will be passed a reference to the sequence object containing the transformation whose values are currently being generated.

transformationSet

Object

An object or array describing a set of changes which will be applied at specified times to specified target objects. (A target object being anything that will be modified by the sequence, such as a DOM element or a JavaScript object.) The transformationSet parameter is either a single object whose properties define a set of transformations, or an array of such objects. Certain of the properties (as indicated below) are optional, and each sequence maintains its own settings for what default values will be applied to transformations when the optional properties are not defined. (Note: these defaults are applied at the time the transformations are added, not at run-time, so changing the defaults for a sequence will never alter transformations which have already been added to that sequence.)

Important note: Adding two animation segments that overlap in time, and both try to modify the same feature of the same target object, produces undefined behavior.

The expected layout of the object passed into this method is defined as follows (also see examples below):

transformationSet = TransformationsObject
OR
transformationSet =
  [
    TransformationsObject₁,
    TransformationsObject₂,
  ...]

TransformationsObject =
{
  target: TargetObjectDefinition,
  AND/OR
  targets:
  [
    TargetObjectDefinition₁,
    TargetObjectDefinition₂,
  ...],

  feature: FeatureDefinition,

  // If absent, uses sequence's default value
  [unit: UnitDefinition,]

  // If absent, uses sequence's default value
  [applicator: ApplicatorFunction,]

  // If absent, uses sequence's default value
  [calculator: CalculatorFunction,]

  [calculatorModifiers:
    CalculatorModifiersObject,]

  // If absent, uses sequence's default value
  [easing: EasingFunction,]

  [userProperties: UserPropertiesObject,]

    keyframes: KeyframesDefinition
    OR
    segments:
      SegmentDefinition
      OR
      [
        SegmentDefinition₁,
        SegmentDefinition₂,
      ...]
  };

TargetObjectDefinition = The object to be modified by these transformations. Often this will be a DOM object, but it can be anything at all. Multiple targets can be specified, by using the targets (plural) property, as a shorthand method of duplicating the transformation definitions to target all the included target objects.

FeatureDefinition = The feature of the target object which will be modified, OR an array of such features. In most cases, this will be a string (for example, when animating a DOM style, this might be "width") or an array of strings. Arrays are allowed as a shorthand method of defining multiple features, values, and units together in a more compact notation. The first feature in the array will be matched with the first unit and the first value in those arrays, and so on. See below samples for an example of using arrays in this way.

UnitDefinition = A string to be appended to calculated values before they are applied to the target (for example, when animating a DOM style, this might be "px"), OR an array of such strings. Arrays are allowed as a shorthand method of defining multiple features, values, and units together in a more compact notation. The first unit in the array will be matched with the first feature and the first value in those arrays, and so on. See below samples for an example of using arrays in this way. Use null if nothing should be appended to the calculated values for this transformation.

ApplicatorFunction = Function used to apply the calculated current value to the feature. Because different types of features (e.g., DOM element styles as contrasted to plain JavaScript object properties) are applied in different ways, different applicator functions are needed. This can be set to one of the functions defined in the Concert.Applicators namespace, or to any function with the signature: function applicatorFunction(target, feature, value, unit) See below examples for a sample of a custom applicator.

CalculatorFunction = Function used to calculate a current value to apply to the target feature. This can be set to one of the functions defined in the Concert.Calculators namespace, or to any function returning an approprate value for this transformation's target feature and having the signature: function calculatorFunction(distanceFraction, startValue, endValue, addlProperties) See below examples for a sample of a custom calculator.

CalculatorModifiersObject = Object used to apply additional factors used to modify calculations during the animation of these transformations. Several such factors can be specified. For non-rotational transformations, takes the form:

    {
        [multiply: multiplicationFactorValue,]
        [modulo: moduloFactorValue,]
        [roundFactor: roundFactorValue,]
        [offset: offsetValue,]
    }

These options are modifiers to the animation calculation engine, applied in the following ways and in the following order:

multiplicationFactorValue: While animating the target object, the value to be applied to the target feature is multiplied by this number.
moduloFactorValue: While animating the target object, the value to be applied to the target feature is divided by this number, and the remainder is actually what is applied.
roundFactorValue: While animating the target property, the value to be applied is rounded to the nearest multiple of this number.
offsetValue: While animating the target property, this value is added to the value to be applied to the target feature.

When the Rotational calculator (see Concert.Calculators) is being used (i.e., when this transformation is animating rotational motion), the object should be of the form:

    {
        [centerX: CalculatorModifiersObject,]
        [centerY: CalculatorModifiersObject,]
        [radius:CalculatorModifiersObject,]
        [angle: CalculatorModifiersObject,]
        [offsetX: CalculatorModifiersObject,]
        [offsetY: CalculatorModifiersObject]
    }

Each individual CalculatorModifiersObject specified is an object of the form described above (an object with some or all of these properties: multiply, modulo, roundFactor, offset). This allows a separate set of modifiers to be applied to each of the values that can be animated in a rotational transformation. For instance, the angle could be rounded to the nearest multiple of a number. A very common use case would be specifying an offset so that the center of an element is what is rotated around the specified center point rather than its upper left corner.

EasingFunction = Function used to compute the current time (as a fractional proportion of the distance traversed, from 0 to 1, between the start time and end time of the transformation). This can be set to one of the functions defined in the Concert.EasingFunctions namespace, or to any function returning a value from 0 to 1 and having the signature: function easingFunction(startTime, endTime, currentTime) See below examples for a sample of a custom easing function.

UserPropertiesObject = Object used to apply additional, optional, user properties to each of transformations being added. The primary use case of this object is when employing user-defined, custom calculator functions. If the Transformation uses a custom calculator, this UserPropertiesObject is passed into the calculator function as an argument. This allows setting user-defined properties on the Transformation object that can be used by a user-defined calculator function.

KeyframesDefinition =
	 {
    times: KeyframeTimesArray,

    [values: KeyframeValuesArray]
    OR
    [valueGenerators: ValueGeneratorsArray]
  };

SegmentDefinition = 
{
  // Start time of this transformation
  t0: TimeDefinition,
  // End time: must be >= t0.
  t1: TimeDefinition,

  // Value applied at the start time
  v0: ValueDefinition,
  // Value applied at the end time
  v1: ValueDefinition,
  // OR //
  // Function to calculate v0
  v0Generator: ValueGenerator,
  // Function to calculate v1
  v1Generator: ValueGenerator,

  // If absent, falls back to the calculator
  // defined at the TransformationsObject
  // level; if also absent there, to the
  // sequence's default calculator.
  [calculator: CalculatorFunction,]

  // If absent, falls back to the
  // calculatorModifiers object defined
  // at the TransformationsObject level;
  // if also absent there, to the sequence's
  // default calculatorModifiers object.
  [calculatorModifers:
    CalculatorModifiersObject,]

  // If absent, falls back to easing function
  // defined at the TransformationsObject
  // level; if also absent there, to the
  // sequence's default easing.
  [easing: EasingFunction,]

  // If absent, falls back to the unit defined
  // at the TransformationsObject level;
  // if also absent there, to the sequence's
  // default unit.
  [unit: UnitDefinition,]

  // If absent, falls back to userProperties
  // object defined at the 
  // TransformationsObject level;
  // if also absent there, to the sequence's
  // default userProperties object.
  [userProperties:
    userPropertiesObject]
};

KeyframeTimesArray = An array of the form [ TimeDefinition₁, TimeDefinition₂, ...] This defines the timeline points used as keyframes for this transformation series, to be matched up with the values in the corresponding KeyframeValuesArray. A null element has the effect of breaking the keyframe string into two segments. For example, the array [0, 100, 1000, 2000] defines a constant flow of transition with four keyframes. The array [0, 100, null, 1000, 2000], on the other hand, defines a flow that is broken in two pieces: one animated segment with keyframes at time 0 and 100, then no further animation at all until until time 1000, followed by another period of animation between the keyframes at times 1000 and 2000. Important: Keyframe times for each null-separated segment (or for the whole array, if there are no null breaks) must be passed to the function in ascending order. (That is, an array of times such as [1000, 2000, 0, 500] will not work properly. But it is perfectly okay to use an array of times such as [1000, 2000, null, 0, 500], because that actually produces two entirely separate animation segments, and each of them is specified ascending time order.)

KeyframeValuesArray = An array of the form [ValueDefinition₁, ValueDefinition₂, ...]. This defines the values applied at each keyframe point, as matched up with the keyframe points defined in the corresponding KeyframeTimesArray. Note that null values appearing in this array work exactly the same way (and should match up with) null values in the KeyframeTimesArray. Both arrays must have the same number of elements.

ValueGeneratorsArray = An array of the form [ValueGenerator₁, ValueGenerator₂, ...]. This defines the functions that calculate values applied at each keyframe point, as matched up with the keyframe points defined in the corresponding KeyframeTimesArray.

TimeDefinition = A number indicating a point along the sequence timeline. When synchronizing to a media object or running by the system clock, this should ordinarily be specified as a number of milliseconds (1/1000's of a second). Otherwise, there is no restriction; it simply indicates a numeric point on the overall timeline, with no particular unit implied. For instance, a sequence could be synchronized to the value of a slider or other user control, in which case this number would just be anything from the minimum to the maximum values of that control.

ValueDefinition = A value to be applied to the target object feature, or an array of such values. This value can be of any type, although it needs to be one appropriate to the target feature, calculator, and applicator being used. If a unit is specified, the value will be treated as a string and the unit will be appended to it before application. Arrays are allowed as a shorthand method of defining multiple features, values, and units together in a more compact notation. The first value in the array will be matched with the first unit and the first feature in those arrays, and so on. See below samples for an example of using arrays in this way.

ValueGenerator = A function which returns a valid ValueDefinition and has the signature: function generatorFunction(sequence) This is a mechanism that allows specifying functions that will calculate start and end values for a transformation, instead of using fixed values determined at the time the transformation is initially specified. This can be helpful if the same transformation will be run more than once with different start and end values, such as a motion that might be repeated in more than one place on the screen at different times, or if the transformation is being added to the sequence before the actual start and end values are yet known. This is not to be confused with a Calculator function. A Calculator takes a start and end value along with the current time and calculates the current value. This function, by contrast, is called prior to running the sequence and determines what the start and end values are that the Calculator will look at during run-time of the sequence. All of the value generator functions for an entire sequence are called at once, either manually by calling the sequence's generateValues method, or at the time the sequence is run, by specifying true for the generateValues option when calling the run, begin, follow, or syncTo methods. The generator function will be passed a reference to the sequence object containing the transformation whose values are currently being generated.

Source:

Concert.js, line 1743

Examples

Example 1 Below: Single target object and feature, using keyframes, not relying on defaults. This would move a DOM object with id "someObject" by changing its "left" style value from "0px" to "60px" over the timeline period from time 1000 to 2000.

sequence.addTransformations({
    target: document.getElementById("someObject"),
    feature: "left",
    unit: "px",
    applicator: Concert.Applicators.Style,
    calculator: Concert.Calculators.Linear,
    easing: Concert.EasingFunctions.ConstantRate,
    keyframes: { times: [1000, 2000], values: [0, 60] }
  });

Example 2 Below: This example demonstrates adding transformations for more than one target at a time, using both the "keyframes" and "segments" styles of definition, and using arrays for the target features and values. (An array could also have been specified for the "unit" property, but that isn't necessary if the same unit is being used for all the features as it is here.) Also note that the setDefaults method is being used to avoid having to specify common properties over and over again. This code would move the DOM object with id "someObject1" from position (0, 0) to (100, 200) from time 0 to 1000, and would change the width on the object with id "someObject2" from 75 to 150 and back to 75 again over the same time period.

sequence.setDefaults(
  {
    applicator: Concert.Applicators.Style,
    calculator: Concert.Calculators.Linear,
    easing: Concert.EasingFunctions.ConstantRate,
    unit: "px"
  });

sequence.addTransformations(
  [
    {
      target: document.getElementById("someObject1"),
      feature: ["left", "top"],
      keyframes: { times: [0, 1000], values: [[0, 0], [100, 200]] }
    },

    {
      target: document.getElementById("someObject2"),
      feature: "width",
      segments:
        [
          { t0:   0, t1:  500,    v0:  75, v1: 150 },
          { t0: 500, t1: 1000,    v0: 150, v1:  75 },
        ]
    }
  ]);

Example 3 Below: This example demonstrates using value generator functions instead of fixed values. This could would create a single transformation that animates the "left" property of the DOM element with ID "PhotonTorpedoBox". The animation runs from time 0 to time 1000, but the actual values are not yet known. Imagining that we're animating the firing of a torpedo from a ship whose location at the time the torpedo will be fired is not yet known, we set up functions that can determine the proper start and end locations later. Then, whenever it is appropriate to determine and fix the actual numbers, we would call generateValues(), which calls the generator functions and stores the values returned to be used when the sequence is run. (Or, if the generateValues option is specified with a value of true when running the sequence, generateValues() will be called automatically at that time.) Also note, the QuadIn easing function is used here, which will cause the motion to speed up as it proceeds from beginning to end.

sequence.setDefaults(
  {
    applicator: Concert.Applicators.Style,
    calculator: Concert.Calculators.Linear,
    easing: Concert.EasingFunctions.QuadIn,
    unit: "px"
  });

sequence.addTransformations(
  {
    target: document.getElementById("PhotonTorpedoBox"),
    feature: "left",
    segments:
      [{
        t0: 0,
        t1: 1000,
        v0Generator:
          function ()
          {
            var ship = document.getElementById("SpaceshipBox");
            return (ship.offsetLeft + ship.offsetWidth);
          },
        v1Generator:
          function ()
          {
            var ship = document.getElementById("SpaceshipBox");
            return (ship.offsetLeft + ship.offsetWidth + 1000);
          }
      }]
  });
// ... sometime later:
sequence.generateValues();

Example 3b Below: Shown here is the relevant portion of the last example modified to use keyframes notation instead of segments notation.

sequence.addTransformations(
  {
    target: document.getElementById("PhotonTorpedoBox"),
    feature: "left",
    keyframes:
      {
        times: [0, 1000],
        valueGenerators:
        [
          function ()
          {
            var ship = document.getElementById("SpaceshipBox");
            return (ship.offsetLeft + ship.offsetWidth);
          },

          function ()
          {
            var ship = document.getElementById("SpaceshipBox");
            return (ship.offsetLeft + ship.offsetWidth + 1000);
          }
        ]
      }
  });

Example 4 Below: This example demonstrates using custom applicator, calculator, and easing functions to manipulate the width of a DOM object. The code shows a custom applicator function that could be used if we wanted to use a jQuery object containing multiple elements as a target object. Note that Concert.js does NOT depend in any way on jQuery; this example merely shows using the two libraries in conjunction. The custom calculator function below also makes use of jQuery, and shows how a custom calculator could be used to generate truly dynamic values- in this case, it generates the calculated value based on the width at that moment of a particular DOM element. The custom easing function shown here causes the animation to proceed at half-speed for two thirds of the time, then double-speed for the final third of the time.

function customApplicator(target, feature, value, unit)
{
  target.each(function () { $(this).css(feature, value + unit); });
}

function customCalculator(distanceFraction, startValue,
  endValue, addlProperties)
{
  var outerBoxWidth = $("#OuterBox").innerWidth(),
      calculatedValue =
        (distanceFraction
        * (endValue - startValue) * outerBoxWidth);
  return calculatedValue;
}

function customEasing(startTime, endTime, currentTime)
{
  var fractionComplete =
      (currentTime - startTime) / (endTime - startTime);
  if (fractionComplete < 2 / 3)
    return (fractionComplete / 2);
  else
    return (1 / 3 + 2 * (fractionComplete - 2 / 3));
}

sequence.addTransformations(
  {
    target: $(".InnerBox"),
    feature: "width",
    applicator: customApplicator,
    calculator: customCalculator,
    easing: customEasing,
    unit: "px",
    keyframes:
    {
      times: [0, 1000],
      values: [0, 0.5]
    }
  });

begin(parametersopt)

Runs the sequence starting from the beginning, locked to the system clock and automatically stopping upon reaching the end. This is really just a shortcut method provided for a common usage scenario; it is exactly the same as calling the run method with the parameters { synchronizeTo: null, initialSeek: 0, timeOffset: null, autoStopAtEnd: true }. Note that these parameter values can still be overridden, or any of the other parameters accepted by the run method can be specified in the parameters argument passed into this method.

Parameters:

Name	Type	Attributes	Description
`parameters`	Object	<optional>	An object with property values setting options for how to run the sequence. See the run method for information on allowable properties and values in this object.

Source:

Concert.js, line 2542

clone(targetLookupFunction, matchRunningStatusopt, doInitialSeekopt) → {Object}

Creates a duplicate of a sequence, allowing a sequence to be defined once and then cloned to apply to any number of different sets of target objects. For example, the same series of animated motions might be applied to numerous on-screen elements. Since each sequence may contain transformations targeting numerous different objects, this is accomplished by passing in a function that, when passed a transformation target from the original sequence, returns the corresponding object to be targeted in the new sequence. (Note that one useful way of doing this easily is to set the targets of the original sequence to be strings or integers instead of actual objects. The original sequence then just becomes essentially a dummy sequence with placeholder targets that your function can easily identify and use for looking up substitute target objects.) This method is capable of duplicating nearly every aspect of the original sequence, including jumping to the same current point in time and even cloning its running or non-running status if desired. (To change the target objects of a sequence without creating a new one, see the retarget method.)

Parameters:

Name	Type	Attributes	Default	Description
`targetLookupFunction`	function			A function taking a single parameter. The value passed in will be one of the transformation targets of the original sequence. The function must return the equivalent object which should be targeted by the equivalent transformation in the new sequence.
`matchRunningStatus`	boolean	<optional>	false	If `true`, and the sequence being cloned is currently running, the new sequence will jump to the same point on the timeline and run as well. Otherwise, the new sequence will not automatically start running.
`doInitialSeek`	boolean	<optional>	false	If `true`, the new sequence will immediately seek to the same point on the timeline as the original sequence. Otherwise, the new sequence will merely be created, but will not immediately perform any action (unless the matchRunningStatus parameter is `true`).

Source:

Concert.js, line 2563

Returns:

A new Sequence object, with the same properties and duplicates of all the same transformations that were in the original sequence, but with new target objects of those transformations substituted in as controlled by the targetLookupFunction parameter.

Type: Object

Example

One possible method of using this function easily for replicating a sequence definition onto any number of targets is shown below. The initial sequence here is defined with two transformations that are given strings ("UpperElement" and "LowerElement") as targets. The initial sequence is thus just a dummy from which we can clone easily and repeatedly, and the strings make helpful placeholders for the function passed into the clone method to use for matching up to real DOM elements or other intended target objects which we may have created dynamically at a later time. Note further that if you index a sequence before cloning it, resulting cloned sequences will already be indexed and can be run instantly without any indexing lag.

var originalSequence = new Concert.Sequence();
originalSequence.setDefaults(
  {
    applicator: Concert.Applicators.Style,
    calculator: Concert.Calculators.Linear,
    easing: Concert.EasingFunctions.ConstantRate,
    unit: "px"
  });
originalSequence.addTransformations(
  [
    {
      target: "UpperElement", feature: "left",
      keyframes: { times: [0, 1000], values: [100, 200] }
    },
    {
      target: "LowerElement", feature: "left",
      keyframes: { times: [0, 1000], values: [100, 200] }
    }
  ]);

//...some time later, having created DOM elements with id values
// like "UpperElement1", "LowerElement1", "UpperElement2", ...
var newSequence1 = originalSequence.clone(
    function (originalTarget)
    { return document.getElementById(originalTarget + "1"); });
var newSequence2 = originalSequence.clone(
    function (originalTarget)
    { return document.getElementById(originalTarget + "2"); });

follow(syncSource, parametersopt)

Runs a transformation starting from the current timeline position, locked to the specified synchronization source. This differs from the syncTo method in that follow causes the sequence to run exactly in time with the synchronization source and in the same direction, but starting at the current timeline position, whereas with syncTo the sequence will first jump to a timeline position matching the current value of the synchronization source and then do the same. This is really just a shortcut method provided for a common usage scenario; it is exactly the same as calling the run method with the parameters { synchronizeTo: syncSource, initialSeek: null, timeOffset: null }. Note that these parameter values can still be overridden, or any of the other parameters accepted by the run method can be specified in the parameters argument passed into this method.

Parameters:

Name	Type	Attributes	Description
`syncSource`	Varies		A synchronization source. Can take any of the following different types of values: `null`: locks sequence to the system clock. `function object`: the passed-in function is called every time the polling interval is reached, and the return value is used as the seek time. Using a custom function here allows you to synchronize the sequence to anything you want (for instance, locking it to the current value of a UI element, such as a slider, or to another Concert.Sequence object.) `html audio or video DOM object`: locks the sequence to the currentTime property of the media element. This allows the sequence to remain synchronized to the media even when it is paused, scrubbed, or the user skips around.
`parameters`	Object	<optional>	An object with property values setting options for how to run the sequence. See the run method for information on allowable properties and values in this object.

Source:

Concert.js, line 2734

generateValues()

Calls the value generation functions attached to transformations that have value generators instead of fixed start and end values.
It may be useful at times to define transformations whose start and end values are not fixed at the time the transformations are first defined, but which instead are calculated dynamically at some later time prior to running the sequence. This is accomplished by specifying functions instead of start and end values, as explained in the documentation for the addTransformations method. Those functions (for all such transformations in a sequence) are then called, and their return values stored as the start and end values of their respective transformations, either at the time the sequence is run by specifying the appropriate option when calling the run, begin, follow, or syncTo methods, or at any time by calling generateValues.

Source:

Concert.js, line 2776

getCurrentTime() → {number}

Gets the current position along a sequence's timeline.

Source:

Concert.js, line 2806

Returns:

The sequence's current timeline position.

Type: number

getEndTime() → {number}

Gets the end time of a sequence's timeline. This end time of a sequence is considered to be the last end time of any transformation within that sequence.

Source:

Concert.js, line 2822

Returns:

The end time of the sequence's timeline.

Type: number

getID() → {number}

Returns a unique integer identifying this sequence.

Source:

Concert.js, line 2842

Returns:

The sequence ID.

Type: number

getStartTime() → {number}

Gets the start time of a sequences timeline. The start time of a sequence is considered to be the first start time of any transformation within that sequence.

Source:

Concert.js, line 2858

Returns:

The start time of the sequence's timeline.

Type: number

index(completionCallback, isAsynchronous)

Indexes a sequence. This function is run automatically (if necessary) any time a sequence is run or the seek method is called. However, for very large sequences (large enough that indexing would cause a noticable lag), it may be desirable to manually control when indexing takes place (that is, to pre-index the sequence), so that seeking or running will begin instantly. Once indexed, a sequence (or any sequences cloned from it) will not need to be indexed again unless new transformations are added to it.

Explanation of Indexing: Concert.js sequences can consist of very large numbers of transformations applied to numerous target objects, with the ability to seek extremely quickly to any point in the sequence. This is what makes it useful for synchronizing to other things (such as audio or video) and for other situations that require arbitrary seeking, running at different speeds or in either direction, or other uses that don't conform to a simple, run-once-forward-only-at-normal-speed scenario. What makes this possible is an internal data structure that optimizes for quickly finding the correct value to apply to every target feature of every one of the objects being animated, at any point along the timeline. This internal structure involves a set of pre-built indexes of timeline segments. Much like indexes on database tables, this vastly speeds up run-time lookup performance by doing some processing ahead of time to analyze and organize the data. Every sequence needs to be indexed once (or again after any new transformations are added). Running or seeking to any point in an un-indexed sequence will cause indexing to take place automatically, or indexing can be run manually with this method. In many cases, the automatic indexing will run fast enough that manually running the indexer is not necessary.

Parameters:

Name	Type	Description
`completionCallback`	function	This function will be executed upon completion of indexing. It is especially useful if the `isAsynchronous` parameter is set to `true`. The function specified here should have a signature of the form `someCallBackFunction(sequenceObject)`. That is, the function will be called with a single argument, which will be the sequence object whose indexing has completed. (For purposes of handling this callback when there are multiple sequences being manipulated, it may also be helpful to remember that every Sequence object has a unique integer ID which can be retrieved using the getID method.)
`isAsynchronous`	boolean	If `true`, the indexing process will not be run all at once, but will instead be broken into smaller chunks of work and scheduled using calls to `window.setTimeout`. This is useful for very large sequences, to help reduce or eliminate any noticable pause in browser responsiveness while indexing is taking place. For the current version, the indexer makes a best effort to keep each processing chunk under 100 ms. Future versions may allow the programmer to adjust this value, and may also be able to incorporate web workers as a way of pushing most of the work into a completely separate, concurrent thread.

Source:

Concert.js, line 2884

isRunning() → {boolean}

Gets a value indicating whether the sequence is currently running or not.

Source:

Concert.js, line 2951

Returns:

true if the sequence is currently running, false otherwise.

Type: boolean

retarget(targetLookupFunction)

Changes the target objects for all the transformations in a sequence. This could be useful if a sequence is being defined before its targets are created. For instance, if it will be used to animate DOM elements that don't yet exist at the time the sequence is being created, a sequence can be created with placeholder targets (such as strings or integers), and then the real targets substituted in later with this method. (If you wish to apply the same sequence to multiple sets of targets, or to more than one set of targets simultaneously, you may wish to see the clone method.)

Parameters:

Name	Type	Description
`targetLookupFunction`	function	A function that, when passed a transformation target from the sequence as currently defined, returns the new object to be targeted.

Source:

Concert.js, line 2967

run(parametersopt)

Runs the sequence, with the options defined in the parameters object. For many purposes, one of the other run methods (begin, follow, or syncTo) may be easier, because they assume certain default options that are correct in most usage scenarios, but this method is the general-purpose way to run a sequence with any set of behavioral options, and is in fact used behind the scenes by those other methods. Except for generateValues, initialSeek, and timeOffset (the last of which is automatically re-calculated if null), options specified in the parameters object are remembered and will be retained as the default values. This means for restarting stopped sequences, it is not always necessary to explicitly re-state all the options, and it also means that this method can be called on an already-running sequence to change run-time options on the fly.

Parameters:

Name Type Attributes Description

Name	Type	Attributes	Description
`parameters`	Object	<optional>	An object with property values setting options for how to run the sequence. Defined as follows below. Any or all of the below options may be specified: parameters = { // Initial default: Concert.Repeating.None after: VALUE, // Initial default: true autoStopAtEnd: VALUE, // Initial default: Concert.Repeating.None before: VALUE, // Default value: true generateValues: VALUE, // Default: null initialSeek: VALUE, // Initial default: null onAutoStop: VALUE, // Initial default: 0 pollingInterval: VALUE, // Initial default: 1 speed: VALUE, // Initial default: true stretchStartTimeToZero: VALUE, // Initial default: null synchronizeTo: VALUE, // Default value: null timeOffset: VALUE, // Initial default: true useSoleControlOptimization: VALUE } `after = Function which defines how the sequence behaves when the sequence end time is reached and exceeded.` (Can also be set using the setAfter method.) Takes one of the functions defined in the Concert.Repeating namespace, or a custom function. For instance, a value of Concert.Repeating.Loop(2) will cause the sequence to loop back to the beginning twice (thus running a total of three times) before ceasing. See Concert.Repeating for information on the pre-defined values, or see setAfter for more information on using a custom function. `autoStopAtEnd = Boolean value indicating whether or not to automatically call stop() upon hitting the end.` (Note that "the end" means after all looping, bouncing, etc. is taken into account.) `before = Function which defines how the sequence behaves when the calculated current time is at or less than the sequence start time.` (Can also be set using the setBefore method.) Takes one of the functions defined in the Concert.Repeating namespace, or a custom function. For instance, a value of Concert.Repeating.Loop(2) will cause the sequence to loop back to the end twice (thus running a total of three times) before ceasing. See Concert.Repeating for information on the pre-defined values, or see setBefore for more information on using a custom function. `generateValues = Boolean value.` If the sequence has any transformations whose start and end values are dynamic rather than fixed (see addTransformations for details), the actual values to use will have to be calculated at some point in order to run the sequence. This can be accomplished by calling generateValues manually, or it will happen automatically just before run-time if this parameter is set to true. `initialSeek = Numeric value indicating an initial seek point along the timeline.` If specified and non-null, sequence will seek to this time before commencing the run. `onAutoStop = Function called upon reaching the end of the sequence.` This specifies a callback function to be invoked just after automatically stopping at the end of the sequence. It only will be called if autoStopAtEnd is true. `pollingInterval = Numeric value indicating the time in between animation updates.` In other words, how often (in milliseconds) to calculate and seek to a new timeline position when running. Set to any value > 0 for manual control, or set to 0 (or anything < 1) to let Concert determine this automatically. (It does this by using requestAnimationFrame() if the browser supports it, or a fixed interval of 16 ms otherwise.) `speed = Numeric value indicating a run speed multiplier.` (0.5 = half-speed, 2 = double-speed, etc.) `stretchStartTimeToZero = Boolean value indicating whether to treat the sequence start time as 0 even if the first transformation in the sequence starts at a time greater than 0.` This prevents a sequence whose first animations begin some time into the timeline from auto-stopping or triggering its before behavior when it is run from time 0. To define the beginning of the sequence timeline as the beginning of the first transformation in the timeline no matter what, set to false. `synchronizeTo = a variable type which sets a synchronization source for this sequence.` Can take any of the following different types of values: `null`: locks sequence to the system clock. `function object`: the passed-in function is called every time the polling interval is reached, and the return value is used as the seek time. Using a custom function here allows you to synchronize the sequence to anything you want (for instance, locking it to the current value of a UI element, such as a slider, or to another Concert.Sequence object.) `html audio or video DOM object`: locks the sequence to the currentTime property of the media element. This allows the sequence to remain synchronized to the media even when it is paused, scrubbed, or the user skips around. `timeOffset = Numeric value indicating an offset added to the current time before seeking.` This is useful if you want your sequence to run fixed amount ahead of, or behind, your synchronization source. If null, this value is automatically calculated assuming that you want the current sequence time (or the sequence start time if no calls to seek() have yet been made) to match up with the current return value of the synchronization source. For instance, you may have a sequence that runs, locked to the system clock, from time 0 to time 10000 (i.e., for 10 seconds). But the raw value coming from the system clock is never between 0 and 10000; it is the number of milliseconds since January 1, 1970 00:00:00 UTC, which is a very high number. The timeOffset value is therefore added in order to translate the raw starting clock value to the start time of the sequence. But because this automatic translation may not always be the desired behavior, it can be explicitly set here. `useSoleControlOptimization = Boolean value indicating whether the sequence can optimize assuming it is the only thing controlling all the object properties it is modifying.` If your sequence is animating a property whose values could also be modified by anything else, this should be set to `false`. When `true`, the sequence will assume that every value it has set has remained set. If, for instance, two successive animation frames both would set the `left` property of a `DIV` object to "200px", the sequence won't bother setting the value again during second frame, assuming it is still set from the first frame. This speeds up seek times and thus improves overall performance. But if something else has modified the value in the meantime, failing to set the value on the second frame could result in unexpected behavior. See the seek method for details. (Note that regardless of the value specified here, the seek method can be called manually at any point with its useSoleControlOptimization parameter set to either true or false.)

parameters

Object

An object with property values setting options for how to run the sequence. Defined as follows below. Any or all of the below options may be specified:

parameters =
{
  // Initial default: Concert.Repeating.None
  after: VALUE,

  // Initial default: true
  autoStopAtEnd: VALUE,

  // Initial default: Concert.Repeating.None
  before: VALUE,

  // Default value: true
  generateValues: VALUE,

  // Default: null
  initialSeek: VALUE,

  // Initial default: null
  onAutoStop: VALUE,

  // Initial default: 0
  pollingInterval: VALUE,

  // Initial default: 1
  speed: VALUE,

  // Initial default: true
  stretchStartTimeToZero: VALUE,

  // Initial default: null
  synchronizeTo: VALUE,

  // Default value: null
  timeOffset: VALUE,

 // Initial default: true
  useSoleControlOptimization: VALUE
}

after = Function which defines how the sequence behaves when the sequence end time is reached and exceeded. (Can also be set using the setAfter method.) Takes one of the functions defined in the Concert.Repeating namespace, or a custom function. For instance, a value of Concert.Repeating.Loop(2) will cause the sequence to loop back to the beginning twice (thus running a total of three times) before ceasing. See Concert.Repeating for information on the pre-defined values, or see setAfter for more information on using a custom function.

autoStopAtEnd = Boolean value indicating whether or not to automatically call stop() upon hitting the end. (Note that "the end" means after all looping, bouncing, etc. is taken into account.)

before = Function which defines how the sequence behaves when the calculated current time is at or less than the sequence start time. (Can also be set using the setBefore method.) Takes one of the functions defined in the Concert.Repeating namespace, or a custom function. For instance, a value of Concert.Repeating.Loop(2) will cause the sequence to loop back to the end twice (thus running a total of three times) before ceasing. See Concert.Repeating for information on the pre-defined values, or see setBefore for more information on using a custom function.

generateValues = Boolean value. If the sequence has any transformations whose start and end values are dynamic rather than fixed (see addTransformations for details), the actual values to use will have to be calculated at some point in order to run the sequence. This can be accomplished by calling generateValues manually, or it will happen automatically just before run-time if this parameter is set to true.

initialSeek = Numeric value indicating an initial seek point along the timeline. If specified and non-null, sequence will seek to this time before commencing the run.

onAutoStop = Function called upon reaching the end of the sequence. This specifies a callback function to be invoked just after automatically stopping at the end of the sequence. It only will be called if autoStopAtEnd is true.

pollingInterval = Numeric value indicating the time in between animation updates. In other words, how often (in milliseconds) to calculate and seek to a new timeline position when running. Set to any value > 0 for manual control, or set to 0 (or anything < 1) to let Concert determine this automatically. (It does this by using requestAnimationFrame() if the browser supports it, or a fixed interval of 16 ms otherwise.)

speed = Numeric value indicating a run speed multiplier. (0.5 = half-speed, 2 = double-speed, etc.)

stretchStartTimeToZero = Boolean value indicating whether to treat the sequence start time as 0 even if the first transformation in the sequence starts at a time greater than 0. This prevents a sequence whose first animations begin some time into the timeline from auto-stopping or triggering its before behavior when it is run from time 0. To define the beginning of the sequence timeline as the beginning of the first transformation in the timeline no matter what, set to false.

synchronizeTo = a variable type which sets a synchronization source for this sequence. Can take any of the following different types of values:

null: locks sequence to the system clock.
function object: the passed-in function is called every time the polling interval is reached, and the return value is used as the seek time. Using a custom function here allows you to synchronize the sequence to anything you want (for instance, locking it to the current value of a UI element, such as a slider, or to another Concert.Sequence object.)
html audio or video DOM object: locks the sequence to the currentTime property of the media element. This allows the sequence to remain synchronized to the media even when it is paused, scrubbed, or the user skips around.

timeOffset = Numeric value indicating an offset added to the current time before seeking. This is useful if you want your sequence to run fixed amount ahead of, or behind, your synchronization source. If null, this value is automatically calculated assuming that you want the current sequence time (or the sequence start time if no calls to seek() have yet been made) to match up with the current return value of the synchronization source. For instance, you may have a sequence that runs, locked to the system clock, from time 0 to time 10000 (i.e., for 10 seconds). But the raw value coming from the system clock is never between 0 and 10000; it is the number of milliseconds since January 1, 1970 00:00:00 UTC, which is a very high number. The timeOffset value is therefore added in order to translate the raw starting clock value to the start time of the sequence. But because this automatic translation may not always be the desired behavior, it can be explicitly set here.

useSoleControlOptimization = Boolean value indicating whether the sequence can optimize assuming it is the only thing controlling all the object properties it is modifying. If your sequence is animating a property whose values could also be modified by anything else, this should be set to false. When true, the sequence will assume that every value it has set has remained set. If, for instance, two successive animation frames both would set the left property of a DIV object to "200px", the sequence won't bother setting the value again during second frame, assuming it is still set from the first frame. This speeds up seek times and thus improves overall performance. But if something else has modified the value in the meantime, failing to set the value on the second frame could result in unexpected behavior. See the seek method for details. (Note that regardless of the value specified here, the seek method can be called manually at any point with its useSoleControlOptimization parameter set to either true or false.)

Source:

Concert.js, line 2997

seek(time, useSoleControlOptimizationopt)

Seeks to the specified point along the sequence timeline. If the time value is less than the sequence's start time or greater than the sequence's end time, the resulting behavior will be defined by the sequence's "before" or "after" repeating behavior settings, as controlled by the setBefore and setAfter methods or by the options passed into the run, begin, follow, or syncTo methods. The default behavior, if none has explicitly been specified, is Concert.Repeating.None, which seeks to the sequence start time for any time value less than or equal to the sequence's start time, and to the end time for any time value greater than or equal to the sequence's end time. The useSoleControlOptimization option, when set to true, enhances run-time performance, but should only be used if nothing other than the Concert sequence will be modifying any target object properties that are modified by transformations in the sequence. Essentially it skips updating target object properties any time a newly calculated value is the same as the last one applied. This speeds up seek times, especially when doing relatively slow things such as DOM updates. However, if a target object property's value has been changed by something else since the last time the sequence object touched it, this optimization can result in that value not being updated by the seek() function.

Parameters:

Name	Type	Attributes	Description
`time`	number		The intended seek point.
`useSoleControlOptimization`	boolean	<optional>	Whether or not the sequence can optimize by assuming sole control over the target objects.

Source:

Concert.js, line 3263

setAfter(newAfter)

Sets the behavior of the sequence when asked to seek after its end time. For instance, it may halt, loop, or bounce.

Parameters:

Name	Type	Description
`newAfter`	function	One of the functions defined in Concert.Repeating, or a custom function. For any sequence where this is not explicitly set, the "after" behavior defaults to `Concert.Repeating.None`. Any function passed in here should have a signature of the form `function (sequenceStart, sequenceEnd, unadjustedTime)` and must return an object of the form `{ adjustedTime: XXX, hitFinalBoundary: YYY }`, where `XXX` is the actual time to use in the seek, and `YYY` is a boolean value indicating whether this seek will put the sequence at one of its final boundary points. For instance, a looping behavior function could take an `unadjustedTime` value past the end of the sequence and map it to a resulting value somewhere between the sequence start and end times, and if it does not loop infinitely, a high enough input would result in hitting the final boundary beyond which looping does not continue. The `hitFinalBoundary` property value is what is used to determine whether to automatically call the stop method if running with `autoStopAtEnd` set to `true`.

Source:

Concert.js, line 3371

setBefore(newBefore)

Sets the behavior of the sequence when asked to seek before its start time. For instance, it may halt, loop, or bounce.

Parameters:

Name	Type	Description
`newBefore`	Object	One of the functions defined in Concert.Repeating, or a custom function. For any sequence where this is not explicitly set, the "after" behavior defaults to `Concert.Repeating.None`. Any function passed in here should have a signature of the form `function (sequenceStart, sequenceEnd, unadjustedTime)` and must return an object of the form `{ adjustedTime: XXX, hitFinalBoundary: YYY }`, where `XXX` is the actual time to use in the seek, and `YYY` is a boolean value indicating whether this seek will put the sequence at one of its final boundary points. For instance, a looping behavior function could take an `unadjustedTime` value past the end of the sequence and map it to a resulting value somewhere between the sequence start and end times, and if it does not loop infinitely, a high enough input would result in hitting the final boundary beyond which looping does not continue. The `hitFinalBoundary` property value is what is used to determine whether to automatically call the stop method if running with `autoStopAtEnd` set to `true`.

Source:

Concert.js, line 3395

setDefaults(newDefaults)

When adding transformations to a sequence, several properties have default values and can therefore be left unspecified in the objects passed into the addTransformations method. This can be very helpful in avoiding repetition if most or all of the transformations have the same values for these properties. This method sets those default values for new transformations added to the sequence.

Parameters:

Name Type Description

Name	Type	Description
`newDefaults`	Object	An object with property values setting default options for new transformations. Defined as follows. Any or all of the below options may be specified. `newDefaults = { // Default: Concert.Applicators.Property applicator: VALUE, // Default: Concert.Calculators.Linear calculator: VALUE, // Default: Concert.EasingFunctions.ConstantRate easing: VALUE, // Default: null (no unit at all) unit: VALUE, }` `applicator = Function used to apply calculated target feature values to the target feature.` One of the Concert.Applicators functions, or a custom function. See Concert.Applicators and addTransformations for more information about the meaning of this property and its allowable values. `calculator = Function used to calculate values applied to the target feature during the animation.` One of the Concert.Calculators functions, or a custom function. See Concert.Calculators and addTransformations for more information about the meaning of this property and its allowable values. `easing = Function used to specify a rate curve for the animation.` One of the Concert.EasingFunctions functions, or a custom function. See Concert.EasingFunctions and addTransformations for more information about the meaning of this property and its allowable values. `unit = String indicating the unit to be appended to the end of a calculated value before it is applied, or null if there is none.` Common values would include "px", "%", "em", and so on.

newDefaults

Object

An object with property values setting default options for new transformations. Defined as follows. Any or all of the below options may be specified.

newDefaults =
{
  // Default: Concert.Applicators.Property
  applicator: VALUE,

  // Default: Concert.Calculators.Linear
  calculator: VALUE,

  // Default: Concert.EasingFunctions.ConstantRate
  easing: VALUE,

 // Default: null (no unit at all)
  unit: VALUE,
}

applicator = Function used to apply calculated target feature values to the target feature. One of the Concert.Applicators functions, or a custom function. See Concert.Applicators and addTransformations for more information about the meaning of this property and its allowable values.

calculator = Function used to calculate values applied to the target feature during the animation. One of the Concert.Calculators functions, or a custom function. See Concert.Calculators and addTransformations for more information about the meaning of this property and its allowable values.

easing = Function used to specify a rate curve for the animation. One of the Concert.EasingFunctions functions, or a custom function. See Concert.EasingFunctions and addTransformations for more information about the meaning of this property and its allowable values.

unit = String indicating the unit to be appended to the end of a calculated value before it is applied, or null if there is none. Common values would include "px", "%", "em", and so on.

Source:

Concert.js, line 3419

stop()

Stops a currently running sequence. Calling this function, whether explicitly or by setting autoStopAtEnd to true, is recommended when you wish the sequence to stop running or synchronizing, because otherwise the timers which continually update the sequence will continue to run. This may be the desired behavior if the sequence is being synchronized to a value which may continue to change, but in many cases it would be a waste of processor cycles to continue running a completed sequence. (Note that autoStopAtEnd is automatically enabled if the sequence is run using the begin method.)

Source:

Concert.js, line 3495

syncTo(syncSource, parametersopt)

Runs a transformation locked to the specified synchronization source and matching its position. This differs from the follow method in that follow causes the sequence to run exactly in time with the synchronization source and in the same direction, but starting at the current timeline position, whereas with syncTo the sequence will first jump to a timeline position matching the current value of the synchronization source and then do the same. This is really just a shortcut method provided for a common usage scenario; it is exactly the same as calling the run method with the parameters { synchronizeTo: syncSource, initialSeek: null, timeOffset: 0, autoStopAtEnd: false }. Note that these parameter values can still be overridden, or any of the other parameters accepted by the run method can be specified in the parameters argument passed into this method.

Parameters:

Name	Type	Attributes	Description
`syncSource`	Varies		A synchronization source. Can take any of the following different types of values: `null`: locks sequence to the system clock. `function object`: the passed-in function is called every time the polling interval is reached, and the return value is used as the seek time. Using a custom function here allows you to synchronize the sequence to anything you want (for instance, locking it to the current value of a UI element, such as a slider, or to another Concert.Sequence object.) `html audio or video DOM object`: locks the sequence to the currentTime property of the media element. This allows the sequence to remain synchronized to the media even when it is paused, scrubbed, or the user skips around.
`parameters`	Object	<optional>	An object with property values setting options for how to run the sequence. See the run method for information on allowable properties and values in this object.

Source:

Concert.js, line 3520