Table of Contents

Constructor

new TextFormat()
new TextFormat(font, size, color, bold, italic, underline, url,
               target, align, leftMargin, rightMargin, indent, leading)

Arguments

font

An optional string specifying the font property's initial value.

size

An optional integer specifying the size property's initial value.

color

An optional integer specifying the color property's initial value.

bold

An optional Boolean specifying the bold property's initial value.

italic

An optional Boolean specifying the italic property's initial value.

underline

An optional Boolean specifying the underline property's initial value.

url

An optional string specifying the url property's initial value.

target

An optional string specifying the target property's initial value.

align

An optional string specifying the align property's initial value.

leftMargin

An optional nonnegative integer specifying the leftMargin property's initial value.

righMargin

An optional nonnegative integer specifying the rightMargin property's initial value.

indent

An optional nonnegative integer specifying the indent property's initial value.

leading

An optional nonnegative integer specifying the leading property's initial value.

Properties

align

Specifies horizontal paragraph alignment.

blockIndent

Specifies paragraph indentation.

bold

Boolean; specifies bold character display.

bullet

Specifies whether to add bullets to paragraphs.

color

Specifies character color.

font

Sets the font for specified characters.

indent

Specifies indentation for a paragraph's first line.

italic

Boolean; specifies italicized character display.

leading

Specifies line spacing.

leftMargin

Specifies the margin to the left of a paragraph.

rightMargin

Specifies the margin to the right of a paragraph.

size

Specifies character font size, in points.

tabStops

Specifies horizontal tab stops, in pixels.

target

Specifies the window or frame for a hypertext link.

underline

Boolean; specifies underlined character display.

url

Specifies a hypertext link.

Methods

getTextExtent( )

Returns the pixel dimensions of a string rendered according to a given TextFormat object.

Description

Internally, a text field's visual formatting is described by style profiles stored in the Flash Player. Each profile holds format settings such as font size, font face, bolding, and margins. Every character in a text field is associated with one of these internal profiles. For example, in the text field:

Please hurry up!

two style profiles are represented: one with bold type and one without bold type. The characters P, l, e, a, s, and e are associated with the bold profile, while the remaining characters are associated with the nonbold profile. As necessary, Flash adds internal profiles to keep track of all text displayed in the Player. While ActionScript itself does not provide direct access to the Player's internal profiles, it can depict the profile for any character as a TextFormat object. A TextFormat object's properties control the display features associated with a specific character or, alternatively, report the display features common to a series of characters.

To retrieve a TextFormat object for an existing text field, we use the TextField.getTextFormat( ) method. For example, here we create a text field and then retrieve a TextFormat object that describes the formatting of the field's first character:

// Create the text field
this.createTextField("theField_txt", 1, 0, 0, 150, 40);
// Assign the field some text for display
theField_txt.text = "Please hurry up!"
// Retrieve a TextFormat object for theField_txt's first character (index 0)
firstCharFormat = theField_txt.getTextFormat(0);
// Check whether the first character is bolded
trace(firstCharFormat.bold);  // Displays: "false"

A TextFormat object's usage is intimately tied to a corresponding TextField object. For example, the TextFormat object of an existing text field is obtained using TextField.getTextFormat( ). Throughout the following discussion, pay careful attention to which properties and methods are part of the TextFormat class and which are part of the TextField class. To set the formatting of a character or span of characters in a text field, we must create a TextFormat object, set its properties, and apply the format using the TextField.setTextFormat( ) method (this is known colloquially as "applying a text format object to a text field").

The setTextFormat( ) method optionally accepts the starting and ending character indexes over which to apply the text format object. For example:

// Create the TextFormat object
emphasisFormat = new TextFormat();
// Specify bold for the format
emphasisFormat.bold = true;
// Apply the format to the word 'Please', characters 0 to 5 (inclusive)
theField_txt.setTextFormat(0, 6, emphasisFormat);

Alternatively, we can set the TextFormat object's properties when we construct it (using null for properties we do not wish to set):

emphasisFormat = new TextFormat(null, null, null, true);

When text is added to a field, it is formatted according to the field's default style profile, which is represented in ActionScript by a distinct TextFormat object called a new text format. We can view a field's default style profile by using TextField.getNewTextFormat( ). We can modify a field's default style profile by creating a TextFormat object, setting its properties, and passing it to TextField.setNewTextFormat( ). For more details on modifying the format of new text, see TextField.getNewTextFormat( ) and TextField.setNewTextFormat( ).

For a description of the paragraph and character formats available, see the property listings for TextFormat. Note that each property is also available through analogous HTML tags, described under TextField.htmlText and in Appendix E. The default settings for an existing text field's TextFormat object are listed in Table 18-25.

Table 18-25. Default TextFormat property values

Property	Default value	Datatype
bullet	false	boolean
tabStops	empty object	object
blockIndent	0	number
leading	0	number
indent	0	number
rightMargin	0	number
leftMargin	0	number
align	"left"	string
underline	false	boolean
italic	false	boolean
bold	false	boolean
target	""(empty string)	string
url	"" (empty string)	string
color	0	number
size	12	number
font	"Times New Roman"	string

Usage

Writing to the text property of a TextField object destroys any custom formatting associated with the field. Use the TextField.replaceSel( ) method to add text to a field while retaining its formatting.

See Also

TextField.getNewTextFormat( ), TextField.getTextFormat( ), TextField.htmlText, TextField.replaceSel( ), TextField.setNewTextFormat( ), TextField.setTextFormat( ), the TextField class

Table of Contents