| TextField.getTextFormat( ) Method | Flash 6 |
| retrieves a TextFormat object for specified characters |
The index of the first character whose formatting is described by the returned TextFormat object. It is optional, but it must be a nonnegative integer if it is included. If it is omitted, the entire field is used.
The index following the last character whose formatting is described by the returned TextFormat object. It is optional, but it must be a nonnegative integer if it is included.
A TextFormat object describing the formatting of the specified characters.
The getTextFormat( ) method lets us examine the existing formatting of one or more characters already in a field. It returns a TextFormat object whose properties describe the formatting of the specified characters. For a detailed description of TextFormat objects, see the TextFormat class.
When getTextFormat( ) is invoked with one integer argument, or if endIndex is equal to beginIndex + 1, the returned TextFormat object reflects the formatting for the single character at beginIndex. For example, here we apply a format to the first four characters of a text field, and then we check the font of the 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 = "What time is it?";
// Create a TextFormat object with a font property of "Arial"
sansFormat = new TextFormat("Arial");
// Apply the format to the word 'What', characters 0 to 3 (inclusive)
theField_txt.setTextFormat(0, 4, sansFormat);
// Retrieve a TextFormat object for the first character
firstCharFormat = theField_txt.getTextFormat(0);
// Check the font property
trace(firstCharFormat.font); // Displays: Arial
When getTextFormat( ) is invoked with two integer arguments, the returned TextFormat object represents the formatting for the span of characters from beginIndex to endIndex - 1. And when getTextFormat( ) is invoked with no arguments, the returned TextFormat object represents the formatting for all the characters in the field.
If a specific format (e.g., font, bold, or italic) is not the same for all characters in a specified span, the corresponding property of the TextFormat object for that span will be null. Continuing with our example, if we retrieve a TextFormat object for the entire text of theField_txt, we find that properties shared by all characters return non-null values:
// Retrieve a TextFormat object for all characters in theField_txt allCharsFormat = theField_txt.getTextFormat(); // Now check whether all the characters are bold trace(allCharsFormat.bold); // Displays: false
But properties that vary between characters return null:
// Check the font for all characters trace(allCharsFormat.font); // Displays: null (if font is not uniform)
The first four characters in theField_txt have a different font than the remaining characters, so no single font property value can accurately describe the entire span and null is returned.
Note that changes to a TextFormat object returned by getTextFormat( ) do not have any effect on the text of theField until the object is applied with setTextFormat( ). For example, on its own, the following assignment of the font property has no effect on theField_txt:
allCharsFormat.font = "Courier New";
But when we add a call to setTextFormat( ), the change is applied:
theField_txt.setTextFormat(allCharsFormat); // Applies the "Courier New" font
// to the whole text field
Don't confuse getNewTextFormat( ) with getTextFormat( ); the former retrieves the format used for text that will be added to theField in the future, while the latter retrieves the format for characters already in theField.
For a detailed description of TextFormat objects, see the TextFormat class entry.
TextField.getNewTextFormat( ), TextField.setNewTextFormat( ), TextField.setTextFormat( ), the TextFormat class
