Table of Contents

theFormat.getTextExtent(text)

Arguments

text

The string to be measured in this character format.

Returns

An object with height and width properties.

Description

The getTextExtent( ) method returns an object whose height and width properties tell us the anticipated size of text, formatted according to theFormat. It is used not to measure text already assigned to a text field but to determine the dimensions of any arbitrary string in a particular character format. We make these theoretical measurements when generating dynamic interfaces. For example, a string that is found to be too large in a certain format can be reformatted to fit available space. The following Example truncates text with an ellipsis (...) if the text does not fit in a text field.

The getTextExtent( ) method measures only character formats; it ignores the effect of all paragraph formats (word-wrapping, line breaks, margins, bullets, indent, block indent, etc). For example, the following code with indentation:

f = new TextFormat();
f.indent = 30;  // Add indentation.
trace(f.getTextExtent("test").width);

yields the same result as this code, with no indentation:

f = new TextFormat();
trace(f.getTextExtent("test").width);

Example

The following code adds a new method, called setEllipsisText( ), to all text fields. Using getTextExtent( ), the method checks the width of a string before assigning it to a text field. If the string is too wide to fit in the field, the method crops the string and adds an ellipsis (...):

/*
 * Method: TextField.setEllipsisText()
 *   Desc: Truncates text to fit in a text field, and adds
 *         an ellipsis if necessary
 * Params: theText     Text to assign to the text field
 */
TextField.prototype.setEllipsisText = function (theText) {
  // Retrieve the format for newly added text
  var format = this.getNewTextFormat();
  // Initialize the substring being assigned to the field
  var theSubstring = theText;
  // Check how wide the text display area is. Subtract 8 to account
  // for the gutter between the text and the text field's border.
  var textRegion = this._width - 8;
  // Assume the string is too wide to fit
  var tooWide = true;
  // Check if our assumption is correct
  for (var i = theSubstring.length - 1; tooWide =  = true && i > 0; i--) {
    // If the string is too wide to fit in the field...
    if (format.getTextExtent(theSubstring).width > textRegion) {
       // ...remove a character, add an ellipsis, then check again.
       theSubstring = theText.substr(0, i) + "...";
    } else {
       // ...otherwise, the string will fit, so stop checking.
       tooWide = false;
    }
  }
  // Assign the corrected string to the text field
  this.text = theSubstring;
}
// Sample use of setEllipsisText()
this.createTextField("theField_txt", 1, 100, 100, 150, 60);
theField_txt.border = true;
theField_txt.setEllipsisText("If this text is too long it will be truncated.");

See Also

TextField.border, TextField._height, TextField.textHeight, TextField.textWidth, TextField._width, TextFormat.size

Table of Contents