Carbon


ATSUGetTextHighlight

Header: ATSUnicode.h Carbon status: Supported

Obtains the highlight region for a range of text.

OSStatus ATSUGetTextHighlight (
    ATSUTextLayout iTextLayout, 
    ATSUTextMeasurement iTextBasePointX, 
    ATSUTextMeasurement iTextBasePointY, 
    UniCharArrayOffset iHighlightStart, 
    UniCharCount iHighlightLength, 
     oHighlightRegion
);
Parameter descriptions
iTextLayout

A reference to an initialized text layout object containing the range of text whose highlight region(s) you wish to determine. You cannot pass NULL for this parameter.

iTextBasePointX

The x-coordinate of the origin (in the current graphics port) of the line containing the range of text whose highlight region(s) you wish to determine. Pass the constant kATSUUseGrafPortPenLoc, described in “Current Pen Location and Clear All Constants”, to obtain the highlighting region relative to the current pen location in the current graphics port.

iTextBasePointY

The y-coordinate of the origin (in the current graphics port) of the line containing the range of text whose highlight region(s) you wish to determine. Pass the constant kATSUUseGrafPortPenLoc, described in “Current Pen Location and Clear All Constants”, to obtain the highlighting region relative to the current pen location in the current graphics port.

iHighlightStart

The edge offset that corresponds to the beginning of the range of text whose highlight region(s) you wish to determine. To specify the beginning of the text buffer, pass the constant kATSUFromTextBeginning, described in “Text Offset and Length Constants”. To indicate the entire text buffer, pass kATSUFromTextBeginning in this parameter and the constant kATSUToTextEnd in the iHighlightLength parameter. If the specified range of text is outside the text buffer, ATSUGetTextHighlight returns the result code kATSUInvalidTextRangeErr.

iHighlightLength

The length of the range of text whose highlight region(s) you wish to determine. If you want the length to extend to the end of the text buffer, pass the constant kATSUToTextEnd, described in “Text Offset and Length Constants”. To indicate the entire text buffer, pass kATSUToTextEnd in this parameter and the constant kATSUFromTextBeginning in the iHighlightStart parameter. If the specified range of text is outside the text buffer, ATSUGetTextHighlight returns the result code kATSUInvalidTextRangeErr.

oHighlightRegion

A handle to the highlight region(s). Before calling ATSUGetTextHighlight, create a region handle by calling the NewRgn function. On return, a handle to a structure that contains the highlight region for the text. In the case of discontiguous highlighting, the region consists of multiple components, with the rgnBBox field specifying the bounding box around the entire area of discontiguous highlighting. You cannot pass NULL for this parameter.

function result

A result code. The result code kATSUCoordinateOverflowErr indicate that the coordinates passed in the iTextBasePointX and iTextBasePointY parameters caused a coordinate overflow. The result code kATSUInvalidCacheErr indicates that an attempt was made to read in style data from an invalid cache. This may be because 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 ATSUGetTextHighlight function determines the highlight region for a range of text, but does not highlight the text. To highlight text, call the function ATSUHighlightText.

When there are discontiguous highlighting regions, the structure passed back in the oHighlightRegion parameter is made up of multiple components. The rgnBBox field of the structure represents the bounding box around the entire area of discontiguous highlighting.

ATSUGetTextHighlight uses the previously set line ascent and descent values to calculate the height of the highlight region. If these values have not been set for the line, ATSUGetTextHighlight uses the line ascent and descent values set for the text layout object containing the line. If these are not set, it uses the default values.

ATSUGetTextHighlight 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. When there are discontiguous highlighting regions, the structure passed back in the oHighlightRegion parameter is made up of multiple components. In ATSUI 1.1, the maximum number of components that can be passed back is 31. In ATSUI 1.2, the maximum number of components is 127.

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)