Legacy Document

Inside Macintosh: Text /

Chapter 3 - QuickDraw Text / QuickDraw Text Reference

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

PixelToChar

The PixelToChar function returns the byte offset of a character in a style run, or part of a style run, whose onscreen glyph is nearest the place where the user clicked the mouse.

FUNCTION PixelToChar (textBuf: Ptr; textLen: LongInt; 
                      slop: Fixed; pixelWidth: Fixed; 
                      VAR leadingEdge: Boolean; 
                      VAR widthRemaining: Fixed;
                      styleRunPosition: JustStyleCode; 
                      numer: Point; denom: Point): Integer;

textBuf

A pointer to the start of the text segment.

textLen

The length in bytes of the entire text segment pointed to by textBuf. The PixelToChar function requires the context of the complete text segment in order to determine the correct value.

slop

The amount of slop for the text to be drawn. A positive value extends the text segment; a negative value condenses the text segment.

pixelWidth

The screen location of the glyph associated with the character whose byte offset is to be returned. The screen location is measured in pixels beginning from the left edge of the text segment for which you
call PixelToChar.

leadingEdge

A Boolean flag that, upon completion of the call, is set to TRUE if the pixel location is on the leading edge of the glyph, and FALSE if the pixel location is on the trailing edge of the glyph. The leading edge is the left side if the direction of the character that the glyph represents is left-to-right (such as a Roman character), and the right side if the character direction is right-to-left (such as an Arabic or a Hebrew letter).

widthRemaining

Upon completion of the call, contains -1 if the pixel location (specified by the pixelWidth parameter) falls within the style run (represented by the textLen bytes starting at textBuf). Otherwise, contains the amount of pixels by which the input pixel location (pixelWidth) extends beyond the right edge of the text for which you called PixelToChar.

styleRunPosition

The position on the line of this style run. The style run can be the only one on the line, the leftmost on the line, the rightmost on the line, or one between two other style runs.

numer

A point giving the numerator for the horizontal and vertical
scaling factors.

denom

A point giving the denominator for the horizontal and vertical
scaling factors.

DESCRIPTION

You can use the information that PixelToChar returns for highlighting, word selection, and identifying the caret position. The PixelToChar function returns a byte offset and a Boolean value that describes whether the pixel location is on the leading edge or trailing edge of the glyph where the mouse-down event occurred. When the pixel location falls on a glyph that corresponds to one or more characters that are part of the text segment, the PixelToChar function uses the direction of the character or characters to determine which side of the glyph is the leading edge. (A glyph can represent more than one character, for example, for a ligature. Generally, if a glyph represents more than one character, all of the characters have the same text direction.)

If the pixel location is on the leading edge, PixelToChar returns the byte offset
of the character whose glyph is at the pixel location. (If the glyph represents multiple characters, it returns the byte offset of the first of these characters in memory.) If the pixel location is on the trailing edge, PixelToChar returns the byte offset of the first character in memory following the character or characters represented by the glyph. If the pixel location is on the trailing edge of the glyph that corresponds to the last character
in the text segment, PixelToChar returns a byte offset equal to the length of the
text segment.

When the pixel location is before the leading edge of the first glyph in the displayed text segment, PixelToChar returns a leading edge value of FALSE and the byte offset of the first character. When the pixel location is after the trailing edge of the last glyph in the displayed text segment, PixelToChar returns a leading edge value of TRUE and the next byte offset in memory, the one after the last character in the text segment. If the primary line direction is left to right, before means to the left of all of the glyphs for the characters in the text segment, and after means to the right of all these glyphs. If the primary line direction is right to left, before and after hold the opposite meanings.

You also use the value of the leadingEdge flag to help determine the value of the direction parameter to pass to CharToPixel, which you call to get the caret position. If the leadingEdge flag is FALSE, you base the value of the direction parameter on the direction of the character at the byte offset in memory that precedes the one that PixelToChar returns; if leadingEdge is TRUE, you base the value of the direction parameter on the direction of the character at the byte offset that PixelToChar returns. If there isn't a character at the byte offset, you base the value of the direction parameter on the primary line direction as determined by the SysDirection
global variable.

You specify a value for textLen that is equal to the entire visible part of the style run on a line and includes trailing spaces if and only if they are displayed. They may not be displayed, for example, for the last style run in memory order that is part of the
current line.

For more information about the scaling factors, see "The numer and denom Parameters" on page 3-64. See "The styleRunPosition Parameter" on page 3-63 for a description of the styleRunPosition parameter and the values it takes. See "The slop Parameter" on page 3-63 for more information about the slop parameter.

Note

Be sure to pass the same values for styleRunPosition and the scaling factors (numer and denom) to PixelToChar that you pass to any of the other justification routines for this style run.

You pass PixelToChar a pointer to the byte offset of the character in the text buffer that begins the text segment or style run containing the character whose glyph is at the pixel location. If you do not know which style run on the display line contains the character whose glyph is at the pixel location, you can loop through the style runs until you find the one that contains the pixel location. If the style run contains the character, PixelToChar returns its byte offset. If it doesn't, you can use the widthRemaining parameter value to help determine which style run contains the glyph at the pixel location.

If you pass PixelToChar the pixel width of the display line, you can use the returned value of widthRemaining to calculate the length of a style run. The widthRemaining parameter contains the length in pixels from the end of the style run for which you call PixelToChar to the end of the display line, in this case, if the style run for which you call it does not include the byte offset whose glyph corresponds to the pixel location. You subtract the returned widthRemaining value from the screen pixel width of the display line to get the style run's length.

To truncate a line of text, you can use PixelToChar to find the byte offset of the character where the line should be broken. To return the correct byte offset associated with the pixel location of a mouse-down event when the text belongs to a right-to-left script system, the PixelToChar function reorders the text. If right-to-left text is reordered when you use PixelToChar to determine where to break a line, it returns the wrong byte offset. To get the correct result, you must turn off reordering before you call PixelToChar. Remember to restore reordering after you have determined where to break the line. See "Using Scaled Text" beginning on page 3-43 for more information.

SPECIAL CONSIDERATIONS

The PixelToChar function works with text in all script systems, and for text that is justified or not. For contextual script systems, PixelToChar takes into account the widths of any ligatures, reversals, and compound characters that were created when the text was drawn.

Because 2-byte script systems also include characters consisting of only one byte, you should not simply multiply the number of characters by 2 to determine this value; you must determine and specify the correct number of bytes.

The PixelToChar function may move memory; do not call this procedure at
interrupt time.