Legacy Document

Inside Macintosh: Text /

Chapter 3 - QuickDraw Text / QuickDraw Text Reference

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

CharToPixel

The CharToPixel function returns the screen pixel width from the left edge of a text segment to the glyph of the character whose byte offset you specify.

FUNCTION CharToPixel (textBuf: Ptr; textLen: LongInt; 
                      slop: Fixed; offset: LongInt; 
                      direction: Integer; 
                      styleRunPosition: JustStyleCode;
                      numer: Point; denom: Point): Integer;

textBuf

A pointer to the beginning of the text segment.

textLen

The length in bytes of the entire text segment pointed to by textBuf. The CharToPixel function requires the context of the complete text 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.

offset

The offset from textBuf to the character within the text segment whose display pixel location is to be measured. For 2-byte script systems, if the character whose position is to be measured is 2 bytes long, this is the offset of the first byte.

direction

This parameter specifies whether CharToPixel is to return the caret position for a character with a direction of left-to-right or right-to-left. A direction value of hilite indicates that CharToPixel is to use the caret position for the character direction that matches the primary line direction as specified by the SysDirection global variable.

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 use CharToPixel to find the onscreen pixel location at which to draw a caret and to identify the selection points for highlighting. The CharToPixel function returns the horizontal distance in pixels from the start of the range of text beginning with the byte offset at textBuf to the glyph corresponding to the character whose byte offset is specified by the offset parameter. The pixel location is relative to the beginning of the text segment, not the left margin of the display line. To get the actual display line pixel location of the glyph relative to the left margin, you add the pixel value that CharToPixel returns to the pixel location at the end of the previous style run (on the left) in display order. In other words, you need to know the length of the text in pixels on the display line up to the beginning of the range of text that you call CharToPixel for, and then you add in the screen pixel width that CharToPixel returns.

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, which is part of the line. Do not confuse the textLen parameter with the offset, which is the byte offset of the character within the text segment whose pixel location CharToPixel is to return.

If you use CharToPixel to get a caret position to mark the insertion point, you specify a value of leftCaret or rightCaret for the direction parameter. You can use the value of the PixelToChar leadingEdge flag to determine the direction parameter value.

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 can use the following constants to specify a value for direction.

Constant	Value	Meaning
leftCaret	0	Place caret for left-to-right text direction.
rightCaret	-1	Place caret for right-to-left text direction.
hilite	1	Specifies that the caret position should be determined according to the primary line direction, based on the value of SysDirection.

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 CharToPixel that you pass to any of the other justification routines for this style run.

For more information about CharToPixel see "Drawing Carets and Highlighting" on page 3-46.

SPECIAL CONSIDERATIONS

The CharToPixel function works with text in all script systems. For 1-byte contextual script systems, CharToPixel calculates the widths of any ligatures, reversals, and compound characters that need to be drawn.

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

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