TextSnapshot


Object   |   +-TextSnapshot public class TextSnapshot extends Object

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

You don't use a constructor to create a TextSnapshot object; it is returned by the MovieClip.getTextSnapshot() method.

Availability: ActionScript 1.0; Flash Player 7 - The SWF file must be published for Flash Player 6 or later, and must be played in Flash Player 7 or later.

See also

getTextSnapshot (MovieClip.getTextSnapshot method)

Property summary

Properties inherited from class Object

constructor (Object.constructor property), __proto__ (Object.__proto__ property), prototype (Object.prototype property), __resolve (Object.__resolve property)


Method summary

Modifiers

Signature

Description

 

findText (startIndex:Number, textToFind:String, caseSensitive:Boolea n) : Number

Searches the specified TextSnapshot object and returns the position of the first occurrence of textToFind found at or after startIndex.

 

getCount() : Number

Returns the number of characters in a TextSnapshot object.

 

getSelected (start:Number, [end:Number]) : Boolean

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

 

getSelectedText ([includeLineEndings:Boolean]) : String

Returns a string that contains all the characters specified by the corresponding TextSnapshot.setSelected() method.

 

getText (start:Number, end:Number, [includeLineEndings:Boolean]) : String

Returns a string that contains all the characters specified by the start and end parameters.

 

getTextrunInfo (beginIndex:Number,endIndex:Number) : Array

Returns an array of objects that contains information about a run of text.

 

hitTestTextNearPos (x:Number, y:Number,[closeDist:Number]) : 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.

 

setSelectColor (color:Number) : Void

Specifies the color to use when highlighting characters that were selected with the TextSnapshot.setSelected() method.

 

setSelected (start:Number, end:Number,select:Boolean) : Void

Specifies a range of characters in a TextSnapshot object to be selected or not.


Methods inherited from class Object

addProperty (Object.addProperty method), hasOwnProperty (Object.hasOwnProperty method), isPropertyEnumerable (Object.isPropertyEnumerable method), isPrototypeOf (Object.isPrototypeOf method), registerClass (Object.registerClass method), toString (Object.toString method), unwatch (Object.unwatch method), valueOf (Object.valueOf method), watch (Object.watch method)


findText (TextSnapshot.findText method)

public findText(startIndex:Number, textToFind:String,   caseSensitive:Boolean) : Number

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

Availability: ActionScript 1.0; Flash Player 7 - The SWF file must be published for Flash Player 6 or later, and must be played in Flash Player 7 or later.

Parameters

startIndex:Number - Specifies the starting index point in the TextSnapshot text at which to search for the specified text.

textToFind:String - The text to search for. Specify either a String literal (enclosed in quotation marks) or a variable.

caseSensitive:Boolean - Boolean value that specifies whether the found text must match the case of the string in textToFind (TRue); otherwise false.

Returns

Number - The zero-based index position of the first occurrence of the specified text, or -1 if no text matched.

Example

The following example illustrates how to use this method. To use this code, place a static text field that contains the text "TextSnapshot Example" on the Stage.

var my_mc:MovieClip = this; var my_snap:TextSnapshot = my_mc.getTextSnapshot(); var index1:Number = my_snap.findText(0, "Snap", true); var index2:Number = my_snap.findText(0, "snap", true); var index3:Number = my_snap.findText(0, "snap", false); trace(index1); // 4 trace(index2); // -1 trace(index3); // 4

See also

getText (TextSnapshot.getText method)

getCount (TextSnapshot.getCount method)

public getCount() : Number

Returns the number of characters in a TextSnapshot object.

Availability: ActionScript 1.0; Flash Player 7 - The SWF file must be published for Flash Player 6 or later, and must be played in Flash Player 7 or later.

Returns

Number - The number of characters in the TextSnapshot object.

Example

The following example illustrates how you can return the number of characters in a TextSnapshot object. To use this code, place one static text field that contains the text "TextSnapshot Example" (and only that text) on the Stage.

var my_mc:MovieClip = this; var my_snap:TextSnapshot = my_mc.getTextSnapshot(); var count:Number = my_snap.getCount(); var theText:String = my_snap.getText(0, count, false); trace(count); // 20 trace(theText); // TextSnapshot Example

See also

getText (TextSnapshot.getText method)

getSelected (TextSnapshot.getSelected method)

public getSelected(start:Number, [end:Number]) : Boolean

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 TextSnapshot.getCount() (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.

Availability: ActionScript 1.0; Flash Player 7 - The SWF file must be published for Flash Player 6 or later, and must be played in Flash Player 7 or later.

Parameters

start:Number - The index position of the first character to be examined. Valid values for start are 0 through TextSnapshot.getCount() - 1. If start is a negative value, 0 is used.

end:Number [optional] - The index position that is one greater than the last character to be examined. Valid values for end are 0 through TextSnapshot.getCount(). The character indexed by the end parameter is not included in the extracted string. If you omit this parameter, TextSnapshot.getCount() is used. If the value of end is less than or equal to the value of start, start + 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 TextSnapshot.setSelected() method (true); otherwise, false.

Example

The following example illustrates how to use this method. To use this code, place a static text field that contains the text "TextSnapshot Example" on the Stage. In the library, include the font used by the static text field, and in Linkage options for the font, select Export for ActionScript. Add the following ActionScript to Frame 1 of the Timeline:

var my_snap:TextSnapshot = this.getTextSnapshot(); var count:Number = my_snap.getCount(); my_snap.setSelected(0, 4, true); my_snap.setSelected(1, 2, false); var firstCharIsSelected:Boolean = my_snap.getSelected(0, 1); var secondCharIsSelected:Boolean = my_snap.getSelected(1, 2); trace(firstCharIsSelected); // true trace(secondCharIsSelected); // false

See also

getCount (TextSnapshot.getCount method), getText (TextSnapshot.getText method), getSelectedText (TextSnapshot.getSelectedText method), setSelected (TextSnapshot.setSelected method)

getSelectedText (TextSnapshot.getSelectedText method)

public getSelectedText([includeLineEndings:Boolean]) : String

Returns a string that contains all the characters specified by the corresponding TextSnapshot.setSelected() method. If no characters are specified (by the TextSnapshot.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.

Availability: ActionScript 1.0; Flash Player 7 - The SWF file must be published for Flash Player 6 or later, and must be played in Flash Player 7 or later.

Parameters

includeLineEndings:Boolean [optional] - A 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 that contains all the characters specified by the corresponding TextSnapshot.setSelected() method.

Example

The following example illustrates how to use this method. To use this code, place a static text field that contains the text "TextSnapshot Example" on the Stage. Then in the Library, include the font used by the static text field, and in Linkage options for the font, select Export for ActionScript. Add the following ActionScript to Frame 1 of the Timeline:

var my_snap:TextSnapshot = this.getTextSnapshot(); var count:Number = my_snap.getCount(); my_snap.setSelected(0, 4, true); my_snap.setSelected(1, 2, false); var theText:String = my_snap.getSelectedText(false); trace(theText); // Text

When you test the SWF file, a colored rectangle surrounds the specified characters.

See also

getSelected (TextSnapshot.getSelected method), setSelected (TextSnapshot.setSelected method)

getText (TextSnapshot.getText method)

public getText(start:Number, end:Number, [includeLineEndings:Boolean]) :   String

Returns a string that contains all the characters specified by the start and end parameters. If no characters are specified, the method returns an empty string.

To return all characters, pass a value of 0 for start, and TextSnapshot.getCount() (or any very large number) for end. To return a single character, pass a value of start +1 for end.

If you pass TRue for includeLineEndings, newline characters are inserted in the return string where deemed appropriate, 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.

Availability: ActionScript 1.0; Flash Player 7 - The SWF file must be published for Flash Player 6 or later, and must be played in Flash Player 7 or later.

Parameters

start:Number - An integer that indicates the position of the first character to be included in the returned string. Valid values for start are 0 through TextSnapshot.getCount() - 1. If start is a negative value, 0 is used.

end:Number - An integer that is 1 + the index of the last character to be examined in the TextSnapshot object. Valid values for end are 0 through TextSnapshot.getCount(). The character indexed by the end parameter is not included in the extracted string. If you omit this parameter, TextSnapshot.getCount() is used. If the value of end is less than or equal to the value of start, start + 1 is used.

includeLineEndings:Boolean [optional] - A 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 that contains the characters in the specified range, or an empty string if no characters are found in the specified range.

Example

The following example illustrates how you can return the number of characters in a specified TextSnapshot object. To use this code, place a static text field that contains the text "TextSnapshot Example" on the Stage.

var my_mc:MovieClip = this; var my_snap:TextSnapshot = my_mc.getTextSnapshot(); var count:Number = my_snap.getCount(); var theText:String = my_snap.getText(0, count, false); trace(count); // 20 trace(theText); // TextSnapshot Example

See also

getCount (TextSnapshot.getCount method), getSelectedText (TextSnapshot.getSelectedText method)

getTextRunInfo (TextSnapshot.getTextRunInfo method)

public getTextRunInfo(beginIndex:Number, endIndex:Number) : Array

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. Macromedia recommends limiting the text range defined by the beginIndex and endIndex parameters.


Availability: ActionScript 1.0; Flash Player 7 - The SWF file must be published for Flash Player 6 or later, and must be played in Flash Player 7r19 or later.

Parameters

beginIndex:Number - The index value of the first character in the range of characters.

endIndex:Number - The index value of the last character in the range of characters.

Returns

Array - An array of objects in which each object contains information about a specific character in the specified range. Each object contains the following 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 hexidecimal digits represent the alpha value, and the remaining digits represent the color value. (The example includes a method for converting decimal values to hexidecimal values.)

  • 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.

Example

The following example illustrates how to use this method. To use this code, on the Stage create a static text field that contains the text "AB". Rotate the text field by 45 degrees, and set the second character to be superscript with a color of 0xFFFFFF with a 50% alpha, as the following figure shows:

The following script lists the getTexTRunInfo() properties of each character in the text field:

var myTS:TextSnapshot = this.getTextSnapshot(); var myArray:Array = myTS["getTextRunInfo"](0, myTS.getCount()); for (var i = 0; i < myTS.getCount(); i++) {   trace("indexInRun: " + myArray[i].indexInRun);   trace("selected: " + myArray[i].selected);   trace("font: " + myArray[i].font);   trace("color: " + decToHex(myArray[i].color));   trace("height: " + myArray[i].height);   trace("matrix_a: " + myArray[i].matrix_a);   trace("matrix_b: " + myArray[i].matrix_b);   trace("matrix_c: " + myArray[i].matrix_c);   trace("matrix_d: " + myArray[i].matrix_d);   trace("matrix_ty: " + myArray[i].matrix_tx);   trace("matrix_tx: " + myArray[i].matrix_ty);   trace(" "); } function decToHex(dec:Number) {   var hexString:String = "";   if (dec > 15) {     hexString = decToHex(Math.floor(dec / 16));   }   var hexDigit = dec - 16 * (Math.floor(dec / 16));     if (hexDigit > 9) {       hexDigit = String.fromCharCode(hexDigit + 55);     }     hexString = hexString + hexDigit;     return hexString; }

This creates the following output:

indexInRun: 0 selected: false font: Times New Roman color: FF000000 height: 28.6 matrix_a: 0.0316612236983293 matrix_b: 0.0385940558426864 matrix_c: -0.0385940558426864 matrix_d: 0.0316612236983293 matrix_ty: 22.75 matrix_tx: 40.35 indexInRun: 0 selected: false font: Times New Roman color: 80000000 height: 28.6 matrix_a: 0.0316612236983293 matrix_b: 0.0385940558426864 matrix_c: -0.0385940558426864 matrix_d: 0.0316612236983293 matrix_ty: 49 matrix_tx: 45.5

This example uses a decToHex() method to convert the decimal value of the color property to a hexidecimal value.

See also

Matrix (flash.geom.Matrix)

hitTestTextNearPos (TextSnapshot.hitTestTextNearPos method)

public hitTestTextNearPos(x:Number, y:Number, [closeDist:Number]) : 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.

If you omit or pass a value of 0 for closeDist, 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, Macromedia Flash 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.)

Availability: ActionScript 1.0; Flash Player 7 - The SWF file must be published for Flash Player 6 or later, and must be played in Flash Player 7 or later.

Parameters

x:Number - The x coordinate of the movie clip that contains the text in the TextSnapshot object.

y:Number - The y coordinate of the movie clip that contains the text in the TextSnapshot object.

closeDist:Number [optional] - The maximum distance from x, y that can be searched for text. The distance is measured from the centerpoint of each character. The default value is 0.

Returns

Number - The index value of the character in the TextSnapshot object that is nearest to the specified x, y coordinate. The method returns -1 if no character is found, or if the font doesn't contain character metric information.

Example

The following example illustrates how to use this method. To use this code, place a static text field that contains the text "TextSnapshot Example" on the Stage. In the library, include the font used by the static text field, and in Linkage options for the font, select Export for ActionScript. To test the code, run the SWF file and point the mouse pointer to the onscreen text.

var my_ts:TextSnapshot = getTextSnapshot(); this.onMouseMove = function() {   var hitIndex:Number = my_ts.hitTestTextNearPos(_xmouse, _ymouse, 0);   my_ts.setSelected(0, my_ts.getCount(), false);   if (hitIndex >= 0) {     my_ts.setSelected(hitIndex, hitIndex + 1, true);   } };

See also

getTextSnapshot (MovieClip.getTextSnapshot method), _x (MovieClip._x property), _y (MovieClip._y property)

setSelectColor (TextSnapshot.setSelectColor method)

public setSelectColor(color:Number) : Void

Specifies the color to use when highlighting characters that were selected with the TextSnapshot.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, Macromedia Flash 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.)

Availability: ActionScript 1.0; Flash Player 7 - The SWF file must be published for Flash Player 6 or later, and must be played in Flash Player 7 or later.

Parameters

color:Number - The color used for the border placed around characters that have been selected by the corresponding TextSnapshot.setSelected() method, expressed in 0x RRGGBB format.

Example

The following example illustrates how to use this method. To use this code, place a static text field that contains the text "TextSnapshot Example" on the Stage. In the library, include the font used by the static text field, and in Linkage options for the font, select Export for ActionScript. Add the following ActionScript to Frame 1 of the Timeline:

var my_snap:TextSnapshot = this.getTextSnapshot(); var count:Number = my_snap.getCount(); my_snap.setSelectColor(0xFF0000); my_snap.setSelected(0, 4, true); my_snap.setSelected(1, 2, false); var theText:String = my_snap.getSelectedText(false); // get the selected   text trace(theText); // Text

When you test the SWF file, you see a colored rectangle surrounds the specified characters.

See also

setSelected (TextSnapshot.setSelected method)

setSelected (TextSnapshot.setSelected method)

public setSelected(start:Number, end:Number, select:Boolean) : Void

Specifies a range of characters in a TextSnapshot object to be selected or not. 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 TextSnapshot.setSelectColor().

To select or deselect all characters, pass a value of 0 for start and TextSnapshot.getCount() (or any very large number) for end. To specify a single character, pass a value of start + 1 for end.

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.

This method works correctly only with fonts that include character metric information; by default, Flash does not include this information for static text fields. Therefore, text that is selected might not 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, in the library, include the font used by the static text field, and in Linkage options for the font, select Export for ActionScript.

Availability: ActionScript 1.0; Flash Player 7 - The SWF file must be published for Flash Player 6 or later, and must be played in Flash Player 7 or later.

Parameters

start:Number - The position of the first character to select. Valid values for start are 0 tHRough TextSnapshot.getCount() - 1. If start is a negative value, 0 is used.

end:Number - An integer that is 1+ the index of the last character to be examined. Valid values for end are 0 through TextSnapshot.getCount(). The character indexed by the end parameter is not included in the extracted string. If you omit this parameter, TextSnapshot.getCount() is used. If the value of end is less than or equal to the value of start, start + 1 is used.

select:Boolean - A Boolean value that specifies whether the text should be selected (true) or not (false).

Example

The following example illustrates how to use this method. To use this code, place a static text field that contains the text "TextSnapshot Example" on the Stage. In the library, include the font used by the static text field, and in Linkage options for the font, select Export for ActionScript. Add the following ActionScript to Frame 1 of the Timssseline:

var my_snap:TextSnapshot = this.getTextSnapshot(); var count:Number = my_snap.getCount(); my_snap.setSelected(0, 4, true); my_snap.setSelected(1, 2, false); var theText:String = my_snap.getSelectedText(false); trace(theText); // Text

See also

getCount (TextSnapshot.getCount method)



ActionScript 2.0 Language Reference for Macromedia Flash 8
ActionScript 2.0 Language Reference for Macromedia Flash 8
ISBN: 0321384040
EAN: 2147483647
Year: 2004
Pages: 113

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net