![]() |
ATSUOffsetToPosition |
||||
Header: | ATSUnicode.h | Carbon status: | Supported | |
Determines the caret position(s) that correspond to an edge offset.
OSStatus ATSUOffsetToPosition ( ATSUTextLayout iTextLayout, UniCharArrayOffset iOffset, Boolean iIsLeading, ATSUCaret *oMainCaret, ATSUCaret *oSecondCaret, Boolean *oCaretIsSplit );
A reference to an initialized text layout object in which the mouse-down event occurred. You cannot pass NULL for this parameter.
The edge offset corresponding to the caret position you want to determine. If you wish to visually respond to a mouse-down event, pass the offset passed back in the ioPrimaryOffset parameter of the function ATSUPositionToOffset.
A value that indicates whether the edge offset is leading or trailing. Note that this value is only relevant if the edge offset occurs at a line direction boundary. Pass true if the edge offset is leading. In this case, it corresponds to the first offset of the line whose origin is specified in the iLocationX and iLocationY parameters. Pass false if the edge offset is trailing. In this case, it corresponds to the last offset of the line whose origin is specified in the iLocationX and iLocationY parameters. The last offset has a value equal to the sum of the starting edge offset and line length.
On return, a pointer to a structure that contains the starting and ending pen locations of the high caret if the value passed back in oCaretIsSplit is true. If the passed back value is false, the structure contains the starting and ending pen locations of the main caret.
On return, a pointer to a structure that contains the starting and ending pen locations of the low caret if the value passed back in oCaretIsSplit is true. If the passed back value is false, the structure contains the starting and ending pen locations of the main caret. This is the same as the oMainCaret parameter.
On return, a pointer to a value that indicates whether the edge offset specified in iOffset occurs at a line direction boundary. If true, the offset occurs at a line direction boundary; otherwise, false.
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.
The user expects that pressing the mouse button correlates to the display of a caret in text. Your application should call the ATSUOffsetToPosition function to find the caret position(s) corresponding to a mouse-down event.
To determine caret position(s), you must first pass the location of the mouse-down event to the function ATSUPositionToOffset. ATSUPositionToOffset passes back the edge offset (or offsets, if the hit occurs on a line direction boundary) from the beginning of the line where the hit occurred.
The offset passed back by ATSUPositionToOffset is given relative to the beginning of the line in which the hit occurred, not from the beginning of the text layout objects buffer. Because this offset is a relative position, you must transform the starting and ending pen locations of the caret(s) that are passed back by ATSUOffsetToPosition before drawing them. The passed back carets do not need to be transformed to reflect angled and split caret appearances.
To do so, add the starting and ending caret coordinates to the coordinates of the origin of the line (in the current graphics port) in which the hit occurred. For example, if ATSUOffsetToPosition passed back the starting and ending pen locations of (25,0), (25,25) in the oMainCaret parameter (and the oSecondCaret parameter contained the same coordinates, meaning that the caret was not split), you would add these to the position of the origin of the line in the graphics port. If the position of the line origin was at (50,50), then the starting and ending pen locations of the caret on the screen would be (75,50), (75,75).
To draw the caret, you can call the QuickDraw functions MoveTo and LineTo, or equivalent functions.
ATSUOffsetToPosition may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.
Available beginning with ATSUI 1.0.
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)