flash.text

# TextSnapshot - AS3

Package | flash.text
Class | public class TextSnapshot
Inheritance | TextSnapshot Object

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

TextSnapshot objects let you work with static text in a movie clip. You can use them, for example, to lay out text with greater precision than that allowed by dynamic text, but still access the text in a read-only way.

You don't use a constructor to create a TextSnapshot object; it is returned by `flash.display.DisplayObjectContainer.textSnapshot` property.

Related API Elements

flash.display.DisplayObjectContainer.textSnapshot

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | charCount : int [read-only] The number of characters in a TextSnapshot object. | TextSnapshot
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | findText(beginIndex:int, textToFind:String, caseSensitive:Boolean):int Searches the specified TextSnapshot object and returns the position of the first occurrence of textToFind found at or after beginIndex. | TextSnapshot
|  | getSelected(beginIndex:int, endIndex:int):Boolean Returns a Boolean value that specifies whether a TextSnapshot object contains selected text in the specified range. | TextSnapshot
|  | getSelectedText(includeLineEndings:Boolean = false):String Returns a string that contains all the characters specified by the corresponding setSelected() method. | TextSnapshot
|  | getText(beginIndex:int, endIndex:int, includeLineEndings:Boolean = false):String Returns a string that contains all the characters specified by the beginIndex and endIndex parameters. | TextSnapshot
|  | getTextRunInfo(beginIndex:int, endIndex:int):Array Returns an array of objects that contains information about a run of text. | TextSnapshot
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | hitTestTextNearPos(x:Number, y:Number, maxDistance:Number = 0):Number Lets you determine which character within a TextSnapshot object is on or near the specified x, y coordinates of the movie clip containing the text in the TextSnapshot object. | TextSnapshot
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | setSelectColor(hexColor:uint = 0xFFFF00):void Specifies the color to use when highlighting characters that have been selected with the setSelected() method. | TextSnapshot
|  | setSelected(beginIndex:int, endIndex:int, select:Boolean):void Specifies a range of characters in a TextSnapshot object to be selected or deselected. | TextSnapshot
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Property Detail

### charCount

property

`charCount:int` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

The number of characters in a TextSnapshot object.

Implementation
`public function get charCount():int`

Related API Elements

flash.text.TextSnapshot.getText()
Method Detail

### findText

()
method

`public function findText(beginIndex:int, textToFind:String, caseSensitive:Boolean):int`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Searches the specified TextSnapshot object and returns the position of the first occurrence of `textToFind` found at or after `beginIndex`. If `textToFind` is not found, the method returns `-1`.

Parameters

| `beginIndex:int` — Specifies the starting point to search for the specified text.
| `textToFind:String` — Specifies the text to search for. If you specify a string literal instead of a variable of type String, enclose the string in quotation marks.
| `caseSensitive:Boolean` — Specifies whether the text must match the case of the string in `textToFind`.

Returns

| `int` — The zero-based index position of the first occurrence of the specified text, or -1.

Related API Elements

flash.text.TextSnapshot.getText()

### getSelected

()
method

`public function getSelected(beginIndex:int, endIndex:int):Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Returns a Boolean value that specifies whether a TextSnapshot object contains selected text in the specified range.

To search all characters, pass a value of `0` for `start`, and `charCount` (or any very large number) for `end`. To search a single character, pass the `end` parameter a value that is one greater than the `start` parameter.

Parameters

| `beginIndex:int` — Indicates the position of the first character to be examined. Valid values for `beginIndex` are `0` through `TextSnapshot.charCount - 1`. If `beginIndex` is a negative value, `0` is used.
| `endIndex:int` — A value that is one greater than the index of the last character to be examined. Valid values for `endIndex` are `0` through `charCount`. The character indexed by the `endIndex` parameter is not included in the extracted string. If this parameter is omitted, `charCount` is used. If this value is less than or equal to the value of `beginIndex`, `beginIndex + 1` is used.

Returns

| `Boolean` — A Boolean value that indicates whether at least one character in the given range has been selected by the corresponding `setSelected()` method (`true`); otherwise, `false`.

Related API Elements

flash.text.TextSnapshot.charCount
flash.text.TextSnapshot.getText()
flash.text.TextSnapshot.getSelectedText()
flash.text.TextSnapshot.setSelected()

### getSelectedText

()
method

`public function getSelectedText(includeLineEndings:Boolean = false):String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9., Flash Lite 4

Returns a string that contains all the characters specified by the corresponding `setSelected()` method. If no characters are specified (by the `setSelected()` method), an empty string is returned.

If you pass `true` for `includeLineEndings`, newline characters are inserted in the return string, and the return string might be longer than the input range. If `includeLineEndings` is `false` or omitted, the method returns the selected text without adding any characters.

Parameters

| `includeLineEndings:Boolean` (default = `false`)`` — An optional Boolean value that specifies whether newline characters are inserted into the returned string where appropriate. The default value is `false`.

Returns

| `String` — A string that contains all the characters specified by the corresponding `setSelected()` command.

Related API Elements

flash.text.TextSnapshot.getSelected()
flash.text.TextSnapshot.setSelected()

### getText

()
method

`public function getText(beginIndex:int, endIndex:int, includeLineEndings:Boolean = false):String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9., Flash Lite 4

Returns a string that contains all the characters specified by the `beginIndex` and `endIndex` parameters. If no characters are selected, an empty string is returned.

To return all characters, pass a value of `0` for `beginIndex` and `charCount` (or any very large number) for `endIndex`. To return a single character, pass a value of `beginIndex + 1` for `endIndex`.

If you pass a value of `true` for `includeLineEndings`, newline characters are inserted in the string returned where deemed appropriate. In this case, the return string might be longer than the input range. If `includeLineEndings` is `false` or omitted, the selected text is returned without any characters added.

Parameters

| `beginIndex:int` — Indicates the position of the first character to be included in the returned string. Valid values for `beginIndex` are`0` through `charCount - 1`. If `beginIndex` is a negative value, `0` is used.
| `endIndex:int` — A value that is one greater than the index of the last character to be examined. Valid values for `endIndex` are `0` through `charCount`. The character indexed by the `endIndex` parameter is not included in the extracted string. If this parameter is omitted, `charCount` is used. If this value is less than or equal to the value of `beginIndex`, `beginIndex + 1` is used.
| `includeLineEndings:Boolean` (default = `false`)`` — An optional Boolean value that specifies whether newline characters are inserted (`true`) or are not inserted (`false`) into the returned string. The default value is `false`.

Returns

| `String` — A string containing the characters in the specified range, or an empty string if no characters are found in the specified range.

Related API Elements

flash.text.TextSnapshot.charCount
flash.text.TextSnapshot.getSelectedText()

### getTextRunInfo

()
method

`public function getTextRunInfo(beginIndex:int, endIndex:int):Array`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Returns an array of objects that contains information about a run of text. Each object corresponds to one character in the range of characters specified by the two method parameters.

Note: Using the `getTextRunInfo()` method for a large range of text can return a large object. Adobe recommends limiting the text range defined by the `beginIndex` and `endIndex` parameters.

Parameters

| `beginIndex:int` — The index value of the first character in a range of characters in a TextSnapshot object.
| `endIndex:int` — The index value of the last character in a range of characters in a TextSnapshot object.

Returns

| `Array` — An array of objects in which each object contains information about a specific character in the range of characters specified by the `beginIndex` and `endIndex` parameters. Each object contains the following eleven properties:

- `indexInRun`—A zero-based integer index of the character (relative to the entire string rather than the selected run of text).
- `selected`—A Boolean value that indicates whether the character is selected `true`; `false` otherwise.
- `font`—The name of the character's font.
- `color`—The combined alpha and color value of the character. The first two hexadecimal digits represent the alpha value, and the remaining digits represent the color value.
- `height`—The height of the character, in pixels.
- `matrix_a`, `matrix_b`, `matrix_c`, `matrix_d`, `matrix_tx`, and `matrix_ty`— The values of a matrix that define the geometric transformation on the character. Normal, upright text always has a matrix of the form `[1 0 0 1 x y]`, where `x` and `y` are the position of the character within the parent movie clip, regardless of the height of the text. The matrix is in the parent movie clip coordinate system, and does not include any transformations that may be on that movie clip itself (or its parent).
- `corner0x`, `corner0y`, `corner1x`, `corner1y`, `corner2x`, `corner2y`, `corner3x`, and `corner3y`—The corners of the bounding box of the character, based on the coordinate system of the parent movie clip. These values are only available if the font used by the character is embedded in the SWF file.

Related API Elements

Matrix class

### hitTestTextNearPos

()
method

`public function hitTestTextNearPos(x:Number, y:Number, maxDistance:Number = 0):Number`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9., Flash Lite 4

Lets you determine which character within a TextSnapshot object is on or near the specified `x`, `y` coordinates of the movie clip containing the text in the TextSnapshot object.

If you omit or pass a value of `0` for `maxDistance`, the location specified by the `x`, `y` coordinates must lie inside the bounding box of the TextSnapshot object.

This method works correctly only with fonts that include character metric information; however, by default, the Flash authoring tool does not include this information for static text fields. Therefore, the method might return `-1` instead of an index value. To ensure that an index value is returned, you can force the Flash authoring tool to include the character metric information for a font. To do this, add a dynamic text field that uses that font, select Character Options for that dynamic text field, and then specify that font outlines should be embedded for at least one character. (It doesn't matter which characters you specify, nor whether they are the characters used in the static text fields.)

Parameters

| `x:Number` — A number that represents the `x` coordinate of the movie clip containing the text.
| `y:Number` — A number that represents the `y` coordinate of the movie clip containing the text.
| `maxDistance:Number` (default = `0`)`` — An optional number that represents the maximum distance from `x`, `y` that can be searched for text. The distance is measured from the center point of each character. The default value is `0`.

Returns

| `Number` — A number representing the index value of the character that is nearest to the specified `x`, `y` coordinate. Returns `-1` if no character is found, or if the font doesn't contain character metric information.

Related API Elements

flash.display.DisplayObject.x
flash.display.DisplayObject.y

### setSelectColor

()
method

`public function setSelectColor(hexColor:uint = 0xFFFF00):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9., Flash Lite 4

Specifies the color to use when highlighting characters that have been selected with the `setSelected()` method. The color is always opaque; you can't specify a transparency value.

This method works correctly only with fonts that include character metric information; however, by default, the Flash authoring tool does not include this information for static text fields. Therefore, the method might return `-1` instead of an index value. To ensure that an index value is returned, you can force the Flash authoring tool to include the character metric information for a font. To do this, add a dynamic text field that uses that font, select Character Options for that dynamic text field, and then specify that font outlines should be embedded for at least one character. (It doesn't matter which characters you specify, nor if they are the characters used in the static text fields.)

Parameters

| `hexColor:uint` (default = `0xFFFF00`)`` — The color used for the border placed around characters that have been selected by the corresponding `setSelected()` command, expressed in hexadecimal format (0xRRGGBB).

Related API Elements

flash.text.TextSnapshot.setSelected()

### setSelected

()
method

`public function setSelected(beginIndex:int, endIndex:int, select:Boolean):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9., Flash Lite 4

Specifies a range of characters in a TextSnapshot object to be selected or deselected. Characters that are selected are drawn with a colored rectangle behind them, matching the bounding box of the character. The color of the bounding box is defined by `setSelectColor()`.

To select or deselect all characters, pass a value of `0` for `beginIndex` and `charCount` (or any very large number) for `endIndex`. To specify a single character, pass a value of `start + 1` for `endIndex`.

Because characters are individually marked as selected, you can call this method multiple times to select multiple characters; that is, using this method does not deselect other characters that have been set by this method.

The colored rectangle that indicates a selection is displayed only for fonts that include character metric information; by default, Flash does not include this information for static text fields. In some cases, this behavior means that text that is selected won't appear to be selected onscreen. To ensure that all selected text appears to be selected, you can force the Flash authoring tool to include the character metric information for a font. To do this, add a dynamic text field that uses that font, select Character Options for that dynamic text field, and then specify that font outlines should be embedded for at least one character. It doesn't matter which characters you specify, nor even if they are the characters used in the static text fields in question.

Parameters

| `beginIndex:int` — Indicates the position of the first character to select. Valid values for `beginIndex` are `0` through `charCount - 1`. If `beginIndex` is a negative value, `0` is used.
| `endIndex:int` — An integer that is 1+ the index of the last character to be examined. Valid values for `end` are `0` through `charCount`. The character indexed by the `end` parameter is not included in the extracted string. If you omit this parameter, `TextSnapshot.charCount` is used. If the value of `beginIndex` is less than or equal to the value of `endIndex`, `beginIndex + 1` is used.
| `select:Boolean` — A Boolean value that specifies whether the text should be selected (`true`) or deselected (`false`).

Related API Elements

flash.text.TextSnapshot.charCount
flash.text.TextSnapshot.setSelectColor()

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00