B4A Library [Library] Universal Tween Engine - Animate your views

tween-engine-big-logo.jpg

Picture copyright Aurelien Ribon​

The Universal Tween Engine allows you to create smooth interpolations on every attribute from every object in your project !

I would like to thank the author of the official version, Aurelien Ribon, a lot for helping me porting the project.

You can take a look at an example here:
Universal Tween Engine demo

or Android Application:
https://play.google.com/store/apps/details?id=aurelienribon.tweenengine.demo

And amazing sample made with b4a?
Check out post 6 by Sorex!

I ported almost all functions from this engine to Basic4Android.
So you can make simple tweens with callbacks to powerful animation sequences.

Examples to make with this library:
- Games: Imagine Jewelquest where the sprites have to move from the game (with an elastic animation, bounce, etc)
- Livewallpaper: imagine what you can do ;)
- Menu's
- Intro's
- And a lot more!

I will try to explain this library as good as possible.
There are 6 classes available to use in the TweenEngine:

B4X:
Dim Tween As Tween
Dim Manager As TweenManager
Dim Constants As TweenConstants
Dim Callback As TweenCallback
Dim Path1 As TweenPath
Dim TimeLine As TweenTimeline

A Tween is an animation of an object, view, ...
Currently you can animate a Label, ImageView and Panel. (Due B4A uses wrappers for the views, we needed to create seperate methods for every view. We also couldn't cast from an Object to a viewwrapper.) But don't worry! You can still add your view to animate to a panel and tween the panel.

Let's go over a sample of animating a view.

B4X:
'Load Activity stuff
Activity.LoadLayout("Main.bal")
Activity.AddMenuItem("Start Tween", "mnuTween")

'Initialize the TweenManager
Manager.Initialize
   
'Initialize the tween
Tween1.Initialize("Tween")

'A callback is used when you want to monitor a tween like tween completion, etc
Callback.Initialize("TweenCallback")

'We will use a timer to update our animation.
'Normally, we should use a thread to remain maximum fps.
tmrUpdate.Initialize("TweenUpdate", 10)
   

'Next, we register a Tween Accessor if the object you will use is a panel.
'If the tween you will use is an imageview, you'll use registerImageAccessor, etc
Tween1.registerPanelAccessor

'Let's create our tween.
'First we need to call one of the 4 'initializers'. These will construct your tweens otherwise you'll receive a nullpointer.
'These are: - To, From, Set and Call - they are explained in the methods in the IDE.
'Our first parameter is the object/view we will add.
'Second param is a tweenConstants. These are X, Y or XY
'Last parameter is our duration in secs or ms.
'This is the unit you want, the engine doesn't care  
'However, if you choose seconds for instance, you need to use the same unit in every call to the engine. 
'That means that the deltas in the manager.update() method will need to be in seconds too. 
'As long as you use the same unit everywhere, you can use the unit you want.
Tween1.PanelTo(pnlTween, Constants.POSITION_XY, 30)

'Then we set the target's x and y position to go to.
Tween1.setTarget(105,200)

'Next we create an ease from the constants. A dozen are available to use.
Tween1.Ease(Constants.ELASTIC_IN)

'Sets a listener before you set the callback!
Callback.Listener = True

'A callback is used when you can to know what happened with the Tween. OnEvent is called with the TweenCallback eventname you initialized before
Tween1.Callback = Callback.TweenCallback
   
'Adds the tween to the TweenManager.
'Calling TweenManager.start will start all tweens associated with it.
Manager.addTween(Tween1(0).Tween)
Manager.addTween(Tween1(1).Tween)

Sub mnuTween_Click

   'Starts the tween and enables the timer.
   Manager.StartTween
   tmrUpdate.Enabled = True
   
End Sub

Sub TweenUpdate_Tick
   'Updates the tween.
   Manager.Update(0.1)

End Sub

Sub TweenCallback_OnEvent (Event As Int)
   Log("Event: " & Event)

End Sub

A lot of other methods are available to the tweens like resuming, pausing, getting information, repeating, delays, waypoints, etc.

A sample for TweenTimelines isn't available yet, but you can find more information here:
java-universal-tween-engine - The Universal Tween Engine allows you to create smooth interpolations on every attribute from every object in your project ! - Google Project Hosting

TweenConstants are the constants used for the Tweens.
All constants (except 3 Position_x, y and xy) are used for the easing of the tween.

TweenPath isn't really tested.
It has 1 method:

B4X:
/**
         * Computes the next value of the interpolation, based on its waypoints and
         * the current progress.
         *
         * @param t The progress of the interpolation, between 0 and 1. May be out
         * of these bounds if the easing equation involves some kind of rebounds.
         * @param points The waypoints of the tween, from start to target values.
         * @param pointsCnt The number of valid points in the array.
         * @return The next value of the interpolation.
         */

TweenCallback is the callback from your methods. OnEvent is called with the event as an int.
You can use this to start new tweens, or to open an activity when a tween ended.

It would also be great if people could make nice examples to share with other users. The intro of the Android app is available on the universal Tween Engine google code: / - java-universal-tween-engine - The Universal Tween Engine allows you to create smooth interpolations on every attribute from every object in your project ! - Google Project Hosting

As last: the credits.
The Universal Tween Engine is licensed under Apache License 2.0.
This means you'll have to credit the author(Aurelien Ribon) and a link to their website (Aurelien Ribon's Dev Blog)
Users are free to use the lib in any projects, commercial or not. If you distribute a modified version of the library, you need to retain the original attribution.
In every licensed file, any attribution notices in redistributed code must be preserved; and, in every licensed file changed, a notification must be added stating that changes have been made to that file.

Javadocs are available here:

Universal Tween Engine API

If you don't know what a function does, or arguments, visit that link!
The javadocs are extremely good documented and if you would like a new feature from the Javadocs, reply on this topic. Do not pm me about this.

I would also like to thank Sorex for beta testing and the usual bunch on the chat: tds, NJDude, HotShoe, Barx.
(feel free to join us and talk about b4a! We are there 24/7 :p
Basic4Android Chat

In the attachments, you can find the usual stuff. A sample, lib files and readme

If you have any questions, please ask them in this topic.

Have fun!
Tomas


Note 1. It is best to associate all tweens with a manager instead of calling them manually.

Note 2. You can not call methods like to(...).delay(...).repeat(...).start becaus e Basic4Android handles only known types.

note 3. You can also declare an array of tweens like:
B4X:
dim tween(2) as Tween
tween(0).do
tween(1).do

note 4. If you receive some kind of error: "No TweenAccessor found or to this object." means that your accessor is incorrect. Probably, you will have called the wrong Accessor (registerPanelAccessor, etc) to the wrong type (e.g imageview)
 

Attachments

  • TweenEngine.zip
    120.4 KB · Views: 955
  • TweenEngine1.1.zip
    121 KB · Views: 1,824
Last edited:

Omar

Member
Licensed User
Longtime User
Thanks!

Hey Tomas,

Thanks so much for this great library, I'm sure this will be extremely useful for many of us and really grateful for all your contributions to the community. :sign0098:
 

sorex

Expert
Licensed User
Longtime User
Hello,

As promised to xVerhelstx I wrote a small example file.

I created an extra sub routine which allowed me to set up tween with 1 line of code.

Due to the lack of parameter tweening in the library compared to what we have in Flash I coded a small work around which allows you to scale objects based on the tween equations.

It should be enought to get you started.

the animation sequence you see on your phone might look odd but I only have an i5800 here with 400x240 resolution or something and didn't want to test it with our beloved *cough* emulator.

oh that sequence only needed 13 lines of code :)
 

Attachments

  • TweeningExample.zip
    59.3 KB · Views: 697

sorex

Expert
Licensed User
Longtime User
no, those are for the scaling/resizing workaround.

it are the hidden1 & hidden2 views and tweens.

they tween from 0-100 then I know how much percentage the scaling should be :)

you can place them at top=-100 or something.
 

sorex

Expert
Licensed User
Longtime User
ok, it seems that my sub confuses some people so I'll explain it here.

Sub Tween(v,c,obj As Object ,tweentype,x,y,t,e As Object,d)

v : the object type of the to-be-tweened object (can currently only be panel, label or image)
c : the id/counter in the tweening array
obj : the object name as seen in the designer
tweentype : can actually be removed since it should always be position_xy with this sub setup
x : target/new x-pos
y : target/new y-pos
t : time/duration which seems to be in tenth's of seconds so 10 is 1 second
e : easing/tweentype : the tweening type as found in the constants (type constants. and select)
d : delay before the tween starts

notice that the sub is just a quick thrown together thing to declare tween easier and in 1 command, but as I'm just a B4A noob it could be more elegant ;)

some ideas that could be added to improve performance is

- enable items when they get tweened
- custom actions in the timer ticker can be enabled/disabled with an if (obj=visible) do modifications to object. otherwise it will resize the object all the time even when not visible.
 

NJDude

Expert
Licensed User
Longtime User
AWESOME LIBRARY!!!

Note that the positioning values should be in DIP

x : target/new x-pos (in dip)
y : target/new y-pos (in dip)

E.g:
B4X:
Tween("image", 10, imageCube, Constants.POSITION_XY, 120dip, 20dip, 0, Constants.BOUNCE_INOUT, 20)
 

AurelienRibon

Member
Licensed User
Longtime User
Hello B4A users :)

Big thanks to Tomas for porting the library to you.
Just a note to give you some info. The Tween Engine is called "Universal" because it lets you animate every attribute of every object, using any framework.

To provide such support, the engine asks you to provide a "TweenAccessor" for each class of object you want to animate. In this accessor, you define every attribute you want to animate: position, rotation, opacity, color, scale, skew, higgsboson... anything is possible, you just need to let the engine know how to animate it (ie. how to get and set the related attributes). Have a look at the official "GetStarted" tutorial to get a better view of the engine aim [1].

In the port provided by Tomas, he built the accessors in the wrapper. This wrapper only seems to support the animation of object positions. I don't have access to the port source code, since I'm not a B4A user, so I can't really help you on the implementation, but you may be able to add support for any other attributes by looking into the built-in accessors.

[1] code.google.com/p/java-universal-tween-engine/wiki/GetStarted
 

walterf25

Expert
Licensed User
Longtime User
Tween Library

XverhelstX, thanks for this library again, i have been playing around with it and see if i can use it in a live wallpaper app, so far i haven't had any success, one question though, i noticed that you can only use either a panel, an imageview or a label, is there way to use a rect, a button, or anyother view, i know this can be done with the original library written in Java!

Has anyone else made any examples with this library, preferably live wallpapers?

thanks,
Walter
 

XverhelstX

Well-Known Member
Licensed User
Longtime User
Hey walter,

I had a lot of trouble accessing the right accessor.
I mostly ended up with "No TeenAccessor found."
This is due the way Basic4Android handles the views. It uses Wrappers for most views, and this is why i need to use ImageViewWrappers, and other wrappers instead of normal ImageViews, etc.

Also using an Object as a parameter lead me to the same error.
And the only way to do this is to create a new Accessor class for every wrapper.
I'm not sure about rect, and non-related views though.

Tomas
 

walterf25

Expert
Licensed User
Longtime User
Tween Library

Well, i have this live wallpaper with a golfcourse gif file animated set as the background, and when the user taps anywhere on the screen a golfball starts flying from a far distance and it starts getting closer, and when it hits the screen i set it to give a broken screen effect, (the ball hitting the screen), but i wanted to see if i could use your library to give the ball movement a little more realistic effect, if you could add some more accessors that would really help us a lot.

Thanks, and great Job!
Walter
 

NJDude

Expert
Licensed User
Longtime User
The attached project contains a simple animation using the Universal Tween Engine.

The code is based on Sorex's code, I also borrowed some hints from XverhelstX tutorial.

NOTE: I have improved the code, now you can animate all views (except ProgressBar and SeekBar).

For example:
B4X:
'To animate a Button:
AnimateTween("Button", 2, Button1, Constants.POSITION_XY, 100dip, 20dip, .5, Constants.ELASTIC_INOUT, 5)

'To animate a ListView:
AnimateTween("ListView", 3, ListView1, Constants.POSITION_XY, 30dip, 5dip, .5, Constants.ELASTIC_INOUT, 10)

Update: July 25, 2012

The new code version 2.0 includes the following routines:

  • AnimateTween
  • RotateTween
  • FadeTween
  • ScaleTween
  • ResetTween

Notes:
  • I recommend you compile using SDK level 16, this code will run on systems running Honeycomb and up (SDK level 11 as indicated on THIS post).
  • This library also works in Android 2.x AS LONG AS you DO NOT use rotation, scale or fade, however, you can create workarounds like THIS for example.

Enjoy.
 

Attachments

  • TweenAnimationSample2.0.zip
    48 KB · Views: 481
Last edited:
Top