Tweener: Cinnamon Javascript Reference Manual

## Tweener Tweener — File providing tweening functions |

## Functions

| init ()
| addTween ()
| getTweenCount ()
| isTweening ()
| removeTween ()
| pauseTweens ()
| resumeTweens ()

## Description

This is a wrapper around imports.tweener.tweener that adds a bit of Clutter integration and some additional callbacks:

1. If the tweening target is a Clutter.Actor, then the tweenings will automatically be removed if the actor is destroyed

2. If target._delegate.onAnimationStart() exists, it will be called when the target starts being animated.

3. If target._delegate.onAnimationComplete() exists, it will be called once the target is no longer being animated.

The onAnimationStart() and onAnimationComplete() callbacks differ from the tweener onStart and onComplete parameters, in that (1) they track whether or not the target has any tweens attached to it, as opposed to be called for each tween, and (2) onAnimationComplete() is always called when the object stops being animated, regardless of whether it stopped normally or abnormally.

onAnimationComplete() is called at idle time, which means that if a tween completes and then another is added before returning to the main loop, the complete callback will not be called (until the new tween finishes).

ActionScript Tweener methods that imports.tweener.tweener doesn't currently implement: getTweens, getVersion, registerTransition, setTimeScale, updateTime.

imports.tweener.tweener methods that we don't re-export: pauseAllTweens, removeAllTweens, resumeAllTweens. (It would be hard to clean up properly after removeAllTweens, and also, any code that calls any of these is almost certainly wrong anyway, because they affect the entire application.)

## Functions

### init ()

    init ();

Function called by main.js when Cinnamon starts

### addTween ()

    addTween (Object   target,
              param    tweeningParameters);

This makes `target` tween according to the parameters of `tweeningParameters`.

`tweeningParameters` contains certain tweening parameters that describe the tween, and the actual things to tween. Everything that is not a tweening parameter is processed as follows: If you have

    1
    2
    3
    4
    5
    {
        ...
        x: 7
        ...
    }

In your parameters, then the property `x` of the `target` object will be animated to the value of `7`.

The tweening parameters are (shamelessly stolen from the actual Tweener documentation):

- `time` (real): The duration of the transition in seconds

- `delay` (real): The delay (in seconds) before the transition starts. The default of this parameter (when omitted) is 0.

- `skipUpdates` (int): How many updates must be skipped before an actual update is made. This is a powerful property that allows the developer to enforce a different update rate for a given tweening, as if simulating a lower frame rate. This is useful on transitions that demand a share of the CPU that's higher than average on each new update, such as filter tweenings. A value of 1, for example, means that the tweening engine will do half of the updates on this transition, since it will update then skip one update; a value of 2 means it will do one third of the normal updates, since it will update, then skip two updates. The default value for this parameter (when omitted) is 0, meaning no update is skipped at all, and the active tweenings are updated on every frame render.

- `transition` (string/function): The type of transition to use. Different equations can be used, producing different tweening updates based on time spent. You can specify this parameter by their internal string names (which you can find by seeing what's offered in the cinnamon-settings effects page), or use any custom function to have a customized easing (see below for examples and a more in-depth description). The default transition is "easeOutExpo".

  If you want to use a custom function as the transition, the function must receive four parameters: current time on the transition, starting tweening value, change needed in that value, and total easing duration (plus an optional object, which will contain any parameter passed as the transitionParams property of new tweenings). During each tweening, the transition function will be continuously called, with the first parameter increasing until it reaches the total duration; it must return the new expected value.

  An example of a custom transition is as follows:

      1
      2
      3
      4
      5
      6
      let myFunc = function(t, b, c, d) {
          let ts = (t/=d)*t;
          let tc = ts*t;
          return b+c*(-97.1975*tc*ts + 257.5975*ts*ts + -234.4*tc + 80*ts + -5*t);
      };
      Tweener.addTween(this.actor, {x: 200, time: 1, transition: myFunc});

- `transitionParams` (array): extra parameters to pass to the custom transition function

- `onStart` (function): A function that is called immediately before a tweening starts. It is called once regardless of the number of properties involved on the tweening. The function scope (in which the event is executed) is the target object itself, unless specified by the onStartScope parameter.

- `onUpdate` (function): A function that is called every time a tweening updates its properties. The function scope (in which the event is executed) is the target object itself, unless specified by the `onUpdateScope` parameter.

- `onComplete` (function): A function that is called immediately after a tweening is completed. It is called once regardless of the number of properties involved on the tweening. The function scope (in which the event is executed) is the target object itself, unless specified by the `onCompleteScope` parameter.

- `onOverwrite` (function): A function that is called when tweening is overwritten. It is called once regardless of the number of properties involved on the tweening. The function scope is the target object itself, unless specified by the `onOverwriteScope` parameter.

- `onError` (function): A function that gets called when an error occurs when trying to run a tweening. This is used to handle errors more commonly thrown by other events (that is, from code not controlled by Tweener), such as onStart, onUpdate or onComplete. The function scope (in which the event is executed) is the target object itself, unless specified by the `onErrorScope` parameter.

- `rounded` (boolean): Whether or not the values for this tweening must be rounded before being applied to their respective properties. This is useful, for example, when sliding objects that must be positioned on round pixels, like labels that use pixel fonts; its x and y properties need to be rounded all the time to avoid blurring the text. This option acts on all properties for that specific tween. The default value for this parameter (when omitted) is false.

- `min` (real): The minimum the values of this tweening can take. This is useful, for example, when you animate the opacity of an object with a bounce transition and don't want the opacity of an object to fall below 0. Leave empty for no minimum.

- `max` (real): The maximum the values of this tweening can take. This is useful, for example, when you animate the opacity of an object with a bounce transition and don't want the opacity of an object to go above 1. Leave empty for no maximum.

- `onStartParams` (array): A list of parameters (of any type) to be passed to the onStart function.

- `onUpdateParams` (array): A list of parameters (of any type) to be passed to the onUpdate function.

- `onCompleteParams` (array): A list of parameters (of any type) to be passed to the onComplete function.

- `onOverwriteParams` (array): A list of parameters (of any type) to be passed to the onOverwrite function.

- `onStartScope` (object): The object in which the onStart function will be executed. This is needed if you have some specialized code inside the event function; in that case, references to this. inside the function will reference to the object defined by this parameter. If omitted, the tweened object is the scope used instead.

- `onUpdateScope` (object): The object in which the onUpdate function will be executed. This is needed if you have some specialized code inside the event function; in that case, references to this. inside the function will reference to the object defined by this parameter. If omitted, the tweened object is the scope used instead.

- `onCompleteScope` (object): The object in which the onComplete function will be executed. This is needed if you have some specialized code inside the event function; in that case, references to this. inside the function will reference to the object defined by this parameter. If omitted, the tweened object is the scope used instead.

- `onOverwriteScope` (object): The object in which the onOverwrite function will be executed. This is needed if you have some specialized code inside the event function; in that case, references to this. inside the function will reference to the object defined by this parameter. If omitted, the tweened object is the scope used instead.

- `onErrorScope` (object): The object in which the onError function will be executed. This is needed if you have some specialized code inside the event function; in that case, references to this. inside the function will reference to the object defined by this parameter. If omitted, the tweened object is the scope used instead.

#### Parameters

target | the object to tween |
tweeningParameters | parameters |

### getTweenCount ()

    getTweenCount (Object   scope);

Returns the number of tweens `scope` currently has.

#### Parameters

scope | the object we are interested in |

### isTweening ()

    isTweening (Object   scope);

Returns whether `scope` is animating

#### Parameters

scope | the object we are interested in |

### removeTween ()

    removeTween (Object   scope);

Removes all tweens running on the object.

FIXME: removeTweens should be much more powerful, but I have no idea how it works

#### Parameters

scope | the object we are interested in |

### pauseTweens ()

    pauseTweens (Object   scope);

Pauses all the tweens running on the object. Can be resumed with Tweener.resumeTweens

FIXME: removeTweens should be much more powerful, but I have no idea how it works

#### Parameters

scope | the object we are interested in |

### resumeTweens ()

    resumeTweens (Object   scope);

Resumes all the tweens running on the object paused by Tweener.pauseTweens

FIXME: removeTweens should be much more powerful, but I have no idea how it works

#### Parameters

scope | the object we are interested in |