Tiitle: The TextFormat() Object
Level: Intermediate
Author: Benjie Moss
Website: www.232nd.net

The TextFormat() object was introduced by Macromedia with the release of the Flash Player 6. It's purpose is to provide an alternative to formatting content within a text field without the need for inserting HTML markup into your string. You will need a copy of Flash MX, Flash MX 2004 or Flash MX 2004 Professional to complete this tutorial.

Part One: Creating text field

In order to see the TextFormat() object in action we need to create a text field and provide it with content to be styled: Create a new Flash file, and select the first keyframe. Open the actions panel and enter the following script:

_root.createTextField("myTextField", 0, 0, 0, 0, 0);
myTextField.autoSize = true;
myTextField.text = "The quick brown TextFormat jumped over the lazy HTML";

The first line creates a text field on the _root with an instance name 'myTextField'. (The numbers that follow the instance name in the brackets refer to level, x position, y position, width and height in that order.) The second line sets autoSize to true, meaning the text field will expand to display all the content we enter into it. The third line inserts the string "The quick brown TextFormat jumped over the lazy HTML" into the field. Test your movie now and you will see the phrase displayed on the stage using Flash's default formatting.

Part Two: Applying default style

Without the TextFormat() object we would be left with the styles we could apply by use HTML elements embedded in the string, or the styles we could apply using the authoring environment. (Note that if you are using Flash MX 2004 it is possible to apply styles using Cascading Style Sheets.) Using the TextFormat object we not only have more control of the formatting of our content but applying styles is easier because our styles are seperated from our content.

Now we are going to apply a default style to our text field, this requires you to add two lines to your script so that it reads as follows:

defaultStyle = new TextFormat("myFont", 18, 0x000000, false, false, false, "", "", "left", 0, 0, 0, 18);
_root.createTextField("myTextField", 0, 0, 0, 0, 0);
myTextField.autoSize = true;
myTextField.setNewTextFormat(defaultStyle);
myTextField.text = "The quick brown TextFormat jumped over the lazy HTML";

The first line creates a new TextFormat object. The values inside the brackets, refer to font, font size, text colour, bold, italic, underline, url, target, alignment, left margin, right margin, first line indent and leading respectively. The second new line (note it's position in the code; after text field creation, but before inserting the content), is setNewTextFormat (not to be confused with setTextFormat which will be discussed in the next section). This text field method is used to set the default style of our text field. It applies, the style specified (in this case, 'defaultStyle') to the text field specified. Test your movie now, and you'll see your style applied to the wole text field.

Part Three: Apply specific styles

Applying a default style to a text field is only part of what we can do with TextFormat. We also have the ability to apply styles to specified portions of our content. In order to demonstrate this we are going to insert a link into our example so modify your script so it reads as follows:

defaultStyle = new TextFormat("myFont", 18, 0x000000, false, false, false, "", "", "left", 0, 0, 0, 18);
linkStyle = new TextFormat();
linkStyle.color = 0x0000ff;
linkStyle.underline = true;
linkStyle.url = "http://www.actionscripts.co.uk/";
linkStyle.target = "_blank";
_root.createTextField("myTextField", 0, 0, 0, 0, 0);
myTextField.autoSize = myTextField.html=true;
myTextField.setNewTextFormat(defaultStyle);
myTextField.text = "The quick brown TextFormat jumped over the lazy HTML";
myTextField.setTextFormat(16, 26, linkStyle);

The first new line creates a new TextFormat object called 'linkStyle', notice here that we do not need to specify all possible parameters inside the brackets when we create a TextFormat() object, we can instead specify just the few parameters we require as seperate lines: The following four lines specify the color (in this case blue), whether or not to underline the content, the target url and the target browser window of our link respectively. The final line in the script uses a new method; setTextFormat(). This method vaires from the setNewTextFormat() method in that it accepts three parameters; firstly the index of the character where the style begins, the index of the character after the final character to be included in the style and the style to apply. Remember that the index of a string begins at zero, so to turn the word 'TextFormat' into a link, we start at position 16, finish at positon 26 and apply our linkStyle text format.

Part Four: Applying dynamic style

Of course life is never that simple. Most of the time you need to apply style to dynamic text, and you can't expect the same words to appear in the same position in the same content every time. Assuming that at some point in the future the position in the string of the characters 'TextFormat' will change, we need to apply styles to words dynamically. The following example demonstrates the use of a while loop to run through your string applying the link style to every instance of the word 'TextFormat'. (Note that as well as adding new lines the setTextFormat() method has been altered.)

defaultStyle = new TextFormat("myFont", 18, 0x000000, false, false, false, "", "", "left", 0, 0, 0, 18);
linkStyle = new TextFormat();
linkStyle.color = 0x0000ff;
linkStyle.underline = true;
linkStyle.url = "http://www.actionscripts.co.uk/";
linkStyle.target = "_blank";
_root.createTextField("myTextField", 0, 0, 0, 0, 0);
myTextField.autoSize = myTextField.html=true;
myTextField.setNewTextFormat(defaultStyle);
myTextField.text = "The quick brown TextFormat jumped over the lazy HTML";
var linkString = "TextFormat";
var linkPosition = myTextField.text.indexOf(linkString);
while (linkPosition>=0) {
  myTextField.setTextFormat(linkPosition, linkPosition+linkString.length, linkStyle);
  linkPosition = myTextField.text.indexOf(linkString, linkPosition+1);
}

The first new line creates the variable 'linkString', this variable holds the string that we want to find and apply formatting to, within our content. The second new line finds the index of the first character of our linkString variable in our content. If the string isn't found at all, then nothing more will happen. The next new line is the start of our while loop. The script inside the while loops brackets will be repeated whilst the linkPosition variable is greater than or equal to 0. The penultimate new line uses setTextFormat to apply the 'linkStyle' format beginning at the character index held in linkPosition, and finishing 1 character index after the length of our 'linkString' string. The final line is vital, this line recalculates the variable 'linkPosition' so that the while loop can run again. Importantly it begins searching the string after the previous 'linkPosition' so that it does not keep finding the same set of characters. If you test your movie now you'll see no difference from the previous version, however if you add the word 'TextFormat' to your string a couple of times you'll see that no matter how you alter the string, provided the word 'TextFormat' is in there, the 'linkStyle' will be applied to it.

The TextFormat() object is an extremely flexible technique for handling text formatting in Flash, if you get stuck you'll find plenty of help in our forums. That's the end of this tutorial, I hope you found it useful.