Loading External Text Files In Flash ActionScript 3.0

Work Files:
Load_Text_Start.fla
summer.txt (right-click > save as )

In this article, we're going to learn how to load text from an external source into a Flash movie.

What is the benefit of loading text from an external source?
The nice thing about loading text externally is that when you need to update the text, then you simply need to edit the text file. You won't have to make changes to the .fla file anymore.

To load text from an external source, we will need the ff:

• a plain text file that contains the text we would like to load
• a URLRequest object to specify the path to the external text file
• a URLLoader object which will load the external text file into the Flash movie
• a TextField that will display the loaded text

2 exercise files accompany this tutorial:

1. Load_Text_Start.fla - this is the Flash movie where the external text will be loaded into
   
2. summer.txt - this is the plain text file that contains the text we will be loading into the Flash movie

The download links are found at the beginning of the article. Make sure that you save both files in the same folder. By the end of this tutorial, you should be able to load the external text into the Flash movie. And in succeeding articles, you will also learn how to format the text using a TextFormat object, and how to add text scrolling functionality.

So let's begin. Go ahead and open the Load_Text_Start.fla file. You will see that the document contains some artwork (a sun drawing) and 2 buttons (these buttons will be used to scroll the text up and down). We'll be creating a TextField which will be placed within the empty white area on the stage. This TextField will display the text loaded from the external source.

Let's now begin writing the code. Let's first create the TextField, add it to the display list and set some of it's properties. Select frame 1 of the Actions layer and go to the Actions Panel and type the ff:

// Create a TextField object
var myTextField:TextField = new TextField();

// Add the TextField object to the display list so that
// it will be visible on the stage
addChild(myTextField);

myTextField.border = true;
myTextField.multiline = true;
myTextField.wordWrap = true; 
myTextField.width = 215; 
myTextField.height = 225; 
myTextField.x = 300; 
myTextField. y = 50;

If you test your movie now, you should see the TextField just above the scroll buttons and to the right of the sun artwork.

Now that we have the TextField, we'll need a URLRequest object and a URLLoader object in order to load the external text file. The URLRequest allows us to specify the path to the external file that we would like to load. In this example, we want to load the summer.txt file, which we saved in the same folder as the Flash document. So since they are in the same directory, all we have to do is specify the filename summer.txt when we create the URLRequest object. The URLLoader, on the other hand, has the capability to load external text files into Flash movies. It is the URLRequest object that simply tells the URLLoader which file it's supposed to load.

So to recap, the URLRequest specifies which file is to be loaded, while the URLLoader is the one that loads the specified file. Now, let's go ahead and create the URLRequest and URLLoader objects:

var myTextField:TextField = new TextField();

// This next line creates the URLRequest object named textURL.
// The file name of the external text file to be loaded is
// passed as a parameter to the URLRequest constructor.
var textURL:URLRequest = new URLRequest("summer.txt");

// This next line creates a URLLoader object named textLoader
var textLoader:URLLoader = new URLLoader();

addChild(myTextField);

myTextField.border = true;
myTextField.multiline = true;
myTextField.wordWrap = true;
myTextField.width = 215;
myTextField.height = 225;
myTextField.x = 300;
myTextField. y = 50;

After creating the URLRequest and URLLoader objects, we can now tell Flash to load the external text file. The load() method of the URLLoader class is what instructs the URLLoader to load an external text file. The URLRequest object is passed as a parameter to the load() method so that the URLLoader will know which file it is supposed to load (ex. textLoader.load(textURL); ). But in addition to writing the load statement, we'll also need an event handler. Why is that? This is because we'll only be able to display the text in the TextField once the external text file has finished being loaded (and not while the loading process is still happening). Once the URLLoader begins to load the text file, we'll have to wait for the text file to be loaded completely, and only then can we display the text in the TextField. The event that will tell us when the file has been loaded completely is Event.COMPLETE (this event will be dispatched if and when the external text file has been successfully loaded). This event will be dispatched by the URLLoader object, so the event listener will be added to our URLLoader which we named textLoader. So let's go back to the Actions Panel and create the event handler and the load statement.

myTextField.border = true;
myTextField.multiline = true;
myTextField.wordWrap = true;
myTextField.width = 215;
myTextField.height = 225;
myTextField.x = 300;
myTextField. y = 50;

// This next lines adds an event listener that waits
// for the textLoader to completely load
// the external text file (Event.COMPLETE). Once loaded,
// the function named displayText will be called.
textLoader.addEventListener(Event.COMPLETE, displayText);

function displayText(e:Event):void 
{
     // This function will contain the code that will display the text in the 
     // TextField once the external text file has been loaded. But let's add
     // that code later. For now, let's just put in a trace statement.
     // This trace statement will just indicate that the file has loaded.
     trace("File loaded successfully.");
}

// This next line tells the TextLoader to load the
// external text file specified by the URLRequest object
// named textURL (which specifies the summer.txt file)
textLoader.load(textURL);

Now go ahead and test the movie. You should see the output window display the phrase File loaded successfully. So this means that the Event.COMPLETE event has been triggered and that the text file has been loaded successfully. If it doesn't, you might want to check that you typed in the correct file name - "summer.txt" - and that the text file is saved in the same directory as your Flash movie.

So now that the external text file has been loaded, where is the text? I don't see it.
What we've done so far is that we've simply just loaded the external text file. The text data is already in the Flash movie, we just haven't displayed it yet. So the next thing we need to do is to get the text data and then display it in the TextField.

Ok. So where exactly do I find the text data?
Once loaded, the text contained inside the external text file can be found in the URLLoader object that was used to load the external text file. That text can be accessed by using the data property of the URLLoader class (ex. textLoader.data).

And once I get the text data, how do I assign it to the TextField?
You'll use the same way you assign text to any TextField - by using the text property of the TextField class (ex. myTextField.text = textLoader.data; ). And REMEMBER, you'll have to do this only after the text file has been loaded completely. So you must place the text assignment statement inside the Event.COMPLETE listener function (which in this example is the displayText function).

So let's go back to the event listener function named displayText and let's remove the trace statement and replace it with the text assignment statement. But instead of typing textLoader.data inside the event listener function, we'll type in e.target.data . Since the even listener was added to the textLoader URLLoader object, then e.target will refer to textLoader as well. One advantage of using e.target is that we'll be able to use the same event listener function with other URLLoader objects as well (for example, we might want to have multiple URLLoader objects that load different external text files).

function displayText(e:Event):void 
{
     // This next line will assign the text from the external text file to the
     // TextField instance named myTextField
     myTextField.text = e.target.data;
}

Now if you test the movie, you should be able to see the text displayed inside the TextField.

Here's the code in full:

import flash.text.TextField;
import flash.net.URLRequest;
import flash.net.URLLoader;

var myTextField:TextField = new TextField();
var textURL:URLRequest = new URLRequest("summer.txt");
var textLoader:URLLoader = new URLLoader();

addChild(myTextField);

myTextField.border = true;
myTextField.multiline = true;
myTextField.wordWrap = true;
myTextField.width = 215;
myTextField.height = 225;
myTextField.x = 300;
myTextField. y = 50;

textLoader.addEventListener(Event.COMPLETE, displayText);

function displayText(e:Event):void 
{
     myTextField.text = e.target.data;
}

textLoader.load(textURL);

In the next part, we'll style the text using a TextFormat object.

NEXT: Formatting Externally Loaded Text In Flash ActionScript 3.0

Preloading in ActionScript 3.0 Part 2

Exercise Files:
Preloader02_Start.fla
bird.jpg
candles.jpg

We've learned about the basics of preloading in Part 1 of Preloading in ActionScript. In this lesson, we'll apply the same concepts to make a picture gallery that has the ability to preload the images. Links to the exercise files are provided at the beginning of this article. Make sure to save all these files in one folder.

Descriptions of Exercise Files

1. bird.jpg and candles.jpg
   These 2 files will be loaded externally into the Flash movie we will create.
2. Preloader02_Start.fla
   This Flash document has the following elements:
   
   • 2 Buttons - The instance names of the buttons are pic1_btn and pic2_btn. Clicking on these buttons will load the image files.
   • 1 TextField - The instance name of the TextField is percent_txt. This will display the loading progress of the image that is being loaded.

Go ahead and open the Preloader02_Start.fla file. Select frame 1 of the Actions layer and then go to the Actions Panel and place the code below (comments have been included to explain the code):

// Create the loader object that will be used to load the
// external image files. I've named it picLoader. We'll only
// need one loader since we don't plan on displaying the images
// at the same time. We only want to load and display them one
// at a time.
var picLoader:Loader = new Loader();

// Create the URLRequest objects that specify the filenames
// of the external image files. We need to create 1 URLRequest
// per image file. We have 2 images so we need to create two
// URLRequest objects. I've named the first one picURL1, which
// requests for bird.jpg. I've named the second one picURL2, which
// requests for candles.jpg.
var picURL1:URLRequest = new URLRequest("bird.jpg");
var picURL2:URLRequest = new URLRequest("candles.jpg");

// Add the event listeners for each of the buttons. We will
// use a CLICK event to tell Flash to respond. When any of
// the buttons are clicked, Flash will begin to load the
// corresponding image.
pic1_btn.addEventListener(MouseEvent.CLICK, clickOne);
pic2_btn.addEventListener(MouseEvent.CLICK, clickTwo);

// These are the event listener functions for the CLICK
// event handlers. I've created two different functions
// for each of the buttons since each button will be
// loading a different image. (but do know that there are
// more effecient ways to go about this).
// This clickOne event listener function is for when the
// pic1_btn button is clicked
function clickOne(e:MouseEvent):void
{
     // Add the event listeners for ProgressEvent.PROGRESS 
     // and Event.COMPLETE.
     // This is for the preloading of the images.
     picLoader.contentLoaderInfo.addEventListener(ProgressEvent.PROGRESS, onProgress);
     picLoader.contentLoaderInfo.addEventListener(Event.COMPLETE, onComplete);

     // This load statement below is the line that tells Flash to 
     // start loading the image.
     picLoader.load(picURL1);
}

// This next function does the same thing as the function above,
// except that it will load a different image as specified in the 
// load statement.
// This one is for the second button and will load 
// picURL2 (the candles.jpg image), while the other one will load 
// picURL1 (the bird.jpg image).
function clickTwo(e:MouseEvent):void
{
     picLoader.contentLoaderInfo.addEventListener(ProgressEvent.PROGRESS, onProgress);
     picLoader.contentLoaderInfo.addEventListener(Event.COMPLETE, onComplete);
     picLoader.load(picURL2);
}

// This is the event listener function for ProgressEvent.PROGRESS.
// It contains the preloader formula.
function onProgress(e:ProgressEvent):void
{
     // The line below calculates how much of the file has already 
     // been loaded.
     var nPercent:Number = Math.round(e.target.bytesLoaded / e.target.bytesTotal * 100);

     // This next line outputs the results from the preloading 
     // calculations.
     // The value will be displayed in the percent_txt TextField 
     // on the stage.
     percent_txt.text = nPercent.toString() + " %";
}

// This is the event listener function for Event.COMPLETE 
// (dispatched when the image has successfully loaded completely).
function onComplete(e:Event):void
{
     // Remove the ProgressEvent.PROGRESS and Event.COMPLETE 
     // listeners once the image has been loaded.
     picLoader.contentLoaderInfo.removeEventListener(ProgressEvent.PROGRESS, onProgress);
     picLoader.contentLoaderInfo.removeEventListener(Event.COMPLETE, onComplete);

     // Add the loader to the display list so that the image that 
     // was loaded will be visible on the stage.
     addChild(picLoader);

     // Adjust the x and y position of the loader so that it fits 
     // within the border drawn on the stage. If you don't put 
     // these lines, then the loader position will default to 
     // x = 0 and y = 0 (making it appear on the upper left corner 
     // of the stage.
     picLoader.x = 75;
     picLoader.y = 30;
}

AS3 Timer - ActionScript 3 Tutorial | Introduction to the Flash ActionScript 3.0 Timer Class

The Flash AS3 Timer class lets you create Timer objects, one common usage of which would be to create counters for your Flash application - like an AS3 countdown timer, a time limit counter for a game or some sort of timer delay. In this tutorial, we'll learn the basics of working with the Timer ActionScript 3 class.

NOTE: For those of you coming from AS2 and have been using the setInterval() function - there is also an AS3 setInterval() function, but the AS3 Timer class is a good alternative to using setInterval().

A Timer object has the ability to count at a specific interval, which can be set using what is called the delay. The delay is specified in milliseconds. For example, if there is a delay of 1000 milliseconds, then the Timer object will count at 1 second intervals. If there is a delay of 5000 milliseconds, then the Timer counts every 5 seconds. You can specify a delay as short as 20 milliseconds, but anything lower than that is not recommended and may cause problems.

So now let's go ahead and create a new AS3 Timer object. The Timer ActionScript 3 constructor accepts 2 parameters. The first parameter is for the delay. The second parameter is for the repeatCount. The repeatCount specifies the number of repetitions the Timer will make. If you don't specify a repeatCount or if you specify zero, the timer repeats indefinitely. If you specify a positive nonzero value, then the timer runs at that specified number of times and then stops. So for example, if you specify a repeatCount of 5, then the Timer will count 5 times and then stop. The delay parameter is required, while the repeatCount is optional.

var myTimer:Timer = new Timer(1000);

This creates a new Timer object named myTimer. A delay of one second has been specified.

NOTE: The delay is not always 100% accurate. It will usually be off by a few milliseconds, but in many cases, it's barely noticeable.

The Timer will not start automatically. Use the start() method of the Timer class in order to tell the Timer object to start.

var myTimer:Timer = new Timer(1000);
myTimer.start();

If you test your movie now, the Flash movie will launch, but you won't see anything happen. In order to tell Flash to respond and do something, then we'll need to create AS3 Timer event handlers so that our Flash movie will know what to do when certain Timer associated events get dispatched.

Let's first take a look at the TimerEvent.TIMER event. This event gets dispatched every time the Timer object makes a count. So for example, if you have a Timer object that has a 1 second delay, then TimerEvent.TIMER will get dispatched every 1 second. This event is useful if you'd like your Flash movie to do something repeatedly at a constant interval. So let's go ahead and create a TimerEvent.TIMER event handler that will tell Flash to display the word hello in the output window every time the Timer makes a count.

var myTimer:Timer = new Timer(1000);
myTimer.start();

myTimer.addEventListener(TimerEvent.TIMER, sayHello);

function sayHello(e:TimerEvent):void {
     trace("hello");
}

So now, if you test the movie, you will see the word hello come out in the output window every 1 second.

If you wish to keep track of how many times the Timer has been counting, then you can use the currentCount property of the Timer class. Each time the Timer makes a count, the currentCount property increases by 1. Let's add a trace statement that's going to output the Timer object's currentCount value every time the Timer makes a count.

var myTimer:Timer = new Timer(1000);
myTimer.start();

myTimer.addEventListener(TimerEvent.TIMER,  sayHello);

function sayHello(e:TimerEvent):void 
{
     trace("hello");
     trace("Current Count: " + myTimer.currentCount);
}

NOTE: The currentCount property begins at 0, but when you test the movie, you will see that the first value displayed is 1. This is because the Timer will only begin dispatching TimerEvent.TIMER after it makes that first count from 0 to 1. Also note that if you stop the Timer and then start it again, the currentCount will continue counting from that last value that it stopped at. To reset the currentCount property of a Timer object back to 0, then you can use the reset() method of the Timer class ( ex. myTimer.reset(); ). If the Timer is running, then the reset() method will also stop the Timer.

The other event that gets dispatched by the AS3 Timer object is the TimerEvent.TIMER_COMPLETE event. This gets dispatched when the Timer has completed the number of counts as set by the repeatCount parameter.

So let's go ahead and add in a repeatCount of 10, and then let's create an event handler for the TimerEvent.TIMER_COMPLETE event. Let's tell the Flash movie to output the word bye once it completes the specified number of counts.

var myTimer:Timer = new Timer(1000, 10);
myTimer.start();

myTimer.addEventListener(TimerEvent.TIMER, sayHello);
myTimer.addEventListener(TimerEvent.TIMER_COMPLETE, sayBye);

function sayHello(e:TimerEvent):void 
{
     trace("hello");
     trace("Current Count: " + myTimer.currentCount);
}

function sayBye(e:TimerEvent):void 
{     
     trace("bye");
}

So in the example above, the Timer will count 10 times. Each time it makes a count, the word hello will come out in the output window, and the currentCount value will increase by 1. Once it reaches 10, then the TimerEvent.TIMER_COMPLETE event gets dispatched, and you will see the word bye come out in the output window.

And that concludes this AS3 Timer - ActionScript 3 tutorial.