User Guide

972 Chapter 2: ActionScript Language Reference
TextSnapshot.hitTestTextNearPos()
Availability
Authoring: Flash MX 2004.
Playback: SWF files published for Flash Player 6 or later, playing in Flash Player 7 or later.
Usage
my_snap.hitTestTextNearPos(x:Number, y:Number [, maxDistance:Number] ) :
Number
Parameters
x
A number that represents the x coordinate of the movie clip containing the text in my_snap.
y A number that represents the x coordinate of the movie clip containing the text in my_snap.
maxDistance An optional number that represents 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
An integer representing the index value of the character in my_snap 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 (see “Description”).
Description
Method; lets you determine which character within a TextSnapshot object is on or near specified
x, y coordinates of the movie clip containing the text in my_snap.
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
my_snap.
This method functions correctly 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 the method returns -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 character(s) you specify, nor even if they are the characters used
in the static text fields in question.
Example
The following example illustrates how to use this method. To use this code, place a static text field
containing the text “TextSnapshot Example” on the Stage. To test the code, move the pointer over
the static text field.
Note: If characters don’t appear to be selected when you run the code, you must also place a
dynamic text field on the Stage. See “Description” in this entry.
// this example assumes that the movie clip contains
// the static text "TextSnapshot Example"