259 IN THIS PART Chapter 10 Text text PART III Part III focuses exclusively on text, and covers a variety of text uses. Chapter 10 begins with the dynamic creation of text fields and the styling of text elements using TextFormat objects. Using this approach, text styles can be precreated and applied to individual text fields at any time. For global styling, you can use a combination of HTML and Cascading Style Sheets (CSS). Both the HTML content and the CSS styles can be created internally or loaded from external sources. By using HTML and CSS, you can establish styles that apply to an entire project, if desired. Further, CSS styles can be edited easily in one central location, and all text to which the styles are applied will be automatically updated. We finish the chapter with a look at Adobe’s new text technology, the Text Layout Framework (TLF). Built atop Flash Player’s new text engine, TLF was officially released both as part of the Flash Professional CS5 interface and as a set of ActionScript 3.0 classes, and offers Flash Platform users unprecedented typographic control. Download from Wow! eBook <www.wowebook.com> Download from Wow! eBook <www.wowebook.com> 261 IN THIS CHAPTER Creating Text Fields Setting Text Field Attributes Selecting Text Formatting Text Formatting with HTML and CSS Triggering ActionScript from HTML Links Loading HTML and CSS Text Layout Framework What’s Next? Working with text can be a basic affair, such as displaying a simple text string in a default text field, or as complex as your needs require, perhaps creating individual text fields for every character in a string to build an animated text effect. Learning how to create and manipulate text objects at runtime with ActionScript can increase flexibility and make it much easier to reuse code from project to project. In this chapter, we’ll focus mostly on how to display, populate, and format text data. We’ll discuss two kinds of text: the traditional Flash Platform text technology, available for many years and newly christened Classic text; and text created using the Text Layout Framework (TLF)—a significantly more robust text technology introduced with Flash Player 10. TLF offers improved typographical control, support for multiple columns, flowing text among multiple linked containers, and more. We’ll cover: • Creating Text Fields. Text fields can be created with ActionScript like any display object, freeing you from the Flash Properties panel and allowing you to create fields on the fly. • Setting Text Field Characteristics. How you set up your text field will determine how the field will appear and function. • Selecting Text. You can select segments of text using ActionScript by specifying the start and end of a selection block. • Formatting with TextFormat. Text can be formatted easily by creat- ing a formatting object that can be applied to one or more text fields at any time, including partial content of these fields. • Formatting with HTML and CSS. It’s also possible to use a lim- ited subset of supported Hypertext Markup Language (HTML) and tex t CHAPTER 10 Download from Wow! eBook <www.wowebook.com> Part III: Text 262 Creating Text Fields Cascading Style Sheets (CSS) features to format and style your text globally or on a field-by-field basis. • Triggering ActionScript from HTML. In addition to standard links in HTML text that might open a website, you can also use links to trigger ActionScript. This makes it easier to use HTML data to control your project and provides another way of dynamically triggering func- tions. For example, rather than creating buttons to drive an interface, a text field could contain links to serve the same purpose. • Push Yourself. Concluding this chapter is an example of how to load HTML and CSS data from external files, and an introduction to the Text Layout Framework (TLF). Creating Text Fields Creating text fields dynamically is as simple as creating any other display object, and we’ll be using this method in most of the examples in this chap- ter. The code that follows creates a text field and adds it to the display list. It also uses the text property to populate the field, as seen in the text_field_1.fla source file. 1 var txtFld:TextField = new TextField() 2 txtFld.text = "Hello Skinny"; 3 addChild(txtFld); Without your setting additional properties of the field, default values will shape most of its characteristics. These defaults are fairly straightforward, such as black text, dimensions of 100 × 100 pixels, no field styling (such as background or border use), and single-line display without text wrapping. In other words, no assumptions are made by ActionScript about the way you want to display the text. By default, a text field created with ActionScript will be a dynamic field type. This type supports programmatic control, in contrast to the static field type you might create by hand using Flash Professional’s Text tool. Later on we’ll show you how to create an input text field type, which also supports user input at runtime. Setting Text Field Attributes It’s almost certain that you’ll need to customize text fields to suit your needs, so we’ll modify a typical set of properties to demonstrate the most common adjustments made to a field. Whether you need fields that simply display text or accept input at runtime, ActionScript offers ample control over the appearance and functionality of a text field. It’s a simple matter to control color, wrap text, limit acceptable input characters, and more. Download from Wow! eBook <www.wowebook.com> Setting Text Field Attributes Chapter 10: Text 263 Dynamic Text Fields Dynamic text fields are the go-to field type because they support ActionScript control but not user input. When displaying text in typical scenarios, for example, you’re unlikely to want the user to edit your content. This first example can be found in the text_field_2.fla source file, and includes syntax for setting the most common properties of a text field. If you’ve been reading this book linearly, you’ve used several of these properties in the Hello World! examples as well as a few other exercises in past chapters. Collecting the properties here, however, will help you focus on them in the context of other text manipulations. Lines 1 and 2 create a text field and position it at (20, 20), while lines 3 and 4 set the width of the field to 200, and automatically size the height of the field to fit its content, while justifying left. This means the field will remain 200 pixels wide, but will resize from the upper-left corner to whatever height is required to accommodate all the text you add to the field. 1 var txtFld:TextField = new TextField(); 2 txtFld.x = txtFld.y = 20; 3 txtFld.width = 200; 4 txtFld.autoSize = TextFieldAutoSize.LEFT; 5 txtFld.border = true; 6 txtFld.borderColor = 0x000033; 7 txtFld.background = true; 8 txtFld.backgroundColor = 0xEEEEFF; 9 txtFld.textColor = 0x000099; 10 txtFld.multiline = true; 11 txtFld.wordWrap = true; 12 txtFld.selectable = false; 13 14 for (var i:Number = 0; i < 25; i++) { 15 txtFld.appendText("word" + String(i) + " "); 16 } 17 18 addChild(txtFld); Lines 5 through 9 enable and set the color of the border, background, and text of the field. By default, a field is transparent with black text. To show a border or background of any color, the corresponding properties must first be enabled, as shown in lines 5 and 7. Once enabled, the default colors of the border and background are black and white, respectively. Line 6 sets the field’s border to a dark blue, and line 8 sets its background to light blue. Finally, line 9 sets the color of the text to a medium blue. Lines 10 through 12 control text behavior. Line 10 supports more than one line of text (allowing carriage returns or line feeds in the text, for example), and line 11 supports wrapping text to the next line. Line 12 prevents the user from selecting text within the field. Even if a field is of dynamic type, rather than input type, the user can still select and copy text by default. However, you may not want a text field to allow selection, or you may not want the mouse cursor to switch to the corresponding I-beam text edit cursor that comes with the selection process. In these cases, set the selectable property to false. Download from Wow! eBook <www.wowebook.com> Part III: Text 264 Setting Text Field Attributes Lines 14 through 16 populate the field using a for loop. This loop puts mul- tiple occurrences of the text “word” into the field, adding the loop counter number to the text as it goes, ending with a space each time through the loop. The result will be “word0 word1 word2 ” and so on. The appendText() method is used to add text to the field incrementally. This is a simple example that fills a text field quickly with minimal code, but adding new text to a populated field is quite common. You may want to build a list based on user selections, for example. Imagine a to-do list application in which a user can create a running list by adding new items when needed. Without appending text to the end of a list, every new item would replace all current items. In fact, you’ve already added text incrementally in previous chapters, including the opening script of Chapter 3 when you animated the string, “Hello World!”. Input Text Fields To allow the user to input text in a field at runtime, all you need to do is to set the field’s type property to INPUT using the TextFieldType class. Using default input field properties will suffice for things like a user typing a name or email address into a form. For more specific tasks, additional features are available. Consider, for example, a password field. When entering passwords, you usu- ally want to obscure the password by replacing its characters with symbols. You may also want to limit input in a field to a specific number of characters or range of allowable input. To demonstrate, consider the following script, seen in the text_field_3.fla source file: 1 var txtFld:TextField = new TextField(); 2 txtFld.x = txtFld.y = 20; 3 txtFld.width = 100; 4 txtFld.height = 20; 5 txtFld.border = txtFld.background = true; 6 txtFld.type = TextFieldType.INPUT; 7 txtFld.maxChars = 10; 8 txtFld.restrict = "0-9"; 9 txtFld.displayAsPassword = true; 10 addChild(txtFld); 11 stage.focus = txtFld; Lines 1 through 4 and line 10 create, position, and size the field, and add it to the display list. Line 6 sets the field to an input field, and lines 7 through 9 define the password-related behavior. The maxChars property limits the num- ber of characters that can be entered. The restrict property limits the valid characters that can be entered. These characters can be expressed individually or in ranges, such as the 0 through 9 number range used in this example. For example, you could allow uppercase and lowercase letters, the dollar sign ($) and underscore (_), and numbers 0 through 5, this way: txtFld.restrict = "A-Za-z$_0-5"; N O T E The appendText() method executes faster than using the += compound oper- ator ( txtFld.text += "new value") and is recommended for this purpose. Download from Wow! eBook <www.wowebook.com> Selecting Text Chapter 10: Text 265 Line 9 performs the task of automatically switching the typed character for an asterisk at runtime to hide the password. Finally, line 11 gives the field focus so the user can begin typing without first selecting the field with the mouse. Selecting Text Your control over text and text fields is not limited to styling or input. You can also track user selections or even select portions of a field programmatically and replace its content. The following example, found in the text_field_4.fla source file, uses the but- ton creation class discussed in Chapter 8 to create two buttons that allow you to select and replace a word of text. The first block of code consists only of material discussed previously in this and prior chapters. Line 1 imports the RoundRectButton class, lines 3 through 11 create and setup a dynamic text field, and lines 12 through 28 create two buttons and add event listeners to trigger the functions at the end of the script. 1 import com.learningactionscript3.ui.RoundRectButton; 2 3 var txtFld:TextField = new TextField(); 4 txtFld.x = txtFld.y = 20; 5 txtFld.width = 500; 6 txtFld.autoSize = TextFieldAutoSize.LEFT; 7 txtFld.multiline = true; 8 txtFld.wordWrap = true; 9 txtFld.selectable = false; 10 txtFld.text = "Lorem ipsum dolor sit amet, elit, sed."; 11 addChild(txtFld); 12 13 var selBtn:RoundRectButton = createButton("Select"); 14 selBtn.x = 300; 15 selBtn.y = 20; 16 selBtn.addEventListener(MouseEvent.CLICK, onSelectWord, 17 false, 0, true); 18 addChild(selBtn); 19 20 var repBtn:RoundRectButton = createButton("Replace"); 21 repBtn.x = 300; 22 repBtn.y = 60; 23 repBtn.addEventListener(MouseEvent.CLICK, onReplaceWord, 24 false, 0, true); 25 addChild(repBtn); 26 27 function createButton(labl:String):RoundRectButton { 28 return new RoundRectButton(110, 20, 10, 2, 0x000099, 29 labl, 0xFFFFFF); 30 } The new functionality is introduced in the pair of functions shown below. The first function, onSelectWord() in lines 31 through 34, defines the selec- tion behavior. Line 32 selects characters bound by indices 6 and 11. Counting characters begins with 0, and the setSelection() method includes the first N O T E If you have trouble using the Backspace/ Delete key when testing your movie in Flash Professional, it’s not because the restrict property prohibits its operation. This is a function of keyboard behavior in Flash’s built-in player. You can either test in a browser or disable keyboard shortcuts via the Control menu while in the player. This will remove the functional limitation on the Backspace/Delete key. Just remember to reenable keyboard shortcuts when returning to Flash. N O T E You can select text content with code when using either dynamic or input text fields. Download from Wow! eBook <www.wowebook.com> Part III: Text 266 Formatting Text character up to, but not including the last character. So, in this example, the second word, “ipsum,” is selected. Setting the alwaysShowSelected property in line 33 to true ensures that the selection highlight remains visible even when the field no longer has focus. When false (the default), the selection highlight will disappear when the user interacts with any other part of the SWF. 31 function onSelectWord(evt:MouseEvent):void { 32 txtFld.setSelection(6, 11); 33 txtFld.alwaysShowSelection = true; 34 } The onReplaceWord() function replaces the selected word with another. The first line is a form of error check that ensures that a selection has been made. This prevents an error if the user clicks the second button before making a selection with the first button. The error is avoided by checking that the start and end of the current selection are not equal. If, as a hypothetical example, you selected the first five characters of text in any field, the start of the selection would be different from the end of the selection. If, however, you made no selection, both values would be 0, and if you just clicked in the field without selecting any text, both values would reflect the caret, or text edit cursor, location. Either way, both values would be the same, allowing you to use this information to confirm an attempted selection. If this error check passes, line 37 uses the replaceSelectedText() method to replace the previously selected text with the string argument of the method. 35 function onReplaceWord(evt:MouseEvent):void { 36 if (txtFld.selectionBeginIndex != txtFld.selectionEndIndex) { 37 txtFld.replaceSelectedText("LOREM"); 38 } 39 } Formatting Text Now that you can create, style, and populate text fields, as well as select their contents, you’re ready to learn how to format the text the field contains. This is accomplished with another class called TextFormat. The process is to set up a TextFormat instance that controls all the desired formatting, and then apply that object to all or part of a field. You can apply the object in two ways: by establishing it as the default format for the field, affecting all future input or by applying it on a case-by-case basis, affecting all or part of existing text. Only the application of the format varies in these cases. Creating the TextFormat instance is unchanged. In the upcom- ing example, we’ll create a source file that uses a format to style future text, and then we’ll modify that file to style text after it’s been added to the field. N O T E It’s also possible to select text field con- tent interactively using mouse input. See the companion website, http:// www.LearningActionScript3.com, for more information, specifically the post “Parsing Text Data with Mouse Interaction.” Download from Wow! eBook <www.wowebook.com> Formatting Text Chapter 10: Text 267 Establishing a format for new text 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 cus- tomize 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. 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; serif sans serif Figure 10-1. Serif (top) and sans-serif (bottom) fonts N O T E The blockIndent property (not used in this example), will indent the entire paragraph rather than the first line— typical when formatting block quotes in text display. Download from Wow! eBook <www.wowebook.com> Part III: Text 268 Formatting Text 14 txtFld.defaultTextFormat = txtFmt; 15 16 for (var i:Number = 0; i < 25; i++) { 17 txtFld.appendText("word" + String(i) + " "); 18 } 19 addChild(txtFld); Applying a format to existing text If you need to format existing text, you must use the setTextFormat() meth- od. 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 argu- ments 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 char- acters 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); Adding text after using setTextFormat() One important issue is worthy of note when adding text to a field after apply- ing 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, how- ever, 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"; N O T E Remember that character counting starts with 0 and the length property tells you how many characters are actu- ally in the field. So, if a text field con- tains five characters, the indices of the characters would be 0, 1, 2, 3, and 4, and the length of the field would be 5. The setTextFormat() method uses an ending index one higher than the char- acters you want to format in order to support the use of the length property in the method’s last argument. Download from Wow! eBook <www.wowebook.com> . RoundRectButton(1 10, 20, 10, 2, 0x 000 099, 29 labl, 0xFFFFFF); 30 } The new functionality is introduced in the pair of functions shown below. The first function, onSelectWord() in lines 31 through 34 , defines. txtFld.y = 20; 3 txtFld.width = 200 ; 4 txtFld.autoSize = TextFieldAutoSize.LEFT; 5 txtFld.border = true; 6 txtFld.borderColor = 0x 000 03 3 ; 7 txtFld.background = true; 8 txtFld.backgroundColor = 0xEEEEFF; 9. Attributes Chapter 10: Text 2 63 Dynamic Text Fields Dynamic text fields are the go-to field type because they support ActionScript control but not user input. When displaying text in typical scenarios,