Legacy Document

Inside Macintosh: Text /

Chapter 3 - QuickDraw Text / QuickDraw Text Reference

Routines / Determining the Caret Position, and Selecting and Highlighting Text

HiliteText

The HiliteText procedure finds all the characters between two byte offsets in a text segment whose glyphs are to be highlighted.

PROCEDURE HiliteText (textPtr: Ptr; 
                      textLen, firstOffset, secondOffset: Integer; 
                      VAR offsets: OffsetTable);

textPtr

A pointer to a buffer that contains the text to be highlighted.

textLen

The length in bytes of the entire text segment pointed to by textPtr.

firstOffset

The byte offset from textPtr to the first character to be highlighted.

secondOffset

The byte offset from textPtr to the last character to be highlighted.

offsets

A table that, upon completion of the call, specifies the boundaries of the text to be highlighted.

DESCRIPTION

The HiliteText procedure returns three pairs of byte offsets that mark the onscreen ranges of text to be highlighted. This is because for bidirectional text, although the characters are contiguous in memory, their displayed glyphs can include up to three separate ranges of text.

The HiliteText procedure takes into account the fact that to highlight the complete range of text whose beginning and ending byte offsets you pass it, it must return byte offsets that encompass the glyphs of the first and last characters in the text segment. To determine the correct offset pairs, HiliteText relies on the primary line direction as specified by the SysDirection global variable.

Before calling HiliteText, you must set up an offset table (of type OffsetTable)
in your application to hold the results. You can consider the offset table a set of
three offset pairs:

TYPE OffPair = 
   RECORD
      offFirst:   Integer;
      offSecond:  Integer;
   END;
   OffsetTable = ARRAY [0..2] of OffPair;

If the two offsets in any pair are equal, the pair is empty and you can ignore it. Otherwise the pair identifies a run of characters whose glyphs are to be highlighted.

SPECIAL CONSIDERATIONS

The offsets that HiliteText returns depend on the primary line direction as defined by the SysDirection global variable. If you change the value of SysDirection, HiliteText returns the offset that is meaningful according to the primary line direction for ambiguous offsets on the boundary of right-to-left and left-to-right text.

The HiliteText procedure may move memory; do not call this procedure at interrupt time. For more information, see "Highlighting a Text Selection" on page 3-56.