Carbon


ATSUPositionToOffset

Header: ATSUnicode.h Carbon status: Supported

Obtains the edge offset(s) that correspond to the glyph nearest a mouse-down event.

OSStatus ATSUPositionToOffset (
    ATSUTextLayout iTextLayout, 
    ATSUTextMeasurement iLocationX, 
    ATSUTextMeasurement iLocationY, 
    UniCharArrayOffset *ioPrimaryOffset, 
    Boolean *oIsLeading, 
    UniCharArrayOffset *oSecondaryOffset
);
Parameter descriptions
iTextLayout

A reference to an initialized text layout object in which the mouse-down event occurred. You cannot pass NULL for this parameter.

iLocationX

The x-coordinate of the origin (in the current graphics port) of the line where the mouse-down event occurred. Pass the constant kATSUUseGrafPortPenLoc, described in “Current Pen Location and Clear All Constants”, for the location of the mouse-down event relative to the current pen location in the current graphics port.

iLocationY

The y-coordinate of the origin (in the current graphics port) of the line where the mouse-down event occurred. Pass the constant kATSUUseGrafPortPenLoc, described in “Current Pen Location and Clear All Constants”, for the location of the mouse-down event relative to the current pen location in the current graphics port.

ioPrimaryOffset

A pointer to an edge offset. Before calling ATSUPositionToOffset, pass a pointer to the edge offset of the beginning of the line containing the character nearest the mouse-down event. If the line direction is right-to-left, pass the lowest edge offset. On return, a pointer to the edge offset that corresponds to the closest edge of the glyph beneath the hit point on the screen. You cannot pass NULL for this parameter.

oIsLeading

On return, a pointer to a value that indicates whether the offset passed back in the ioPrimaryOffset parameter is leading or trailing. If the pointed to value is true, then the offset is leading (that is, more closely associated with the following character in the backing-store memory). If this value is false, the offset is trailing (that is, more closely associated with the previous character in the backing-store memory). This value indicates the line direction at the location of the mouse-down event.

oSecondaryOffset

On return, a pointer to the edge offset that corresponds to the furthest edge of the glyph beneath the hit point on the screen. This value is the same as passed back in ioPrimaryOffset unless the mouse-down event occurs on a line direction boundary.

function result

A result code. The result code kATSUInvalidCacheErr indicates that an attempt was made to read in style data from an invalid cache (that is, the format of the cached data does not match that used by ATSUI or the cached data is corrupt). The result code kATSUQuickDrawTextErr indicates that the QuickDraw function DrawText encountered an error while measuring a line of text.

DISCUSSION

The ATSUPositionToOffset function passes back the edge offset(s) of the glyph nearest a mouse-down event. If the mouse-down event occurs at a line direction boundary, the ATSUPositionToOffset function passes back two offsets. Line direction boundaries can occur on the trailing edges of two glyphs, the leading edges of two glyphs, or at the beginning or end of a text segment. The value passed back in the oIsLeading parameter indicates the direction of the text at the line direction boundary. If the mouse-down event occurs at a line direction boundary, the ioPrimaryOffset parameter represents the edge offset that corresponds to the closest edge of the glyph beneath the hit point on the screen. In this case, the oSecondaryOffset parameter represents the edge offset that corresponds to the furthest edge of the glyph beneath the hit point on the screen.

The oIsLeading parameter represents the text direction of the primary edge offset. This is determined by the Unicode directionality of the original character in backing-store memory. If oIsLeading passes back true, the primary edge offset is more closely associated with the following character in the backing-store memory. If it passes back false, the primary offset is more closely associated with the previous character in the backing-store memory.

ATSUI does not keep actual line positions. As a result, the coordinates passed in the iLocationX and iLocationY parameters are relative to the position in the current graphics port of the origin of the line in which the mouse-down occurred. The passed back edge offset(s) are thus offsets from the beginning of the line in which the hit occurred, not from the beginning of the text layout object’s buffer.

To transform the hit point’s position, you must first call the GlobalToLocal function to translate the global coordinates passed back in the where field of the event record to local coordinates. You then subtract the hit point (in local coordinates) from the position of the line’s origin in the current graphics port.

For example, if you have a mouse-down event whose position in local coordinates is (75,50), you would subtract this value from the position of the origin of the line in the current graphics port. If the position of the origin of the line in the current graphics port is (50,50), then the relative position of the hit that you would pass in the iLocationX and iLocationY parameters would be (25,0).

The following summarizes the possible outcomes of calling ATSUPositionToOffset:

ATSUPositionToOffset may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.0.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.5 or later.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)