| Register
Friday, May 09, 2008   
You are here :     Article

Injecting TextScript

Created By  Satori Canton, at  3/7/2006 - 39 comments.

Satori has been an internet consultant since 1994. He is an Adobe Flex Champion, specializing in Rich Internet Applications (RIAs) using Flash, Flex and AIR.

Click to view this author's website.

Update 3/12/2006: This article is now available in Italian.

In my previous article showing how to create dynamic text effects with TextScript, I mentioned that there are only a handful of text effects built into the class, because you could essentially use the class to build any effect that you want. Now were going to take a deeper look at what the class is actually doing and how you can inject your own effect scripts into the TextScript class.

If you haven't seen the previous article, you may want to take a look over it. The two basic types of TextScript effects (constructive effects and deconstructive effects) are explained in that article and are going to be important here.

Also, I'm going to be referring to three sample files in this article, which you cand download here.

In a TextScript effect, think of each letter in the animated text as a sprite (an individual element that has a specific behavior). To create a TextScript effect, you don't have to code for the whole phrase, you just have to code what the single individual sprite is going to do.

Six things to know about TextScript sprites:

  • The sprite is a single letter in an animated text effect
  • The sprite is a movieclip so it has all of the functionality of a movieclip
  • The sprite has a property called frameCount which is set to 0 when a new effect is applied to it
  • The sprite has a property called delay that represents the number of frames the sprite should wait before executing its animation script.
  • Effect scripts are applied to the sprite's onEnterFrame event. Overwriting the sprite's onEnterFrame event will overwrite the effect behavior.
  • In constructive effects (effects that bring the text onto the stage), all sprites start out in their final position and scale so that you can store these values before beginning an animation.

Constructive Effects

As I wrote in my previous TextScript article, constructive effects are effects that build the phrase on the stage. Constructive effects always return an instance of a movieclip that is the container holding all of the letter sprites. We can then use this returned movieclip as a parameter in a deconstructive effect to remove the phrase from the stage.

The injectable constructive method in TextScript is called "createEffect". Its parameters are similar to the built-in constructive functions, with the addition of one more parameter on the end (which the custom effect function).

These parameters are:

TextScript.createEffect(
     scope:MovieClip, 
     phrase:String, 
     x:Number, 
     y:Number, 
     textFormat:TextFormat, 
     delay: Number, 
     customEffect:Function);

A simple typewriter effect:

One of the simplest effects to create is a typewriter effect (or an effect where the letters suddenly appear at normal scale and full alpha in order). To create this kind of effect, we'll build an effect function that TextScript will apply to all of the letter sprites.

So, in the typewriter effect (see sample 1), the typeOn function is applied to the sprite's onEnterFrame event. The second line is the most important line here.

if(this.frameCount++ > this.delay) - This line increments the frame counter and if the frame counter exceeds the delay property that the TextScript class set for the sprite, then the sprite knows that it's time to rock and roll! In this simple example, it rocks and rolls by making itself visible and clearing out the onEnterFrame event.

Not terribly impressive, but with just a few lines of code, it's pretty simple. It's certainly nothing to be scared of. So, let's try one that has a little bit more animation in it.

Rotate In effect:

This one is going to use our same frame counter to check if it's time for the sprite to do its thing. Once the frame counter exceeds the delay value, the sprite will rotate itself 180 degrees, make itself visible, then overwrite the onEnterFrame event to animate itself rotating back into position (see sample 2). Here's the code:

Deconstructive effects

Deconstructive effects are animations that remove the letter sprites from the stage. The method to inject a deconstructive effect is called "removeEffect". As parameters, this method requires a movieclip (the one generated from the constructive effect), the delay (number of frames between sprites becoming active) and the custom effect function. As in:

TextScript.removeEffect(m:MovieClip, delay:Number, effect:Function);

One more thing to know about TextScript sprites:

  • The sprite has a special method called remove. This should be used instead of removeMovieClip to remove the sprite from the stage. This will allow the parent movieclip to collect garbage and clean up after itself when all the sprites are gone.

Fade Out effect

Writing a deconstructive effect is pretty much the same as writing constructive effects. When a deconstructive effect is applied, all of the sprites automatically have their frameCounter properties set to 0. So we can start with our same code (second line of code) to detect when it's time to animate:

This effect waits until the frameCounter exceeds the delay value, then overwrites its own onEnterFrame event to decrease the alpha every frame until it's invisible. Then the sprite calls its remove method to remove itself from memory (see sample 3).

Two secrets about sprites:

  • All sprites have an array called characterArray that represents all of the sprites in the entire phrase. This array is it's own instance and can be manipulated (items removed) without affecting the parent container's characterArray.
  • As implied in the bullet above, the parent movieclip that holds all of the letter sprites has an array (also called characterArray). By committing the sin of this._parent.characterArray, the sprite can find out a lot about the current state of the animation (such as if it's the last man standing, or the first character in a phrase). Although a total hack, the this._parent.characterArray is useful data when creating custom effects.

Beyond the Basics

When creating text effects with TextScript, remember that you have all of the power of Flash movieclips. You can change the text's color, apply filters and blend modes, recreate complex physics, and don't forget about things like sound or other media. The class is written to be simple to use, but completely flexible to inject custom effects. With a little creativity and experimentation, you should be able to come up with some very interesting effects.

Check out the transition functions that are included in the TextScript class (beginning on line 108 of the class). These are the built-in functions that are injected into the createEffect and removeEffect TextScript methods.

If you come up with anything cool, please share it in the comments.

Need Professional Help For Your ActionScript Project?
ActionScript.com Consulting Services provide top quality professional ActionScript consulting to businesses around the globe. If you have a professional project in need to world-class talent, tell us about your project by requesting a quote today.

Reader Comments

  1. Marcelo de Moraes Serpa  Replied:
    ( 3/7/2006 At 2:25 PM)

    Very good... thanks for the excellent article! :)

  2. Tiana Kassin  Replied:
    ( 3/8/2006 At 4:00 AM)

    Here's the first one I came up with. Not wonderful, but I like it. Thanks for the class. I'm having a lot of fun experimenting with it! 

    sideStep = function() {
  if(this.frameCount++ > this.delay) {
    this.pos = this._x;
    if(Math.floor(Math.random()*2) == 0) {
      this._x = Stage.width;
    } else {
      this._x = -this._width;
    }
    this._visible = true;
    this.onEnterFrame=function() {
      this._x = this._x + (this.pos - this._x) / 5;
    }
  }
}
m = TextScript.createEffect(this, "Hello World!", 50, 20, tf, 2, sideStep);

  3. V PALANIAPPAN  Replied:
    ( 3/8/2006 At 9:43 AM)

    just i'm enter in action script. this time its very help ful.

    my thanks for all

  4. Gabriel Belvedere  Replied:
    ( 3/11/2006 At 7:40 PM)

    Satori, thanks for this great class. I added to my Key Me! game at inbyted.com.
    Thank you very much for sharing your work.

  5. Satori Canton  Replied:
    ( 3/11/2006 At 9:55 PM)

    Hi Gabriel,

    That's awesome. Love the game too!

  6. zahid nawaz  Replied:
    ( 4/4/2006 At 11:38 PM)

    Hi everybody,
    These effects are really very nice but i think have a problme. I have tried with different fonts but its not working with other fonts. Only with limited fonts it works. These effects are also not working with richtext like Italic, Underline, bold etc.

    Any body have idea y its like that and how to solve this problem.

    I am actully designing a coustomer tool where i want use these effects on the end user defined Text field. I want to show same effect to his text with his defined Text format.

    If any body have a solution then please post me. I am thankful to your help and attention.

    Best Regards
    Zahid

  7. Satori Canton  Replied:
    ( 4/5/2006 At 4:29 AM)

    zahid,

    To use this class, you need to embed the Bold or Italic version of the fonts in your FLA. If you don't embed them, you won't see any text characters at all. Not seeing any effect is the only sign you'll have that you haven't embedded the correct font in the FLA.

    Also, remember that bold and itallic fonts are different than only bold or only itallic fonts. If you use any of these, they need to be imbedded in the FLA individually.

  8. Kleus van den Belt  Replied:
    ( 4/7/2006 At 6:28 AM)

    "All submissions sent to this contest become the property of ActionScript, Inc. and may be published, used or otherwise distributed without limitation."

    That means you can basically take the whole bunch and start selling other peoples ideas later?

    Why do the entries become property of Actionscript, Inc? Don't you need copyright transfer for that?

  9. Satori Canton  Replied:
    ( 4/7/2006 At 3:09 PM)

    Regarding the contest, when submitting entries, they become the property of ActionScript so that we can publish the winners (and other entries) on the site after the contest is over.

    This is an open source project and the contest is just intended to be a fun way to make people aware of it. We're not asking people to create some massive application that we're going to turn around and sell. But we need permission to use the submissions so that we can republish them.

  10. German Cons Tapia  Replied:
    ( 4/10/2006 At 10:00 PM)

    I was wondering is there a way to add the effects to the original class, so you can use them with the randomEffect method?

    something like TextScript.addEffect("name", name) where name is a function with the new effect?

  11. Satori Canton  Replied:
    ( 4/11/2006 At 5:32 AM)

    There isn't currently an addEffect method, but that's a great freakin' idea! Something like putting a hash table together inside the script to list all prebuilt and added effects would be very useful.

    I'll give it some thought. I don't want to change the class during the contest, but this would definitely work its way into a future build of the class.

  12. Rajat Paharia  Replied:
    ( 4/14/2006 At 1:55 AM)

    Very cool class! Just a thought - for rotation effects it seems like it might be useful for the registration point of each sprite to be in the center of the letter so they could spin in place, rather than around the upper left corner.

    Now back to playing :)

  13. Satori Canton  Replied:
    ( 4/24/2006 At 10:02 AM)

    If you make a custom effect (see: http://www.actionscript.com/Article/tabid/54/ArticleID/Injecting-TextScript/Default.aspx) there are ways to tell when the effect is complete. By using the characterArray described at the end of this other article on the subject, you can detect if the character that is animating is actually the last character in the phrase, and then throw an event (probably out of scope this._parent style) when the animation is complete.

  14. Antonio Cortese  Replied:
    ( 4/26/2006 At 6:23 PM)

    Thanks for the tip, Satori! I noticed only now it was here in this article. I'm just now trying to make it work--will report back with results if I'm successful.

  15. Wael Saad  Replied:
    ( 5/2/2006 At 10:54 PM)

    Hi All, Satori well done, thanks for TextScript class I think its an excellent start for text effects in actionscripting, I really hope to see more text effects in cooperation with ZigoEngine + Fuse Kit v1.1 you can check it out at http://www.mosessupposes.com/Fuse/index.html.

    Also the reason for those people who couldn't get TextScript to work properlly with Flash 8 Components v2 is very simple. its a depth issue that macromedia commented on in their help.

    if you look up getNextHighestDepth, it will read...
    Note: If you are using version 2 components, do not use this method. If you place a version 2 component either on the Stage or in the Library, the getNextHighestDepth() method can sometimes return depth 1048676, which is outside the valid range. If you are using version 2 components, you should always use the version 2 components DepthManager class.

    so here is a quick fix for TextScript just to demonstrate that it can work with V2 Components...

    All you have to do is after the import TextScript line add _global._depth = 0;

    import TextFX;
    _global._depth = 0; <----

    and then in the class

    replace this line

    var teText:MovieClip = scope.createEmptyMovieClip("ascTextPhrase" + scope.getNextHighestDepth(), scope.getNextHighestDepth());

    with

    var teText:MovieClip = scope.createEmptyMovieClip("ascTextPhrase" + _global._depth, _global._depth++);


    And replace this line also:-

    var m:MovieClip = scope.createEmptyMovieClip("ascTextCharacter" + scope.getNextHighestDepth(), scope.getNextHighestDepth());

    with

    var m:MovieClip = scope.createEmptyMovieClip("ascTextCharacter" + _global._depth, _global._depth++);

    that's it, it will work.

    Kind Regards

    Wael

  16. Michael Risser  Replied:
    ( 7/18/2006 At 12:23 PM)

    Great class! I'm having a lot of fun with it, but I've hit a bit of a snag :(

    I'm pretty new to ActionScript, so please bear with me.

    What I have is, in Frame 1 is the code to do the blurIn(), but after a delay I need to do the removeBlurIn(). The problem is that its not working for me.

    The blurIn() works just fine, but when its time to move on to the next scene, removeBlurIn() doesn't work.

    I tried it in Frame 1 after the blurIn() and nothing happened at all. I also tried putting the deconstructor several frames later, the blurIn() worked, but removeBlurIn() didn't.

  17. Stumped  Replied:
    ( 8/13/2006 At 11:09 AM)

    Hi,

    I'm not sure of what the exact problem is.. I am very new to using flash, so please bear with me. I used the textscript class(multline) to create two fields on two separate pages for a website.

    http://thedmp.net
    http://thedmp.net/playlist.html


    They are both located in the bottom half of the page. When I view the website from my home computer, the page displays fine. However, when I view it on another computer, the page does not display correctly. Everything on the page displays correctly except for the new *.swf fields that make use of the textscript class. I don't think its a matter of me forgetting to embed the characters into the dynamic text field because then I would not be able to view the page correctly on my home computer. Can someone please shed some light on this problem??

    I also thought that there might be a version incompatibility with the flash version installed on the other computer, but surely there would be some type of error message, or prompt asking the user to upgrade??

    Thanks.

  18. amit aides  Replied:
    ( 9/6/2006 At 12:41 AM)

    Hello Satori,

    Great looking text effects.
    I would like to know if I can use the 'TextScript' class in a commercial product and on what terms.

    Regards,
    Amit

  19. Satori Canton  Replied:
    ( 9/6/2006 At 4:14 PM)

    You can use TextScript in commercial applications. Just provide attribution to the author.

  20. carlos nshimba  Replied:
    ( 10/9/2006 At 6:33 AM)

    Hey men, thanx for da wonderfull class!
    Although new to action script, i seem to have light!
    What i wanted to do is to diplay different phrases with different effects.
    Also this part:
    "onMouseUp = function() {
    TextScript.removeropIn(m, delay);
    }"
    How can i remove the effect without using the mouse events? I've been trying to use key frames for that, but it seem not work.

  21. kamal kannan  Replied:
    ( 10/13/2006 At 4:32 AM)

    hello sir,
    your text effect was very funtastics.
    I was Download TextScript.as,
    so doesen't run.
    I was create MovieClip in Dynamic text and select linkage option to As 2.0 class text box i entered TextScript.as.

    finally TextScript could not be loaded.

    com.actionscript.text.TextScript' needs to be defined in a file whose relative path is

    'com\actionscript\text\TextScript.as'.
    class com.actionscript.text.TextScript {
    The class 'flash.filters.BlurFilter' could not be loaded.
    this.filters = [new BlurFilter(0, Math.abs(this._velocity), 1)];

    The class 'flash.filters.BlurFilter' could not be loaded.
    this.filters = [new BlurFilter(0, Math.abs(this._velocity), 1)];

    The class 'flash.filters.BlurFilter' could not be loaded.
    this.filters = [new BlurFilter(0, Math.abs(this._velocity), 1)];

    The class 'flash.filters.BlurFilter' could not be loaded.
    this.filters = [new BlurFilter(0, Math.abs(this._velocity), 1)];

    Line 191: The class 'flash.filters.BlurFilter' could not be loaded.
    this.filters = [new BlurFilter(n, n, 1)];

    Line 206: The class 'flash.filters.BlurFilter' could not be loaded.
    this.filters = [new BlurFilter(n, n, 1)];

    The class 'com.actionscript.SatoriArray' could not be loaded.
    teText.characterArray = new SatoriArray();

  22. Dan B  Replied:
    ( 10/15/2006 At 2:26 PM)

    Satori - I love this class! It takes all the work out of creating some fantastic effects, and it makes flash fun again!

    But, unfortunately when I transport my script into another movie I'm seeing similar issues to those listed above.
    I get 6 "The class or interface could not be loaded" errors such as:

    Flash_classpath\com\actionscript\text\TextScript.as: Line 118: The class or interface 'flash.filters.BlurFilter' could not be loaded.

    I carefully went thru the steps outlined by Wael Saad thinking it was a Flash 8 Components v2 problem, but I continue to experience the issue.

    Any assistance is greatly appreciated! :)

    Thanks, Dan

  23. Ian Ossia  Replied:
    ( 10/29/2006 At 6:12 PM)

    Can anyone tell me why this script does not work with bitmap fonts with 'bitmap fonts' selected in the anti-alias box, even though the fonts are still embedded?

  24. Senthil Kumar K  Replied:
    ( 11/9/2006 At 12:35 AM)

    I am create a component using AS 2.0. While i am converting this component into a compiled clip, I am facing a major problem. (i.e) If i put a my compiled clip in a new document, all the movie clips are not in a new document so that i cannt work with this compiled clip. suppose i put particular missing movie clips in that document, it is working. Why is happend like that. Anybody knows pls tell me..

  25. Ben Bartholomew  Replied:
    ( 11/16/2006 At 5:10 PM)

    From a design standpoint, it would be nice if you had control of the Kerning of the font. I'm guessing the class decides the space between the letters based on the font size? An example you have on the site shows the letters running into each other (because it’s a wide font). When experimenting on my own there was too much space between the letters. Has anyone else brought this up?

  26. Satori Canton  Replied:
    ( 11/16/2006 At 7:15 PM)

    Yeah, kerning and line spacing (actually even being able to easily create multi-line effects) are sorely needed in the class.

    I actually created a new version of TextScript that supports all of this. I'll check with the client that I created it for. We talked about releasing it to the community, but I need to be sure there are no objections on their part before putting source code out there.

  27. Jamin Hall  Replied:
    ( 11/21/2006 At 6:54 PM)

    I've been looking at this code trying to figure out how to run effects on a limited piece of a string. For instance if I have a string "Hello World!" and I only want the characters from index 2 to 5 to have a blur out effect how can I do that?

    I tried altering parts of the TextScript code to allow for this, but got a little stuck.

    Any tips?

  28. Satori Canton  Replied:
    ( 11/22/2006 At 5:51 PM)

    Jamin,

    You'd have to use the location of the letter in the character array (see "Two secrets about sprites" above) to detect if an effect should do one thing or another based on it's position in the array.

    It's complicated, and it's kind of a hack, but the character array is provided to allow exactly that kind of hack.

  29. Chris Ivens  Replied:
    ( 1/30/2007 At 10:36 AM)

    I have a slight problem which is baffling me at the moment.
    I'd like the ability to align the text either left, right or centred and to do this I tweaked the createText() function. It's a bit of a hack but in theory it should work.

    I added this code just below the for loop where the characters are created and aligned:

    var c:Number = teText._width;
    for(var d:Number = 0; d < l; d++) {
    switch(format.align) {
    case "left" :
    //do nothing
    break;
    case "right" :
    teText.characterArray[d]._x -= c;
    break;
    case "center" :
    teText.characterArray[d]._x -= c/2;
    break;
    }
    }

    What I was expecting was for each character to shift to the left by a constant amount thus keeping all kerning correct. The issue is, the spaces between words simply disappear. From what I gather of the code, the spaces are rendered as movie clips just the same as a normal character. Why would I be losing the spaces I wonder.

    Any ideas?

  30. walter merida  Replied:
    ( 4/16/2007 At 7:08 PM)

    Hello,

    Thanks for the fantastic TextEffects. They work great!

    I have what is probably a simple/newby question:
    How can I use these effects as the "opening" scene in a sequence? I first added a stop condition to run the script only once through the phrase sequence:

    onEnterFrame = function() {
    if(frameCount++ % 150 == 0 && dummy < phrases.length) {
    triggerChange();

    (dummy is just a counter). I then tried to add more frames or scenes but I cannot make the script run and THEN go to the next frame or scne. The only solution seems to be adding more frames in the TextSffects scene (enough to last until the script runs once so taht it can then go the the next scene). I realise that this is probably covered in "Controlling timelines 101" but I am relatively new to Flash and do not know how to control movie_clip timing. Any help will be greatly appreciated.

  31. Boris Desgeyl  Replied:
    ( 6/25/2007 At 11:45 AM)

    Thank you Satori, great work and very very useful. You wrote, that you perhaps could release a new version of TextScript that supports kerning, line spacing and multiple lines. Did you do that or was your client unfortunately against it?. Thanks again.

  32. Satori Canton  Replied:
    ( 6/26/2007 At 9:55 PM)

    Hey Boris,

    I've been working on TextScript 3.0 this week and hope to release it in the next week or two. This version will be written in ActionScript 3.0, so it will work in Flash CS3 and Flex2. It also supports multi-line effects, kerning, line spacing, etc. It should be a big step forward. Stay tuned and I'll have it up on the site shortly.

    Satori

  33. Roland Sproll  Replied:
    ( 6/30/2007 At 6:58 PM)

    hi satori

    great scripting, thank you. it's indeed one year old, but for me it's up to date, cause i was looking for exactly that last week. i made an adaption, perhaps you or anybody else is interested in. i changed the time behaviour and used mosessupposes fuse kit to make this job. advantages are, now it's independent from the movie frame rate, you can use the predefined easing functions and you have a callback. disadvantages are the file size and there is no as3 version of the fuse kit up to now (but it's announced :-).

    thanks.

  34. Benson  Replied:
    ( 7/3/2007 At 5:01 PM)

    Hi,
    I have try it, It's very great script for me. But I have a question.
    When I use the multi-language for this script such as Chinese. It will be come a large file (the .swf file). Do you know how to make smaller files for the multi-language.

    Thanks.

  35. Jamin Hall  Replied:
    ( 7/5/2007 At 5:02 PM)

    Will TextScript 3.0 work with CS3's new Animator class? This is very exciting. Thanks Satori!

  36. Sumiti Thakral  Replied:
    ( 8/5/2007 At 6:55 AM)

    Hi!
    It's a great script.
    I have a question.
    I m accessing the flash swf file in vb 6.0. I want the text effect to be selected by the user. I have used fscommand to enable communication between ActionScript and VB 6.0 (Visual Basic), but unable to use the appropriate decision making in ActionScript. Pls. advise.

  37. Eric Thomas  Replied:
    ( 8/6/2007 At 5:08 PM)

    Hi. I have a weird error. I created a flash swf and used the text script and had everything running perfectly. As soon as I tried loading that swf into my base swf, the kerning gets all screwed up and jumbled. The font is there, its just as if the spacing is lost.

    I found it strange that it works great by itself, but as soon as its loaded into another swf it acts up. any suggestions on how to combat this? I have an anxious client! thanks so much for the great work.

  38. steve mccrumb  Replied:
    ( 10/28/2007 At 7:12 AM)

    hello everyone,
    i have been following the posts for a little while and i was curious if anyone had found a good solution for multiple lines of text. there were a couple posts about the topic but i havent seen anything since (also the accompanying links to the posts didn't work). I saw also Satori said that he had created a multi-line version but he had to get approval from his clients to release it. anyone heard anything else about that? thanks for the great answers in the past.

  39. Fred Layberger  Replied:
    ( 11/26/2007 At 4:01 PM)

    What is the status of TextScript 3.0? The current version of TextScript generates lots of errors when use with Actionscript3/Flash CS3. Thanks...

Login to post your comments. If you do not have an account with us please Register.
Copyright 2005 by ActionScript, Inc.   |  Privacy Statement  |  Terms Of Use  |  ActionScript Client Extranet