tweenengine 0.12.0

  • readme.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 9

Build Status

License

Apache License 2.0

About

This is a dart port of the original java Universal Tween Engine created by Aurelien Ribbon. This readme is an adaptation of the original's engine readme and includes how things are handled in the dart version of the engine.

You can find a demo of the library here. The engine might have some bugs. Use at your own risk.


Introduction

The Universal Tween Engine enables the interpolation of every attribute from any object in any dart project (server or client side). Tweens are 'fire and forget'.

Implementing

Dart, unlike javascript, has no string accessors for objects, such as myObject['myProperty']. Reflection methods are still under development in Dart, and they will be slow. So, there are two ways of telling the engine which properties you want to tween. The first one is very useful if you do not have control over the class you want to tween a property of. The second one is a bit less verbose but requires code in the class you want to tween.

Using TweenAccessor

Create an accessor that implements the TweenAccessor interface, register it to the engine, and animate anything you want!

class MyAccessor implements TweenAccessor<MyClass>{
  static const Type1 = 1;
  
  int getValues(MyClass target, Tween tween, int tweenType, List<num> returnValues){
    if ( tweenType == MyAccessor.Type1 ){
      returnValues[0] = target.x;
      returnValues[1] = target.y;
      return 2;
    }
    return 0;
  }

  void setValues(MyClass target, Tween tween, int tweenType, List<num> newValues){
    if ( tweenType == MyAccessor.Type1 ){
      target.x = newValues[0];
      target.y = newValues[1];
    }
  }
}

class MyClass{
  num x=0, y=0;
}

main(){
   Tween.registerAccessor(MyClass, new MyAccessor());
}

Using Tweenable

Make sure the class you want to tween implements the Tweenable interface.

class MyTweenable implements Tweenable {
  static const int ANSWER = 1;
  static const int CIRCLE = 2;

  int answer = 42;
  num circle = 6.2831853;

  /**
   * Updates [returnValues] with the values of the properties you want to tween
   * when you run a `tweenType` tween.
   * Returns the number of values set in [returnValues].
   */
  int getTweenableValues(int tweenType, Tween tween, List<num> returnValues) {
    if (tweenType == ANSWER) {
      returnValues[0] = answer;
    } else if (tweenType == CIRCLE) {
      returnValues[0] = circle;
    }
    return 1;
  }

  /**
   * Updates this object's properties with values from [newValues],
   * in the [tweenType] fashion of `getTweenableValues`.
   */
  void setTweenableValues(int tweenType, Tween tween, List<num> newValues) {
    if (tweenType == ANSWER) {
      answer = newValues[0];
    } else if (tweenType == CIRCLE) {
      circle = newValues[0];
    }
  }
}

Updating

For the tween to be completed, a continuous call to your TweenManager's .update(delta) is needed. The delta parameter represents the time elapsed in milliseconds since last call to update.

An easy way to obtain the delta is the window.animationFrame method:


TweenManager myManager;
main(){
  ...
  myManager = new TweenManager();
  window.animationFrame.then(update);
}

num lastUpdate = 0;
update(num delta){
  num deltaTime = (delta - lastUpdate) / 1000;
  lastUpdate = delta;
  
  myManager.update(deltaTime);
  window.animationFrame.then(update);
}

Next, send your objects to another position (here x=20 and y=30), with a smooth elastic transition, during 1 second.

// Arguments are 
// 1. the target
// 2. the type of interpolation
// 3. the duration in seconds
// Additional methods specify the target values, and the easing function. 

main(){
  ...
  Tween.to(myClass, MyAccessor.Type1, 1.0)
    ..targetValues = [20, 30]
    ..easing = Elastic.INOUT;
  window.animationFrame.then(update);
}

API

Possibilities are:

Tween.to(...);   // interpolates from the current values to the targets
Tween.from(...); // interpolates from the given values to the current ones
Tween.set(...);  // apply the target values without animation (useful with a delay)
Tween.call(...); // calls a method (useful with a delay)

Current options are:

myTween.delay = 0.5;
myTween.repeat(2, 0.5);
myTween.repeatYoyo(2, 0.5); 
myTween.pause();
myTween.resume();
myTween.callback = callback;
myTween.callbackTriggers = flags;
myTween.userData = obj;

You can of course chain everything (with dart's method cascading):

new Tween.to(...)
 ..delay = 1
 ..repeat(2, 0.5)
 ..start(myManager);

By altering the delta parameter, adding slow-motion, fast-motion or reverse play is easy, you just need to change the speed of the update:

myManager.update(delta * speed);

Create some powerful animation sequences!

new Timeline.sequence()
    // First, set all objects to their initial positions
    ..push(Tween.set(...))
    ..push(Tween.set(...))
    ..push(Tween.set(...))

    // Wait 1s
    ..pushPause(1.0)

    // Move the objects around, one after the other
    ..push(Tween.to(...))
    ..push(Tween.to(...))
    ..push(Tween.to(...))

    // Then, move the objects around at the same time
    ..beginParallel()
        ..push(Tween.to(...))
        ..push(Tween.to(...))
        ..push(Tween.to(...))
    ..end()

    // And repeat the whole sequence 2 times
    // with a 0.5s pause between each iteration
    ..repeatYoyo(2, 0.5)

    // Let's go!
    ..start(myManager);

You can also quickly create timers:

new Tween.call(myCallback)
  ..delay = 3000
  ..start(myManager);

Main features

  • Supports every interpolation function defined by Robert Penner.
  • Can be used with any object. You just have to implement the TweenAccessor interface when you want interpolation capacities.
  • Every attribute can be interpolated. The only requirement is that what you want to interpolate can be represented as a number.
  • One line is sufficient to create and start a simple interpolation.
  • Delays can be specified, to trigger the interpolation only after some time.
  • Many callbacks can be specified (when tweens complete, start, end, etc.).
  • Tweens and Timelines are pooled by default. If enabled, there won't be any object allocation during runtime!
  • Tweens can be sequenced when used in Timelines.
  • Tweens can act on more than one value at a time, so a single tween can change the whole position (X and Y) of a sprite for instance !
  • Tweens and Timelines can be repeated, with a yoyo style option.
  • Simple timers can be built with Tween.callBack().
  • Source code extensively documented!
  • Test suite included!

Testing suite

Since 0.10.0, tweenengine has a (crude) test suite. It leverages the unittest package.

To run it, you'll either need Dartium or dart2js.

Using Dartium

Browse test/test.html.

Using dart2js

Compile test/test.dart to test/test.dart.js :

$ dart2js test/test.dart -v -o test/test.dart.js

Then, browse test/test.html.

V 0.12.0

  • compatible with Dart 2.0/strong mode
  • Tween.targetValues, Tween.targetRelative and Tween.addWayoint no longer accepts num, only List<num>
  • constants are no longer SCREAMING_CAPS but lowerCamelCase
  • TweenEquation (e.g. Bounce.IN, Sine.OUT, etc.) values have been renamed from IN, OUT, INOUT to easeIn, easeOut, easeInOut respectively

V 0.11.0

  • Fixed issue #12 typo in tween.containsTarget which would make it missfunction

V 0.11.0

  • Timeline.createSequence() and Timeline.createParallel() are now replaced for factory named constructors:
    • new Timeline.sequence()
    • new Timeline.parallel()
  • Tween.to, Tween.from, Tween.set, Tween.call and Tween.mark are now replaced for factory named constructors:
    • new Tween.to()
    • new Tweee.from()
    • new Tween.set()
    • new Tween.call()
    • new Tween.mark()
  • TweenAccesor and Tweenable interfaces have both changed, now they both receive the tween as a paremeter in their getValues() and setValues() methods.
  • BaseTween.normalTime added, provides the normalized elapsed time of the tween ( 0 <= normalTime <= 1)

V 0.10.2

  • Fixed a bug where creating a new Tween from within a callback would break the TweenManager
  • Methods setCallback, setCallbackTriggers and setUserData replaced by their respective setters
  • repeatYoyo() will be deprecated in next version, instead, repeat() now takes a bool argument saying wether it is a yoyo repetition or not.
  • Removed generic argument from BaseTween class

V 0.10.1

Bugs Fixed:

  • Changed Timeline to not 'snap' when using a repeat yoyo on it. issue #7
  • added Changelog
  • changed CallbackHandler to TweenCallbackHandler
  • Twee.setCallBack() now receives a TweenCallbackHandler(function) instead of a TweenCallback instance

V 0.10.0

  • added tweenable interface
  • added crude test suit
  • loosened dart sdk dependency

V 0.9.0

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  tweenengine: ^0.12.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:tweenengine/tweenengine.dart';
  
Version Uploaded Documentation Archive
0.12.0 Oct 3, 2018 Go to the documentation of tweenengine 0.12.0 Download tweenengine 0.12.0 archive
0.11.1 Sep 12, 2014 Go to the documentation of tweenengine 0.11.1 Download tweenengine 0.11.1 archive
0.11.0 Aug 26, 2014 Go to the documentation of tweenengine 0.11.0 Download tweenengine 0.11.0 archive
0.10.2 Aug 11, 2014 Go to the documentation of tweenengine 0.10.2 Download tweenengine 0.10.2 archive
0.10.1 Aug 6, 2014 Go to the documentation of tweenengine 0.10.1 Download tweenengine 0.10.1 archive
0.10.0 Apr 7, 2014 Go to the documentation of tweenengine 0.10.0 Download tweenengine 0.10.0 archive
0.9.0 Jan 31, 2014 Go to the documentation of tweenengine 0.9.0 Download tweenengine 0.9.0 archive
Popularity:
Describes how popular the package is relative to other packages. [more]
18
Health:
Code health derived from static analysis. [more]
--
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
--
Overall:
Weighted score of the above. [more]
9
Learn more about scoring.

The package version is not analyzed, because it does not support Dart 2. Until this is resolved, the package will receive a health and maintenance score of 0.

Analysis issues and suggestions

Support Dart 2 in pubspec.yaml.

The SDK constraint in pubspec.yaml doesn't allow the Dart 2.0.0 release. For information about upgrading it to be Dart 2 compatible, please see https://www.dartlang.org/dart-2#migration.

Maintenance issues and suggestions

Running dartdoc failed. (-10 points)

Make sure dartdoc runs without any issues.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev <2.0.0