TTween documentation

tweensTweening, short for “in-betweening”, is a programming technique for transitioning between values within a given timeframe. Tweening allows you to define a start and stop value, and the class calculates the intermediate positions using mathematical formulas. In other words: it ensures that a value will be changed within the time you allow it.

Tweens are very cost-effective in programming terms, especially for graphics and animations, since they calculate only the number of possible steps or values that can be achieved in the time-frame you allow.

Tweening is almost synonymous with graphics programming since it helps remove unnessesary re-drawing of moving graphics elements. It has become nearly a standard for touch based mobile devices, not just for saving CPU power but also adding a sense of visual responsiveness.  But tweening is not new, as a coding technique it was commonly used in demonstrations during the 80’s and 90’s (then called “time morphing”). It first appeared on the Commodore Amiga in a demo called 9 fingers (1993). It re-surfaced and became mainstream with the release of Apple iOS in 2007. The way forms and dialogs move under iOS, with smooth sliding and acceleration / deacceleration (easing) from one position onto another; these effects are archetypical “tweening” transformations.

You can read more about tweening on Wikipedia.

TTween class

TTween was originally a port of simpletween.js which is a popular JavaScript library with good performance and a humble footprint. The library contains a large repertoire of easing formulas (mathematical formulas responsible for value transformations) and ultimately, the footprint and features made simpletween.js an obvious candidate for adoption into the Smart Mobile Studio RTL.

It is important to underline that simpletween.js only delivered the bare necessities. The Smart Pascal version is a matured and much more evolved implementation. First and foremost full object orientation, one of Smart Pascal’s biggest strengths, giving you the ability to execute and manage an unlimited amount of transformations. So where simpletween.js originally managed a single transformation, our version can have hundreds of tweens running at the same time. This makes TTween suitable for high-end, professional multimedia.

To ensure maximum efficiency and speed, TTween uses lookup-tables (dictionaries) whenever possible for optimal execution speed. Tween elements (each transformation is represented by an object) are likewise indexed using dictionaries – further increasing efficiency and handling of named objects.

Combined with Smart Mobile Studio’s powerful RTL architecture, TTween is one of the best implementations of tweening for the JavaScript platform.

Methods

  • Add
  • Cancel
  • Clear
  • Delete
  • Execute
  • Pause
  • Resume
  • ObjectOf
  • IndexOf
  • TimeCode

Properties

  • Active
  • Count
  • Interval
  • IgnoreOscillate
  • SyncRefresh
  • Items[index]
  • Tween[id]

Events

  • OnUpdated
  • OnPartialFinished
  • OnFinished
  • OnStarted

 

Add

The Add() method adds a tween element (TW3TweenElement) to the internal object list. Once added, the elements are subject to the internal update sequence. The class exposes 3 different variations of the Add() method, these are:

 function Add(Id:String):TTweenElement;overload;
 function Add(Id:String;const aStartValue,aDistance,aDuration:double;
 const aAnimationType:TTweenEasingType;
 const aBehavior:TTweenBehavior):TTweenElement;overload;
 function Add(const Instance:TTweenElement):TTweenElement;overload;

Cancel

Calling Cancel() stops all active tween operations. This also exits the internal update sequence.

Note: This method completely abort everything. This operation cannot be recovered from through Resume().

Clear

Calling Clear() deletes and releases all tween elements regardless of state. If called while active, the empty object-list causes the internal update sequence to halt.

Note: This method completely abort everything. This operation cannot be recovered from through Resume().

Delete

Calling one of the overloaded Delete() methods removes one or several tween elements from the internal object list. The overloaded variations are:

 procedure Delete(index:Integer);overload;
 procedure Delete(Id:String);overload;
 procedure Delete(const TweenIds:TStrArray);overload;

Note: The elements are released (free is called) and cannot be reused.

Execute

Once tween operations have been registered with TTween through Add(), calling Execute() initiates the internal update sequence – and the defined transformations begins.

Execute comes in 3 overloaded versions. You can prove a callback function that is executed when all tween operations are finished (this populates the OnFinished event).

 procedure Execute(const Finished:TProcedureRef);overload;
 procedure Execute;overload;
 procedure Execute(const TweenObjects:Array of TTweenElement);overload;

If you have pre-created TTweenElements you can pass them as parameters for execution without registering them first (without calling Add() ).

  // Execute all registered tweens
  FTween.Execute();

  // Provide a callback event
  FTween.Execute( procedure (sender:TObject)
    begin
      showmessage("Tweening finished!");
    end);

  // Execute with array of TW3TweenElements
  FTween.Execute( [LFirst, LSecond, LThird]);

Resume

TTween allows you to pause selected tween operations while you let other run their course. This is in some ways against the concept of tweening because it violates the timeline, which is an essential part of tweening. However there are rare cases where you may want some transformations to linger.

Calling Resume() marks a tween element as active again, which means it will be processed by the update sequence. Several overloaded variations exists, these are:


procedure Resume(const index:Integer);overload;
 procedure Resume(const Tween:TTweenElement);overload;
 procedure Resume(const Objs:Array of TTweenElement);overload;
 procedure Resume(const Ids:Array of String);overload;
 procedure Resume;overload;

Note: When you resume a tween operation, the timecode is reset. To avoid this, simply edit the TTweenElement properties manually before resuming.

Pause

TTween allows you to pause selected tween operations while you let other run their course. This is in many ways against the concept of tweening because it violates the timeline, which is an essential part of tweening.

But, since tweening is more often used in graphical effects rather than complex mathematical applications – being able to pause a transformation have some practical uses. Several overloaded variations exists, matching the Resume() functionality:

 procedure Pause(const Index:Integer);overload;
 procedure Pause(const Tween:TTweenElement);overload;
 procedure Pause(const Objs:Array of TTweenElement);overload;
 procedure Pause(const Ids:Array of String);overload;
 procedure Pause;overload;

For more information, please see documentation on Resume()

ObjectOf 

All registered TTweenElements can be retrieved either by index or id. The function ObjectOf() takes one parameter, the string ID for the tween element, and quickly returns the object.

TTween uses an internal lookup-table to ensure maximum speed and efficiency for this operation. ObjectOf() is used throughout the architecture and faster access means more responsive end results.

IndexOf

Much like ObjectOf() quickly locates a named tween element, IndexOf() locates the actual index of the tween-object. This can be used with the Item[] property to retrieve the TTweenElement instance.

IndexOf() takes a string identifier (id) as it’s only parameter.

TimeCode

Timecode() returns the current time identifier used by TTween to measure how time elapses and subsequently – how it moves through the established timeline.

Note: Internally this is obtained from JavaScript own Date.now() method, this returns the number of milliseconds since January 1, 1970 @ 00:00:00.

SyncRefresh property

Boolean property: If you are tweening values used by graphics you can ensure that the internal update sequence uses the RequestAnimationFrame JavaScript API when issuing the OnUpdated event. Setting this value to False (default) instructs TTween to use a normal timer to manage the transformations.

IgnoreOscillate property

Boolean property: Tween elements can be executed in 3 modes: single, repeating or oscillating. If you have multiple tweens executing and one of them is set to either repeat or oscillate, this means the TTween instance will never stop.

By setting the IgnoreOscillate property to True, TTween will only wait for non repeating or oscillating transformations, and once all tween elements are done it will invoke the OnFinished event. In other words, it will ignore transformations that will never end.

Note: When this property is set, the OnPartialFinish event will be invoked first.

Interval property

Integer property: The interval value determines the update frequency for the transformations in the collection. This value represents milliseconds (1000 equals one second). By default this is set to 10.

Note: When using SyncRefresh this value has no meaning since the RequestAnimationFrame API will synchronize the interval with the display frequency.

Easing types

Enum property: Each TTweenElement object can have its own easing type (read: animation type). The easing represents the formula which is applied on the value, performing the transformation. TTweenElement supports the following formulas, each yielding different behavior:

 TTweenEasingType = (
   ttlinear,
   ttQuadIn,
   ttQuadOut,
   ttQuadInOut,
   ttCubeIn,
   ttCubeOut,
   ttCubeInOut,
   ttQuartIn,
   ttQuartOut,
   ttQuartInOut,
   ttQuintIn,
   ttQuintOut,
   ttQuintInOut,
   ttSineIn,
   ttSineOut,
   ttSineInOut,
   ttExpoIn,
   ttExpoOut,
   ttExpoInOut
 );

Note: Under Apple iOS when navigating between forms (form sliding to either side while the new form slides into view), the acceleration starts slowly, picks up speed, and then slows down towards the end. This is ttQuadInOut. All options ending with “InOut” applies the effect both on the start and the ending of the transformation.

Behavior type

TTweenBehavior property: TTweenElement exposes a property named Behavior. As of writing tween transformations can be executed in 3 different ways:

 TTweenBehavior = (
   tbSingle,
   tbRepeat,
   tbOscillate
 );

These represents the following behavior:

  • tbSingle: Transformation is executed once
  • tbRepeat: Transformation is executed repeatedly
  • tbOscillate: Transformation is executed continuously forward and then in reverse

Note: Repeat and oscillate will cause those TTweenElements to never really finish. You must either manually stop them, or set the IgnoreOscillate property of the TTween object so the internal timeline excludes them from completion checking. See IgnoreOscillate property documentation for more information.