Tweens & Jugglers unleashed

You think you know all about Sparrow’s animation system after the last two parts of this series? But we have merely scratched the surface! Get ready for the last part of the series to find uses of the juggler you have probably never thought of!

Tween events

First, we’ll discuss a fact that we have shamefully ignored in the last two articles: tweens dispatch events. Three types of events, to be exact:

SP_EVENT_TYPE_TWEEN_STARTED

SP_EVENT_TYPE_TWEEN_UPDATED

SP_EVENT_TYPE_TWEEN_COMPLETED

The best way to understand those events should be an example. So, back to Ruth Lezz and her blast door!

When you add that code to your project and run it, the output will be similar to this:

The door starts to move now.
The door is moving.
The door is moving.
The door is moving.
...
The door is moving.
The door is moving.
The door is now closed.

As you can see, the START- and END-events are the first and the last events of the tween, respectively. The UPDATE-event, however, is dispatched every time the tween is advanced (in other words: once per frame).

You can use these events to trigger some action in certain stages of a tween’s life cycle. This can come in handy in a lot of situations.

For most tasks, however, you can use simpler techniques than events. I’ll prove that in the following sections.

Chaining Tweens

A common task is having two or more tweens to be executed one after the other.

Let’s say you want to move the door down and then up again. To achieve this, you could first create a tween that moves the door down, then add an event listener that fires when the door arrives at the bottom, and finally create the upward moving tween in this event listener. But, frankly, that’s a lot of code to write for such a simple thing, isn’t it? Well, the ‘delay’-property comes to the rescue! Look at this:

Think of it like this: ‘delayInvocationAtTarget:byTime:’ returns a future version of the text field (perhaps it uses a Flux Capacitor™, but who knows?). And everything that you do to this text field will only happen 2 seconds from now.

[A short warning though: you cannot use ‘release’, ‘copy’ and other methods of Objective C’s NSObject base class - but that’s rarely a problem.]

Let’s use a real-life example to show the power of this method. We want to display a countdown - a text field that counts: “3 - 2 - 1 - Go!”. With the juggler’s delayed calls, you can do that easily!

// create a text field with the text "3"SPTextField*textField=[SPTextFieldtextFieldWithText:@"3"];[selfaddChild:textField];// now start the countdown![[jugglerdelayInvocationAtTarget:textFieldbyTime:1.0]setText:@"2"];[[jugglerdelayInvocationAtTarget:textFieldbyTime:2.0]setText:@"1"];[[jugglerdelayInvocationAtTarget:textFieldbyTime:3.0]setText:@"Go!"];// and get rid of it later.[[jugglerdelayInvocationAtTarget:textFieldbyTime:4.0]removeFromParent];

Note that we remove the text field from the screen at the end - which makes this countdown-method completely self contained (there’s no need to save that object in a member variable just to remove it from the screen later).

Animate Everything!?

You already know that you can use a tween to animate every numerical property of an object (integer, float, double). This allows us to do a lot of animations: movement, fading, scaling, rotation, etc.

But this fact can be interpreted in a different way, too: As soon as you can describe something with a number, you will be able to animate it.

Again, here’s an example. Many games contain a score display - a text field that shows the player his current score. When the player achieves something, you raise the score, probably like this:

mScore+=100;// mScore is a member variable (int)scoreTextField.text=[NSStringstringWithFormat:@"%d",mScore];

Now the score changes immediately from, say, 400 to 500. But wouldn’t it be nice if it displayed the intermediate values, too? Quickly rising from 400 to 401, 402, 403, etc., until it reaches 500?

To do that, we create a subclass of SPTextField, that adds - a numerical property! Remember, any numerical property can be animated. So we better create one!

Voilà, we’ve just created the ‘NumberField’ class. It’s no more than a text field than has a special property for displaying numbers. With that class in our tool belt, we can animate the score as we wish:

[Disclaimer: use the ‘alloc/init’ approach to create instances of the NumberField class. If you want to use the ‘textFieldWith…‘-methods, you have to overwrite them in the NumberField class.]

Conclusion

I hope that you find one or another of these techniques useful for your projects! If you’ve read through all three articles of this series, you are on the best way to become a master Sparrow animator. :-)