Table of Contents

theFormat.tabStops

Description

The array tabStops property specifies a list of tab stops for a paragraph, in pixels. As in word processing, a tab stop is the position at which items separated by the Tab character are aligned (i.e., the column where the insertion point jumps when the Tab key is pressed). In ActionScript, tab stops are used for tabular data entry and to produce simple tables, as shown in the following Example.

Each element in the tabStops array is measured from the left border of the text field, not from the previous tab stop. For example, a tabStops value of [50, 120] indicates two tab stops, one at 50 pixels and one at 120 pixels. To add a tab character to a string, type the Tab key directly, use the escape sequence "\t", or use String.fromCharCode(9). For convenience, we can assign a tab character to a variable:

var tab = String.fromCharCode(9);

A tab character always causes the insertion point to move ahead to the next available tab stop, even if previous tab stops are skipped. For example, if tabStops is set to [5, 100] for a text field that contains:

"Colin" + String.fromCharCode(9) + "Moock"

then "Moock" will appear 100 pixels right of the text field's left border. The word "Colin" is wider than 5 pixels, so the first tab stop is ignored and the next available one is used. Remember, tab stops are set in pixels, not characters. Average characters in a 10-point font are about 8 pixels wide.

To set the tab stops for an entire text field, invoke TextField.setTextFormat( ) without specifying any index arguments:

this.createTextField("theField_txt", 1, 0, 0, 250, 40);
theField_txt.border = true;
var tab = String.fromCharCode(9);
theField_txt.text = "One" + tab + "Two" + tab + "Three\n"
                  + "Four" + tab + "Five" + tab + "Six";
// Create a TextFormat object
format = new TextFormat();
format.tabStops = [50, 130];
// Apply the tab stops
theField_txt.setTextFormat(format);

To set the tab stops for the first paragraph in a text field, apply the format to the character at index 0:

theField_txt.setTextFormat(0, format);

To set the tab stops for any subsequent paragraphs, apply the format to the character immediately following the newline character:

theField_txt.setTextFormat(14, format);

To set the tab stops for a range of paragraphs, apply the format using start and end index arguments that include the desired paragraphs:

theField_txt.setTextFormat(0, 15, format);

If any paragraph wraps to the next line, the specified format range must include the subsequent line's first character; otherwise, the format will not apply to the wrapped line.

By default, a text field has tab stops every (4 * average character width) pixels and tabStops is an empty array. For a text field without any text, tabStops is null. For a completely new TextFormat object, it is also null, indicating that tabStops will not be set when the format is applied to a text field:

trace(anyUnformattedField_txt.getTextFormat().tabStops);  // Displays: nothing
                                                          // (an empty array)
var format = new TextFormat();
trace(format.tabStops);                                   // Displays: "null"

Example

The following code adds to all TextField objects a method that programmatically places an array of text in a table structure using a the tabStops property. Take note that it relies on the custom appendText( ) method listed under TextField.replaceSel( ). Both custom methods are available from the Code Depot.

/*
 * Method: TextField.makeTable
 *   Desc: Formats an array of text as a table.
 * Params: tabStops     Array containing the positions of the columns,
 *                      starting with column 2, not column 1. Text in each table
 *                      cell cannot wrap, so text must not exceed each tab stop.
 *         data         The array to format.
 */
TextField.prototype.makeTable = function (tabstops, data) {
  // Store the tab character in a variable
  var tab = "\t";
  // Calculate number of columns
  var numCols = tabstops.length;
  // Calculate number of rows
  var numRows = Math.ceil(data.length/numCols);
  // Initialize our text variable that will eventually be assigned to the field
  var newText = "";
  // Add tab characters between each column, 
  // and add newline characters after each row.
  // For each row...
  for (var i = 0; i < numRows; i++) {
    // ...cycle through each column.
    for (var j = 0; j < numCols; j++) {
      // Add each item in the array to our text
      newText += data[i*numCols + j];
      // If we're done with all the elements in the array, quit the loop
      if (i*numCols + j =  = data.length - 1) {
        break;
      }
      // If we're not on the last column...
      if (j < numCols - 1) {
        // ...add a tab character.
        newText += tab;
      } else {
        // ...otherwise add a newline character.
        newText += "\n"
      }
    }
  }
  // Finally, we have to apply the tab stops using a TextFormat object.
  // Create the TextFormat object, but keep the old tabStops property 
  // around so we can put it back when we're done. Hence, future text added 
  // will use the field's original tab stops, not our table's tab stops.
  format = this.getNewTextFormat();
  var oldTabStops = format.tabStops;
  format.tabStops = tabstops;
  // Apply the tab stops.
  this.setNewTextFormat(format);
  // Insert our table.
  this.appendText("\n" + newText + "\n");
  // Restore the original tab stops.
  format.tabStops = oldTabStops;
  this.setNewTextFormat(format);
}
// Example use. Create an array that will become a table.
var tableData = ["one", "two", "three", "four", "five", "six", "seven"];
// Create a text field to hold the table.
this.createTextField("theField_txt", 1, 0, 0, 250, 60);
theField_txt.border = true;
// Add some text and the table.
theField_txt.appendText("Here is the table:");
theField_txt.makeTable([50, 125, 200], tableData);
theField_txt.appendText("Isn't it pretty?");

See Also

String.fromCharCode( ), TextField.replaceSel( ), TextFormat.blockIndent, TextFormat.leftMargin

Table of Contents