In the following code, found in the text_format_1.fla source file, lines 1 through 7 create the format. It’s instantiated in line 1, and settings for font, color, size, leading (line spacing), left and right margins, and paragraph indent are established.

The font property is the name of the font you wish to use. The following syntax shows the use of a device font—a font that must be in the operating system of the user’s device (computer, handheld) to display correctly. System fonts can be specified by name, such as “Verdana,” but there’s no certainty that a user will have that particular font installed. To account for this variance, Flash Player can work with a user’s operating system to specify its default font (whatever that may be) in one of three categories.

Using “_serif” for the font property will use a font with serifs—the flourishes usually found at the top and bottom of most characters, as shown in Figure 10-1. Typically this means Times or Times New Roman, but anyone can customize an operating system, so the actual font used isn’t guaranteed. All that’s reasonably sure to happen is that a serif font will be chosen. Using “_sans,” as in the following script, will specify a sans-serif font (without serifs), such as Arial or Helvetica. Finally, using “_typewriter” will specify a fixed-width font, in which all characters share the same width to ensure that they line up nicely. This usually means that Courier or Courier New will be used.

Figure 10-1. Serif (top) and sans-serif (bottom) fonts

The color property is a hexadecimal color value in the 0xRRGGBB format. The size, leftMargin, and rightMargin properties are measured in pixels. The leading property is also measured in pixels but is based on the space between lines, rather than including the line height as in some typography-centric applications. For example, if you wanted 10-point type on 12-point leading, size would be set to 10 and leading would be set to 2. Finally, indent indents the first line of every paragraph by a measure of pixels.

1    var txtFmt:TextFormat = new TextFormat();
2    txtFmt.font = "_sans";
3    txtFmt.color = 0x000099;
4    txtFmt.size = 10;
5    txtFmt.leading = 4;
6    txtFmt.leftMargin = txtFmt.rightMargin = 6;
7    txtFmt.indent = 20;

Lines 8 through 13 create and setup a text field. Lines 14 though 18 apply the format to the field. Line 14 uses the defaultTextFormat() method to format future text. This must be applied while the field is empty, or it will have no effect. Lines 16 through 18 use a for loop and the appendText() method to add 25 words to the field, and line 19 adds the field to the display list.

8    var txtFld:TextField = new TextField();
9    txtFld.x = txtFld.y = 20;
10    txtFld.width = 200;
11    txtFld.autoSize = TextFieldAutoSize.LEFT;
12    txtFld.multiline = true;
13    txtFld.wordWrap = true;
14    txtFld.defaultTextFormat = txtFmt;
15
16    for (var i:Number = 0; i < 25; i++) {
17         txtFld.appendText("word" + String(i) + " ");
18    }
19    addChild(txtFld);

If you need to format existing text, you must use the setTextFormat() method. This method can apply a TextFormat instance to an entire field just like the defaultTextFormat property, but only after the text has been added to the field. To format an entire field, the only argument you must supply to the method is the format you want to use:

txtFld.setTextFormat(txtFmt);

To format selected text within the field, you can add two additional arguments to the method call, specifying the characters to be formatted. The first integer value is the starting character index and the second integer value is one more than the last character index. In other words, the span includes the character at the first index, but not the character at the second index.

The text_format_2.fla source file demonstrates this by adding the following new five lines of code to the prior example. Lines 20 through 23 create a new format that will style the changed text as red, bold, and underline, and lines 25 and 26 format the first and last word in the field. Line 25 formats from character 0 up to 5, to include “word0.” Line 26 uses the text field property length to determine the number of characters in the field and uses that value for the last index. The first index is 7 characters less to include the last characters added to the field, “word24 ”—created by line 17 of the last example in the Establishing a format for new text section.

20    var txtFmt2:TextFormat = new TextFormat();
21    txtFmt2.color = 0xFF0000;
22    txtFmt2.bold = true;
23    txtFmt2.underline = true;
24
25    txtFld.setTextFormat(txtFmt2, 0, 5);
26    txtFld.setTextFormat(txtFmt2, txtFld.length-7, txtFld.length);

One important issue is worthy of note when adding text to a field after applying a format with setTextFormat(). Using the recommended appendText() method to add text to a field will maintain the formatting of the last character as expected. Using the compound assignment operator (+=) to add text, however, will reset the field to its default text format. As a proof of concept, add the following lines to the end of the current example (or look at text_format_3.fla), and test your file twice, using each line in turn.

27    txtFld.appendText("new");
28    //txtFld.text += "new";

Using the first line, the extra word, “new” will be red, bold, and underlined because that’s the format when the text was added. Commenting out line 27 and using line 28, however, will remove all the red, bold, underline formatting from the field because the field will revert to its default format.

The first step to embedding a font in Flash Professional CS3 or CS4 is to create a new font symbol from the Library panel’s menu, seen in Figure 10-2. In the resulting Font Symbols Properties dialog—Figure 10-3 (CS3) and Figure 10-4 (CS4)—choose the font and font style you wish to embed.

Figure 10-2. Creating a new font from the Library menu (CS4 pictured)

In Flash Professional CS3, you select the bold, italic, or combination bold/italic styles by using the checkboxes below the font name (see Figure 10-3). In Flash Professional CS4, support for font families was introduced. You select these styles using the font family’s dedicated bold, italic (oblique), or bold/italic font in the Style menu. Older fonts that don’t have individual style variants may support the checkboxes for faux bold and italic found below the Style menu.

Figure 10-3. Font Symbol Properties (CS3 pictured)

Each font symbol can style text in a preset manner only: plain, bold, italic, or a combination thereof, and they can’t be combined at runtime. So, to include separate bold and italic font styles, for example, you need a font symbol for bold and a font symbol for italic.

As with other symbols, such as movie clips, we need to use a linkage class to instantiate a font symbol. So the name of the symbol itself should be useful and descriptive, but need not follow any specific conventions. When creating a linkage class, on the other hand (using the same Library menu shown in Figure 10-2), the class name should follow the same naming conventions applied to other classes throughout earlier chapters. For example, the name should contain no spaces and start with a capital letter. Figure 10-4 shows a class name for the font symbol in the exercise we’re building, VerdanaPlain.

Figure 10-4. Font Symbol Properties (CS4 pictured)

In both Flash Professional CS3 and CS4, the Linkage information can be found in the Font Symbol Properties dialog, accessed from the Library menu after the Font symbol has been created.

The process for embedding fonts in Flash Professional CS5 has been improved and simplified. All of the steps discussed in the CS3/CS4 section are accessed in one dialog box in version CS5. This dialog box is accessed by the Text✓Font Embedding menu command. Figure 10-5 shows the Options tab of this dialog box. At the top, selecting a font is similar to the process used in CS4, choosing a name, picking a family, and selecting a style.

As of CS5, however, you can specify which glyphs (characters) should be embedded with the font, just like you can when you embed fonts into a specific text field using the Flash Professional Properties panel. This allows you to select only a subset of the glyphs in a particular font family, which reduces file size. In Figure 10-5, only uppercase, lowercase, numerals, and punctuation characters are being embedded.

Figure 10-5. Flash Professional CS5’s Font Embedding dialog, showing the Options tab

Next to the Options tab in the dialog box is the ActionScript tab, as shown in Figure 10-6. Under this tab, you can export for ActionScript use and set a linkage class name, as is possible in previous versions of Flash Professional. At the top of this dialog box, you’ll notice an Outline format section with options for Classic and TLF text. Classic text includes dynamic and input text fields, and TLF is a new text field type that stands for Text Layout Framework, which we’ll discuss at the end of the chapter. If you embed an OpenType or TrueType font, you can choose the appropriate outline format for the kind of field you intend to use: Classic for Classic text fields, and TLF for Text Layout Framework fields.

Figure 10-6. A detail of the ActionScript tab from Flash Professional CS5’s Font Embedding dialog

Regardless of which version of Flash Professional you use, you end up with the same thing at this point: a Font Symbol that can be instantiated at runtime using ActionScript.

Once your symbol has been embedded and given a linkage name, you’re ready to use it in a TextFormat instance. The following code, found in the embed_font.fla source file, uses embedded fonts and the VerdanaPlain font symbol created in the previous sections. Line 1 instantiates the font symbol, and line 4 applies the embedded font to the font property of the text format. This is a very important step because it can be counterintuitive. You can’t set the property to the class or instance reference from line 1, and you can’t use a string, like “Verdana.” You must specify the fontName property of the font symbol instance. Finally, line 14 sets the embedFonts property to true.

1    var verdanaPlain:Font = new VerdanaPlain();
2
3    var txtFmt:TextFormat = new TextFormat();
4    txtFmt.font = verdanaPlain.fontName;
5    txtFmt.size = 8;
6    txtFmt.bold = true;
7
8    var txtFld:TextField = new TextField();
9    txtFld.x = txtFld.y = 20;
10    txtFld.width = 300;
11    txtFld.defaultTextFormat = txtFmt;
12    txtFld.text = "Hello World!";
13    txtFld.selectable = false;
14    txtFld.embedFonts = true;
15    addChild(txtFld);

Finally, note that lines 38 and 39 contain quotes within quotes. This would ordinarily be a problem because the second quotation mark would balance the first quotation mark and close a string. Typically, prematurely closing a string will cause a syntax error of some kind, but it virtually always results in unexpected behavior.

However, this file has no problem because the nested quotes have been escaped just like the tab and new line characters in the Tab Stops section of this chapter. The backslashes, when used as part of a string, prevent the characters from functioning like quotation marks and make them behave instead like any other character. It’s also possible to nest single quotes within double quotes when a double-quote is not required. This is demonstrated in lines 35 and 36.

Using Classic text fields, rotating a field will cause device fonts to disappear. The workaround for this issue is to embed the font in your SWF—after which the text will display correctly. The problem is, every font symbol you embed contributes to file size, and adding TLF fields to your files requires only a one-time file size increase for each user (which we’ll discuss at the end of this section). So, if you intend to use many device fonts, or even several variants of a small number of device fonts, you may be better served by using TLF.

The following code, found in the tlf_rotation.fla source file demonstrates rotation of both Classic and TLF text fields. The Classic field is positioned at x, y coordinates (20, 20), and the TLF field is placed at (100, 100). In the former case, the rotation causes the device font text to disappear. However, the same device font used in the TLF field remains visible.

1    import fl.text.TLFTextField;
2
3    var txtFld:TextField = new TextField();
4    txtFld.x = txtFld.y = 20;
5    txtFld.text = "Hello World!";
6    txtFld.rotation = 45;
7    addChild(txtFld);
8
9    var tlfFld:TLFTextField = new TLFTextField();
10    tlfFld.x = tlfFld.y = 100;
11    tlfFld.text = "Hello World!";
12    tlfFld.rotation = 45;
13    addChild(tlfFld);

In many ways, the core of the Text Layout Framework is the TextFlow class (contained in the flashx.textLayout.elements package provided by Adobe) and its TextFlow markup syntax. TextFlow markup is a bit like a cross between XML and HTML. It’s structured like XML but has predefined tags and attributes, and controls display features. Manipulating this class is your ticket to improved typographic control, columnar layout, and more.

Although you can populate a TextFlow instance incrementally using string input, it requires creating each paragraph, span, and so on individually with a collection of classes and a fair amount of additional syntax. Sometimes it’s simpler to write the TextFlow content as one string containing markup syntax, which is structured much like HTML. Understanding the syntax is not difficult, but explaining HTML-style syntax is outside the scope of this book.

Unfortunately, no clear documentation of the TextFlow markup syntax currently exists. At the time of this writing, Adobe recommends an understanding of TextFlow markup tags (Table 10-3) to learn how to structure the content and consulting the documentation of the TextLayoutFramework class (http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/formats/TextLayoutFormat.html) to learn how to lay out and format the content within the field.

Figure 10-8 shows the hierarchical relationship among TextFlow elements, which is also illustrated in the following sample markup structure.

Figure 10-8. Hierarchy of TextFlow elements

<div>
    <p>
       text<br />
       <a>link text</a>
    </p>
    <p>
       <span>text</span><br />
       <img />
    </p>
</div>

Div elements (div) can be used to organize copy into separate sections and commonly apply block styling that might apply to multiple paragraphs. Paragraph elements (p) are used (unsurprisingly) to define discrete paragraphs and contain paragraph-wide styling. They need not be limited to text, however. It’s common, for example, to enclose images (img) or lists of links (a) in paragraph tags, as shown previously. Span elements are used to style segments of a paragraph because they don’t force a line break. Finally, if a line break (br) is desired, you can add them anywhere within a paragraph or link element.

Table 10-4 describes a selection of TextFlow formatting options, all of which are used in the following example.

Figure 10-9. TLF text baselines

The following code is found in the tlf_typography.fla source file. It demonstrates many of the most common formatting options used in a TextFlow string, including some of those listed in Table 10-4. This example shows the simplest way to apply a TextFlow string to a TLFTextField class instance. The field’s tlfMarkup property will automatically populate the field’s internal TextFlow instance without first having to process the incoming string. Figure 10-10 shows the outcome of this file.

Figure 10-10. A TLF field formatted by a TextFlow markup string

1    import fl.text.TLFTextField;
2
3    var tlfTxt:TLFTextField = new TLFTextField();
4    tlfTxt.x = tlfTxt.y = 100;
5    tlfTxt.width = 350;
6    tlfTxt.multiline = true;
7    tlfTxt.wordWrap = true;
8    tlfText.selectable = false;
9    addChild(tlfTxt);
10
11    tlfTxt.tlfMarkup = "<TextFlow xmlns='http://ns.adobe.com/
      textLayout/2008' fontFamily='Arial' fontSize='18'><div><p>H<span
      baselineShift='subscript' alignmentBaseline='descent'>2</
      span>O, <span fontWeight='bold'>water</span>, <span typ
      ographicCase='uppercase'>everywhere</span>,<br /><span
      textDecoration='underline'>And</span> <span fontStyle='italic'>all</
      span> <span color='#009900'>the</span> <a href='http://
      en.wikipedia.org/wiki/The_Rime_of_the_Ancient_Mariner'>boards</
      a> <span lineThrough='true'>did</span> <span fontSize='12'>shrink</
      span>.</p></div><p textAlign='right'><span textAlpha='0.5'>Water,
      water,</span> <span trackingRight='5'>everywhere</span>,<br
      /><span lineHeight='150%'>Nor any drop to</span> <span
      textRotation='rotate90' baselineShift='10'>drink</span>. <img
      width='10' height='16' source='water_drop.jpg' /></p></TextFlow>";

One side effect of this approach, however, is that the TextFlow instance is tied to the field. In the last example of the chapter, we’ll look at an alternative approach that creates an independent TextFlow instance first, and then translates a string to populate it.

The following code, found in tlf_columns.fla, builds on the prior source file. Adding this code to the end of the prior example provides a simple demonstration of columnar layout. Arranging TLF text in columns requires direct manipulation of a TextFlow instance. In the prior example, however, working directly with a TextFlow instance was not required, thanks to the field’s tlfMarkup property. This code demonstrates a simple way of gaining access to a populated TLF field’s TextFlow instance through its textFlow property:

12    //addition to previous example
13    import flashx.textLayout.elements.TextFlow;
14
15    var tlfTextFlow:TextFlow = tlfTxt.textFlow;
16    tlfTextFlow.columnCount = 1;
17    tlfTextFlow.columnGap = 30;
18
19    stage.addEventListener(MouseEvent.CLICK, onClick, false, 0, true);
20    function onClick(evt:MouseEvent):void {
21        if (tlfTextFlow.columnCount == 1) {
22            tlfTextFlow.columnCount = 2;
23        } else {
24            tlfTextFlow.columnCount = 1;
25        }
26        tlfTextFlow.flowComposer.updateAllControllers();
27    }

Line 13 adds an import statement for the TextFlow class. Line 15 creates a TextFlow instance by referencing the field’s textFlow property. All that remains is to set the columnCount and, optionally, the columnGap properties. In this example, a mouse click will change the column count at runtime to demonstrate the automatic reflow of text. Line 16 sets the initial number of columns to 1, to match the appearance of the prior example. Line 17 sets the gap between columns to 30 pixels. This has no immediate effect on the layout of the text.

However, lines 19 through 27 create a mouse click listener and add it to the stage. With each mouse click, the conditional beginning in line 20 checks the number of columns in the field and toggles between 1 and 2 columns. Finally, Line 26 instructs the flow composer (which controls the flow of text) of the TextFlow instance to update the text flow of the field. Because the field is already populated, the layout reflows between 1 and 2 columns on the fly. Figure 10-11 shows the two-column layout of the file.

Figure 10-11. The same TLF field from Figure 10-10, reflowed into two columns

The last example of the chapter is the most advanced and demonstrates one of TLF’s most powerful features: the ability to flow text across multiple containers. This is called linked text, or threaded text, because the text is not broken apart when populating more than one text field. Instead, it flows through linked text fields, threading its way through your layout. This is further demonstrated with selectable linked text and the ability to scroll within a field while selecting text—just like you can in a text editor.

One of the first things you’re likely to notice, is that this script contains no direct reference to TLF text fields. Instead, it uses the concept of TLF containers—sprites or movie clips that are automatically populated with TLF text by Flash Player. This approach is very powerful because it means that anywhere you can create a sprite, you can fill it with TLF text, and even link it up as part of a chain of TLF text.

For example, you could create many text fields across the stage and size them all to accommodate one line of text. You could then link them together, flow “The Rime of the Ancient Mariner” through them, and animate them up and down like undulating waves of water. Best of all, you can easily reflow the text along the linked chain whenever required.

The following code is found in the tlf_containers.fla source file. Lines 1 through 6 import all the classes required to complete this exercise.

1    import flashx.textLayout.compose.StandardFlowComposer;
2    import flashx.textLayout.container.ContainerController;
3    import flashx.textLayout.container.ScrollPolicy;
4    import flashx.textLayout.conversion.TextConverter;
5    import flashx.textLayout.edit.SelectionManager;
6    import flashx.textLayout.elements.TextFlow;

Lines 8 through 16 fill the field with text. Lines 8 through 12 create a string of TLF markup. Lines 9 and 12 open and close the TextFlow content, and lines 10 and 11 use the dummyText() function (found in lines 49 through 55) to fill the two paragraphs with dummy text.

Lines 14 through 16 demonstrate how to create an independent TextFlow instance. They use the TextConverter class’s static method importToFlow() to convert the TextFlow markup into layout format. Not only does this allow you to separate the TextFlow from a text field for easy reuse, but it’s also particularly important here because we’re not making direct use of a TLF text field.

7    //create TextFlow instance
8    var textMarkup:String =
9        "<TextFlow xmlns='http://ns.adobe.com/textLayout/2008'>" +
10           "<p>" + dummyText() + "</p><br />" +
11           "<p>" + dummyText() + "</p>" +
12       "</TextFlow>";
13
14    var textFlow:TextFlow =
15        TextConverter.importToFlow(textMarkup,
16        TextConverter.TEXT_LAYOUT_FORMAT);

Lines 18 through 25 do nothing more than create sprites for cosmetic purposes. They will lie under the TLF containers to provide a border for each. This process uses the borderedBox() function, in lines 57 through 63, to draw borders into the sprites.

17    //create border shapes for cosmetic purpose
18    var box1:Sprite = borderedBox();
19    box1.x = box1.y = 10;
20    addChild(box1);
21
22    var box2:Sprite = borderedBox();
23    box2.x = 240;
24    box2.y = 10;
25    addChild(box2);

Lines 27 through 44 set up containers for the TLF text. Lines 27 through 29, and 31 through 34, create two sprites and position them side by side. Lines 36 through 39 turn these sprites into TLF containers using the ContainerController class. The containers and the width and height of each are passed to the class constructor. The class then does everything required to support TLF text display, all automatically.

The last part of the container code occurs in lines 41 through 44. These lines link the containers together and ready them for TLF text. Line 41 adds a new StandardFlowComposer instance to the TextFlow object’s flowComposer property. Lines 42 and 43 add the two containers to the flow composer using the addController() method, and line 44 updates all the controllers, flowing the text among them.

26    //create TLF containers
27    var container1:Sprite = new Sprite();
28    container1.x = container1.y = 20;
29    addChild(container1);
30
31    var container2:Sprite = new Sprite();
32    container2.x = 250;
33    container2.y = 20;
34    addChild(container2);
35
36    var controllerOne:ContainerController =
37        new ContainerController(container1, 200, 200);
38    var controllerTwo:ContainerController =
39        new ContainerController(container2, 200, 200);
40
41    textFlow.flowComposer = new StandardFlowComposer();
42    textFlow.flowComposer.addController(controllerOne);
43    textFlow.flowComposer.addController(controllerTwo);
44    textFlow.flowComposer.updateAllControllers();

Finally, lines 46 and 47 control the selection and scrolling options. Line 46 populates the interactionManager of the TextFlow with a SelectionManager instance. The interactionManager controls how a user can interact with a container. It can enable selection, editing, or both. In this case, the resulting TLF containers will allow users to select, but not edit, their content.

Line 47 concludes our discussion by enabling vertical scrolling, but only for the second container. Because the two containers are linked and selectable, users will be able to select text across both containers. Because the second container is scrollable, dragging your mouse through the text will scroll up or down as long as content exists outside the bounds of the container in that direction. Figure 10-12 shows the result of this exercise, with a selection in progress.

45    //enable selection and scrolling
46    textFlow.interactionManager = new SelectionManager();
47    controllerTwo.verticalScrollPolicy = ScrollPolicy.AUTO;
48
49    function dummyText():String {
50        var str:String = "";
51        for (var i:int = 0; i < 60; i++) {
52            str += "dummy text ";
53        }
54        return str;
55    }
56
57    function borderedBox():Sprite {
58        var sp:Sprite = new Sprite();
59        var g:Graphics = sp.graphics;
60        g.lineStyle(1, 0x000000);
61        g.drawRect(0, 0, 220, 220);
62        return sp;
63    }

Figure 10-12. Text flowed across two TLF containers with selection in progress

TLF is significantly different from Classic text when it comes to distributing your SWFs. TLF works as a runtime shared library (RSL)—an external archive of code (and sometimes assets) that must be distributed with your SWF.

When you publish your file, you will notice in the same directory as your SWF, that a document with the extension .swz has been created. This is the extension for a compressed runtime library. At the time of this writing, the file is called textLayout_1.0.0.595.swz, but the numbers used in this filename may change with future releases.

Unlike the classes and packages that are compiled into your SWF when you publish your projects, runtime shared libraries remain external. They must be distributed with your SWFs, and their location relative to your SWF should be maintained. For example, if the RSL is in the same directory as your SWF, this should be true when distributing your project, as well.

In the case of the TLF, Flash Player will attempt to download the RSL from the Adobe website, but it’s still a good idea to keep your own copy with your SWF in case the Adobe site is unavailable.

As external files, runtime shared libraries must be downloaded by the user, so using TLF adds about 160K to your overall project size. The good news is that you need to download each RSL only once. For example, if you create 10 projects that use TLF, and a reader views all 10 projects, the first project will initiate the download of the TLF RSL, but all remaining projects will use the library already on the reader’s hard drive.

TLF also causes a problem when a parent SWF loads a child SWF that uses a TLF text field. We’ll discuss this in Chapter 13 when we discuss loading external assets.