A Speech object represents a speech balloon on the screen. It displays text letter by letter when you tell it to say something, and becomes invisible when nothing is being said. To create a Speech object, just use the Speech() constructor function.
The first parameter is a reference to a TextField object on the stage. The TextField object can either be directly on the stage, or it can be inside a DisplayObjectContainer. The DisplayObjectContainer is usually a MovieClip, but it can be other things, like a Sprite or even the Stage.
The second parameter is a Boolean value. If this parameter is true, the Speech class assumes that the object containing the TextField is a part of the speech balloon. The containing object will become invisible when the Speech object is inactive. By default, this value is true, because a TextField alone is not usually very interesting.
//Assume this TextField object already exists on the stage.
var txt:TextField;
var speech:Speech = new Speech(txt);
When creating the Speech object, the TextField will become invisible. If the second parameter was set to true, the parent of the TextField will also become invisible.
You can make a Speech object say something by calling the say() function. This function has two parameters. The first one indicates what to say. The second one indicates how many frames should pass after all the letters have finished displaying.
The default value of the second parameter is -1. If you use -1 as the value of the second parameter, the program will add 20 to the number of characters in the text to display and use the result as the timer value. Here are some examples:
var speech:Speech = new Speech(txt);
//Writes "HELLO!!", then waits 10 frames
speech.say("HELLO!!", 10);
//Writes "Testing...", then waits ("Testing...".length+20) frames
//"Testing...".length = 10 --> Wait for 10+20=30 frames
speech.say("Testing...");
You can stop the speech balloon from writing text at any moment using clearSpeech(). This function not only stops it from writing, but also empties the speech balloon and makes it inviaible.
When you call the say() function, the first thing that happens is that the TextField becomes visible.
Then, frame by frame, the TextField will fill in with a few letters at a time. To control how many letters are written in each frame, you can use the textSpeed property of the Speech object.
var speech:Speech = new Speech(txt,true);
speech.textSpeed = 2;
speech.say("This phrase prints letter 2 by 2.");
As soon as the last letter is printed, the Speech object triggers a "speechFinished" event and begins to count the timer down. From now on, the Speech object will remain unchanged until the timer reaches 0.
//You can listen for the "speechFinished" event
speech.addEventListener("speechFinished",test);
speech.say("Speaking...");
function test(E:Event){
trace("Finished speaking.");
}
When the timer has reached 0, the Speech object will trigger a "speechCleared" event and turn invisible. This is the end of the entire process.
speech.addEventListener("speechFinished",finish);
//You can listen for the "speechCleared" event
speech.addEventListener("speechCleared",clear);
speech.say("Speaking...");
function finish(E:Event){
trace("Finished speaking.");
}
function clear(E:Event){
trace("Removing speech balloon.");
}
What happens if you call the say() function while the speech balloon is printing text? Imagine your character is saying something and is suddenly surprised by an unexpected event.
The program is designed to handle interrupted speech so that you don't have to. If the speech was interrupted between printing two letters, it will print "--", jump to the next paragraph and start writing the new text. If the speech was interrupted in any other moment, it will jump to the next paragraph and start writing the new text
Imagine the character is saying "Text example!", and you interrupt it to write "INTERRUPTION!". Depending on when the text was interrupted, it will act differently. Here are some examples:
Text ex--
INTERRUPTION!
Text
INTERRUPTION!
Text example
INTERRUPTION!
Text example!
INTERRUPTION!
Text ex--
INTERRUP--
INTERRUPTION!
If you don't want to use "--" to mark an interruption, you can change the interruption text by using the interruptionText property of the Speech object.
speech.interruptionText = "...";
Besides the textSpeed and interruptionText properties, there are several other values you can use to control the Speech object. Here's the list of all of them:
textField:TextField [read-only] |
A reference to the TextField object owned by the Speech object.
|
contained:Boolean [read-write] |
Indicates whether the object containing the TextField is also part of the speech balloon. If you set this to true, the container's visibility will become the same as the TextField's visibility.
|
textSpeed:int [read-write] |
An integer value greater than 0. Indicates how many characters are written in each frame. |
position:int [read-only] |
A value indicating the position of the next letter to be written into the TextField.
|
phrase:String [read-only] |
The text currently being written into the TextField.
|
timer:int [read-only] |
An integer value indicating how many frames are left before the TextField becomes invisible. This value is only accurate after all the characters of the text have been written.
|
speaking:Boolean [read-only] |
This value is true if the Speech object is currently printing characters into the TextField object.
|
interruptionText:String [read-write] |
The text to be displayed if the Speech object is interrupted while writing a word.
|
The Speech object can be made to say things when a certain event has occurred. For example, when the user clicks on a specific button or pressed a key. You can use the setEvent() function to do this.
The setEvent() function has 4 parameters. The first parameter is the EventDispatcher object that will trigger the event. The second parameter is the name of the event to be triggered. The third parameter is the text to write when the event happens, and the fourth parameter is the timer parameter for the speech.
In this example, the a female character says something when you rub her belly:
//Imagine we have a MovieClip named "belly"
var belly:MovieClip;
speech.setEvent(belly,"mouseOver","Oooh, that tickles!",-1);
This is equivalent to writing:
belly.addEventListener("mouseOver",rubBelly);
function rubBelly(E:Event){
speech.say("Oooh, that tickles!",-1);
}
To stop the Speech object from listening to the event, you can call clearEvent() using the same EventDispatcher and event type as parameters.
speech.clearEvent(belly,"mouseOver");
You can use getEvent() to get an object containing information about the event the Speech object is listening to.
var event:Object = speech.getEvent(belly,"mouseOver");
The object has the following properties:
object |
The EventDispatcher object that triggers the event
|
type |
The name of the event being listened for. |
phrase |
The text that will be written when the event is fired. |
time |
The timer parameter used in the say() function.
|
Just like the Expression class, the Speech class allows you to listen to "checkpoint" events from the Expansion class.
You can use the setCheckPoint() function to make the Speech object write a text when one of the parts of the Expansion object reaches a specific size while going in a specific direction.
The first parameter is a reference to the MovieClip that's expanding. You can use Expansion.getExpandable() to get the MovieClip from the Expansion object. The second parameter is the expansion size to wait for. The third parameter indicates the direction the expansion is going.
These first three parameters correspond to the same first 3 parameters of the Expansion.setCheckPoint() function. Learn more about expansion checkpoints in Using the Expansion class.
The the fourth parameter is the text to write wih the checkpoint is triggered, and the fifth parameter corresponds to the timer parameter of the say() function. Finally, call the listenTo() function to make the Speech object listen to the "checkpoint" events of that Expansion object
Here's an example of how to make a female character say something when her belly reaches its maximum size:
//Assume these two objects already exist on the stage
var txt:TextField;
var belly:MovieClip;
//Create objects
var exp:Expansion = new Expansion(stage);
var speech:Speech = new Speech(txt);
//Initialize belly. Assume it has 50 frames.
var bellyID:int = exp.insertExpandable(belly,50);
exp.setGrowth(bellyID,1);
exp.setCheckPoint(bellyID,50,1);
//Set the Speech event
var cliptoListenFor:MovieClip = exp.getExpandable(bellyID);
speech.setCheckPoint(cliptoListenFor,50,1,"Wow! My belly is so big!",-1);
//Start!
exp.activate();
You may have noticed that you need to use setCheckPoint() in both the Expansion class and the Speech class, with just about the same parameters in both of them. Unfortunately, I was unable to find a way to make it any easier. You'll just have to remember to make sure that your Speech checkpoints and your Expansion checkpoints are the same.
You can use getCheckPoint() to get an object that represents the checkpoint being listened for.
var checkpoint:Object = speech.getCheckPoint(belly,50,1);
The object returned has the following properties:
part |
The MovieClip object that's expanding.
|
size |
The size being listened for. |
direction |
The direction of the expansion. This value is 1 to check for an expanding object and -1 to check for a reverting object. |
phrase |
The text that will be written when the checkpoint is reached. |
time |
The timer parameter used in the say() function.
|
Finally, you can remove a checkpoint listener by calling the clearCheckPoint() function. giving it the expandable part, the size and the direction.
speech.clearCheckPoint(belly,50,1);
Here's a simple program with a character's expanding belly. The belly is constantly expanding. When the user presses a key, the belly reverts. When the user presses a key again, the belly starts expanding again.
The character will say things when the following things happen:
import expansion.*;
//Assume these things exist:
var txt:TextField;
var belly:MovieClip;
//Initialize belly
var exp:Expansion = new Expansion(stage);
var bellyID:int = exp.insertExpandable(belly,50);
exp.setGrowth(bellyID,1);
exp.setCheckPoint(bellyID,50,1);
exp.setCheckPoint(bellyID,1,-1);
//Initialize speech
//(Assume txt is inside a speech balloon MovieClip
var speech:Speech = new Speech(txt,true);
speech.textSpeed = 2;
//Speech events
speech.addEvent(belly,"mouseOver","Mmmm... That feels nice.");
speech.addEvent(belly,"mouseDown","Ooh! Hey, don't poke me!");
speech.addCheckPoint(belly,50,1,"Wow! My belly is huge!",30);
speech.addCheckPoint(belly,1,-1,"Ah, back to normal again");
//Listen to the expansion
speech.listenTo(exp);
//Activate!
exp.activate();
//Control the expansion
stage.addEventListener("keyDown",toggleExpansion);
function toggleExpansion(E:Event){
exp.growth = -exp.getGrowth(bellyID);
}
If you plan to stop using the Speech object before the end of the program, please use the destroy() function to remove any events it may be listening to.
This concludes the tutorial on how to use the interactive expansion animation library. I hope this was helpful to you. Please see the Speech class reference manual to get a more compact and structured view of the Speech class.
© 2014 Doom the wolf. http://doom-the-wolf.deviantart.com