Easily Create Souped-Up Flash Text Fields With TextArea

In this tutorial I'll walk you through the steps required to install and use the TextArea component as an alternative to Flash's native TextField class, and show you how to detect mouse roll over/out events on hyperlinks. I'll also talk about how you can call custom functions and pass different data types as arguments.

Background

The native TextField class was the first to support text scripts in Flash projects. With TextField, you could support dynamic and static text, as well as the input type to allow user interactivity. It also supported a (very limited) selection of HTML tags for styling your scripts - but when comparing this narrow availability of HTML support in TextField to what is possible with regular HTML files being used within browsers, Flash developers felt the extreme lack of flexibility when dealing with text.

In 2009 when TLFTextField was introduced, developers were hoping to see some solutions - but these didn't appear. Today, with the TextArea class, you can do what you always wanted with your text blocks. Functionalities like detecting roll over/out on href links, calling custom functions from text blocks, creating anchor links, loading custom created tags like video players, slideshow, and buttons: these are all now possible with TextArea.

Final Result Preview

The following simple no-frills demo will present how custom functions are called on hyperlinks. This is what you'll build in the next 30 minutes:

Step 1: Set Up the Environment

TextArea can be used in any IDE that compiles AS3 - like Flash Builder, CS pro versions and FlashDevelop - which means it'll work across Flash platform (in Flex, AIR and AS3-only web projects). Different IDEs each have a somehow similar but unique approach to how you compile your project, and due to this diversity it's sometimes frustrating, especially for beginners, to work with AS3 tutorials because the author may prefer Flash Builder while the learner is accustomed to work with the CS IDE.

To solve this problem, I will try to explain the usage of TextArea independent of the IDE. So, the first step is to set up your environment. No matter which IDE you're using, just open it and create a new AS3 project, then save it somewhere on your computer.

Create a document class, name it Main.as, and add a trace call to output Hello World.

package
{
	import flash.display.MovieClip
	
	public class Main extends MovieClip
	{
		
		public function Main():void
		{
			trace("Hello World")
		}
	}
}

Step 2: Download TextArea

TextArea is free to download and to use but be sure to read the license agreements here. Head to doitflash.com and find the download button at the bottom of the home page to download TextArea classes.

Extract the zip file you downloaded, TextArea.zip, to your computer, go to the folder TextArea/Src, and copy the com folder then to the same directory as your document class, Main.as.

By copying the com folder to where you have your project document class, you are letting the IDE find TextArea classes only in this specific project. Alternatively, you could copy the classes to your global class path so that it will always be available to all your projects - to find out more, read How To Use an External Library in Your Flash Projects.

Step 3: Initializing TextArea

After downloading and installing the TextArea, it's time to initialize it. First you need to import the required classes to the Main class.

import com.doitflash.text.TextArea;

Then remove the hello world trace function and enter the following instead.

var _textArea:TextArea = new TextArea(); 
_textArea.wordWrap= true;
_textArea.multiline = true;
_textArea.htmlText = "Initialize TextArea just like you used to initialize TextField.";
this.addChild(_textArea);

Test your movie and this time instead of outputting hello world, you'll see a text field (but not a TextField!) created for you:

As you can see, TextArea works exactly like the native TextField class. All the different settings that you could apply to TextField are true for TextArea also; it's basically an extension to TextField so it will do everything TextField does, plus more. I'll talk about these extra features in the next sections.

Step 4: Feeding TextArea With an XML File

To make this tutorial as informative as possible and to make it useable for real world practices, let's try to feed the TextArea instance with data from an external XML file.

This procress will again be similar to how you load XML data into TextField. First, create your XML file and place it where you have the published SWF file from the previous steps. Make the XML look like the below and save it as "data.xml":

<?xml version="1.0" encoding="UTF-8"?>
<data>
<![CDATA[
<p align="left"><font face="Tahoma" size="13" color="#333333">
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Nam cursus. Morbi ut mi. 
Nullam enim leo, egestas id, condimentum at, laoreet mattis, massa. 
</font></p>
]]>
</data>

(So that XML contains HTML in a CDATA section.)

Now get back to your Main.as, which should look like the following:

package
{
	import flash.display.MovieClip
	import com.doitflash.text.TextArea;
	
	public class Main extends MovieClip
	{
		
		public function Main():void
		{
			var _textArea:TextArea = new TextArea(); 
			_textArea.wordWrap = true;
			_textArea.multiline = true;
			_textArea.htmlText = "Initialize TextArea just like you used to initialize TextField.";
			this.addChild(_textArea);
		}
	}
}

Add the required imports for xml loading process.

import flash.events.Event;
import flash.net.URLLoader;
import flash.net.URLRequest;

Then replace the whole Main() function with this.

		public function Main():void
		{
			var loader:URLLoader = new URLLoader();
			loader.addEventListener(Event.COMPLETE, onXmlLoaded);
			loader.load(new URLRequest("data.xml"));
			
			function onXmlLoaded(e:Event):void
			{
				var xml:XML = new XML(e.currentTarget.data);
				
				var _textArea:TextArea = new TextArea(); 
				_textArea.wordWrap = true;
				_textArea.multiline = true;
				_textArea.width = 400;
				_textArea.height = 200;
				_textArea.condenseWhite = true;
				_textArea.htmlText = xml.text();
				addChild(_textArea);
			}
		}

The above code loads data.xml - there's no difference from how you would have done it with a TextField so far.

Step 5: Detecting Mouse Rollover/Rollout

To use the specific features of TextArea, you need to specify a few extra settings when initializing it.

The first and the most important thing to remember about using TextArea is that you should use the fmlText method for sending text scripts into the instance rather than using the classic htmlText. The fmlText method will parse scripts using a different approach than htmlText; it stands for Flash Markup Language Text.

So, in your test project, replace htmlText with fmlText like below.

_textArea.fmlText = xml.text();

The next thing to do is create two custom functions in your document class, Main.as, which will be called when you rollover or rollout a hyperlink (which we will build later in data.xml). For the sake of this tutorial, these two functions will just trace some outputs, but in the real world, you could do anything you want with these functions - like, say, opening a tooltip window.

public function funcOnOver():void
{
	trace("rollOver");
}
public function funcOnOut():void
{
	trace("rollOut");
}

You should also set some settings while initializing the TextArea instance. Add these lines just after you initialize TextArea.

_textArea.holder = refToThis; // indicates the location where you are adding TextArea to stage
_textArea.client = refToThis; // must be the location where you have your "allowedFunctions" saved
_textArea.mouseRollOverEnabled = true; // enables mouse rollover detection
_textArea.funcSecurity = true; // makes sure only function names in "allowedFunctions" are accessible
_textArea.allowedFunctions(funcOnOver, funcOnOut);

Also add the following line to the beginning of the Main() function.

var refToThis:Object = this;

To make sure you have written the code in Main.as correctly, below is how your file should look up to now.

package
{
	import flash.display.MovieClip
	import com.doitflash.text.TextArea;
	
	import flash.events.Event;
	import flash.net.URLLoader;
	import flash.net.URLRequest;
	
	public class Main extends MovieClip
	{
		
		public function Main():void
		{
			var refToThis:Object = this;
			
			var loader:URLLoader = new URLLoader();
			loader.addEventListener(Event.COMPLETE, onXmlLoaded);
			loader.load(new URLRequest("data.xml"));
			
			function onXmlLoaded(e:Event):void
			{
				var xml:XML = new XML(e.currentTarget.data);
				
				var _textArea:TextArea = new TextArea(); 
				_textArea.holder = refToThis; // indicates the location where you are adding TextArea to stage
				_textArea.client = refToThis; // must be the location where you have your "allowedFunctions" saved
				_textArea.mouseRollOverEnabled = true; // enables mouse rollover detection
				_textArea.funcSecurity = true; // makes sure only function names in "allowedFunctions" are accessible
				_textArea.allowedFunctions(funcOnOver, funcOnOut);
				_textArea.wordWrap = true;
				_textArea.multiline = true;
				_textArea.width = 400;
				_textArea.height = 200;
				_textArea.condenseWhite = true;
				_textArea.fmlText = xml.text();
				addChild(_textArea);
			}
		}
		
		public function funcOnOver():void
		{
			trace("rollOver");
		}
		public function funcOnOut():void
		{
			trace("rollOut");
		}
	}
}

That's pretty much everything you need to do in your .as file; and the rest will be done in the XML but before we go to XML and create a hyperlink, let's talk a bit about the above settings.

First we have the holder property which is something that you won't use in this article but when you go deeper into TextArea to create custom html tags you will need this a lot; for the sake of this tutorial, it's sufficient for you to know that this property saves the location where you are adding the TextArea instance into the stage.

Then we have the client property. This is the location of - or better to say, this is a reference to - a class where you save all your allowed functions. In this example we use Main.as as the client, but if you have a long list of functions that want to give them the permission to be called from your text scripts, you may prefer creating a separate class for that purpose.

We also have the mouseRollOverEnabled property which is set to false by default for performance reasons. If you want to detect mouse roll over/out on your hyperlinks, you must make sure you enable this property.

Then we have two security properties: allowedFunctions and funcSecurity. These properties will let you restrict the called functions to the specific ones mentioned in the allowedFunctions method.

Okay, to see the magic, get back to data.xml and and add the following line somewhere inside the CDATA section:

Here's a <u><a href='onMouseOver:funcOnOver();onMouseOut:funcOnOut()'>SAMPLE LINK</a></u>.

As you see you have created two function calls (one on mouse rollover, one on mouse rollout) and you can do whatever you like with these functions inside your AS3 project.

But this is not all! In the next section I'll talk about how you can call custom functions and pass different types of data as arguments.

Step 6: Pass Arguments to Functions

Up to now, you have learned how to set the TextArea instance ready for accepting function calls from HTML content which can be placed in external sources like XML. Now we're going to send different types of arguments along with the calls.

We can send array, object and simple string types. Try adding the following hyperlink somewhere inside the CDATA tag in your XML file:

<u><a href='event:func1()'>SIMPLE CALL</a></u>.<br />
<u><a href='event:func2(some string)'>SEND STRING</a></u>.<br />
<u><a href='event:func3([0,1,2,3,4])'>SEND ARRAY</a></u>.<br />
<u><a href='event:func4({var1:val1;var2:val2})'>SEND OBJECT</a></u>.<br />
<u><a href='event:func5(string,[0,1,2],{var1:val1;var2:val2})'>SEND MIXED ARGUMENTS</a></u>.<br />

This will create five function calls in your AS3 project; each function demonstrates how you can send different types of arguments. But remember that this will not work until you actually create these functions inside your AS3 project. To do that, simply add these functions along with the funcOnOver() and funcOnOut() functions that you had previously:

		public function func1():void
		{
			trace("no arguments sent");
		}
		public function func2($str:String):void
		{
			trace("arguments >> " + $str);
		}
		public function func3($arr:Array):void
		{
			trace("arguments >> " + $arr);
		}
		public function func4($obj:Object):void
		{
			trace("arguments >> " + $obj);
		}
		public function func5($str:String, $arr:Array, $obj:Object):void
		{
			trace("arguments >> " + $str);
			trace("arguments >> " + $arr);
			trace("arguments >> " + $obj);
		}

Now you have the calls in XML and the functions are also available in the AS3 project; all that's left is to give the usage permission to the TextArea instance. Modify the allowedFunctions method of TextArea as so:

_textArea.allowedFunctions(funcOnOver, funcOnOut, func1, func2, func3, func4, func5);

Now publish and test your project and try clicking the hyperlinks you created.

Congratulations, you have now learned how to enable mouse rollover and rollout in your text fields, and you know how to create custom functions and call them from within your text blocks.

Conclusion

TextArea extends TextField, adds only 6kb to your project, and can be used as an alternative to TextField. In this tutorial you learned how to initialize TextArea to create simple hyperlinks which can call custom functions inside your AS3 project, and you also learned how to enable mouse rollover and rollout detection on hyperlinks that can call custom functions.

There are many things you can do with these features, like open a tooltip when rolling over a certain hyperlink or create links which call a custom function in your project to navigate through your application pages easier.

I hope you find this tutorial (and TextArea itself) useful!

HIGHLIGHTS OF THE DAY