# Tween

Allows tweening `Object` properties between two states for a given duration. To tween properties on Paper.js `Item` instances, `item.tween(from, to, options)` can be used, which returns created tween instance.

## Constructors

* `Tween(object, from, to, duration[, easing[, start]])`

  Creates a new tween.

  * Parameters:
  * `object:` `Object` — the object to tween the properties on
  * `from:` `Object` — the state at the start of the tweening
  * `to:` `Object` — the state at the end of the tweening
  * `duration:` `Number` — the duration of the tweening
  * `easing:` `String`⟋`Function` — the type of the easing function or the easing function — optional, default: `‘linear’`
  * `start:` `Boolean` — whether to start tweening automatically — optional, default: `true`
  * Returns:
  * `Tween` — the newly created tween

## Properties

### Event Handlers

* `onUpdate`

  The function to be called when the tween is updated. It receives an object as its sole argument, containing the current progress of the tweening and the factor calculated by the easing function.

  * Type:
  * `Function`⟋`null`

  Example:Display tween progression values:

  ```jsx
  var circle = new Path.Circle({
      center: view.center,
      radius: 40,
      fillColor: 'blue'
  });
  var tween = circle.tweenTo(
      { fillColor: 'red' },
      {
          duration: 2000,
          easing: 'easeInCubic'
      }
  );
  var progressText = new PointText(view.center + [60, -10]);
  var factorText = new PointText(view.center + [60, 10]);

  // Install event using onUpdate() property:
  tween.onUpdate = function(event) {
      progressText.content = 'progress: ' + event.progress.toFixed(2);
  };

  // Install event using on('update') method:
  tween.on('update', function(event) {
      factorText.content = 'factor: ' + event.factor.toFixed(2);
  });
  ```

## Methods

* `then(function)`

  Set a function that will be executed when the tween completes.

  * Parameters:
  * `function:` `Function` — the function to execute when the tween completes
  * Returns:
  * `Tween`

  Example:Tweens chaining:

  ```jsx
  var circle = new Path.Circle({
      center: view.center,
      radius: 40,
      fillColor: 'blue'
  });
  // Tween color from blue to red.
  var tween = circle.tweenTo({ fillColor: 'red' }, 2000);
  // When the first tween completes...
  tween.then(function() {
      // ...tween color back to blue.
      circle.tweenTo({ fillColor: 'blue' }, 2000);
  });
  ```
* `start()`

  Start tweening.

  * Returns:
  * `Tween`

  Example:Manually start tweening.

  ```jsx
  var circle = new Path.Circle({
      center: view.center,
      radius: 40,
      fillColor: 'blue'
  });
  var tween = circle.tweenTo(
      { fillColor: 'red' },
      { duration: 2000, start: false }
  );
  tween.start();
  ```
* `stop()`

  Stop tweening.

  * Returns:
  * `Tween`

  Example:Stop a tween before it completes.

  ```jsx
  var circle = new Path.Circle({
      center: view.center,
      radius: 40,
      fillColor: 'blue'
  });
  // Start tweening from blue to red for 2 seconds.
  var tween = circle.tweenTo({ fillColor: 'red' }, 2000);
  // After 1 second...
  setTimeout(function(){
      // ...stop tweening.
      tween.stop();
  }, 1000);
  ```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://paperjs.typogram.co/animation/tween.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.