Legacy Document

Inside Macintosh: Text /

Chapter 5 - Text Utilities / Text Utilities Reference

Routines / Working With Word, Script, and Line Boundaries

StyledLineBreak

The StyledLineBreak function returns the proper location to break a line of text. It breaks the line on a word boundary if possible and allows for multiscript runs and style runs on a single line.

FUNCTION StyledLineBreak(textPtr: Ptr; textLen: LongInt;
                  textStart, textEnd, flags: LongInt;
                  VAR textWidth: Fixed;
                  VAR textOffset: LongInt): StyledLineBreakCode;

textPtr

A pointer to the beginning of a script run on the current line to be broken.

textLen

The number of bytes in the script run on the current line to be broken.

textStart

A byte offset to the beginning of a style run within the script run.

textEnd

A byte offset to the end of the style run within the script run.

flags

Reserved for future expansion; must be 0.

textWidth

The maximum length of the displayed line in pixels. StyledLineBreak decrements this value for its own use. Your responsibility is to set it before your first call to StyledLineBreak for a line.

textOffset

Must be nonzero on your first call to StyledLineBreak for a line, and zero for subsequent calls to StyledLineBreak for that line. This value allows StyledLineBreak to differentiate between the first and subsequent calls, which is important when a long word is found (as described below).

On output, textOffset is the count of bytes from textPtr to the location in the text string where the line break is to occur.

DESCRIPTION

Use the StyledLineBreak function when you are laying out lines in an environment that may include text from multiple scripts. To use this function, you need to understand how QuickDraw draws text, which is described in the chapter "QuickDraw Text" in this book.

You can only use the StyledLineBreak function when you have organized your text in script runs and style runs within each script run. This type of text organization is used by most text-processing applications that allow for multiscript text. Use this function when you are displaying text in a screen area to determine the best place to break each displayed line. For an overview of how to use this function, read the section "Finding Line Breaks" beginning on page 5-24.

What you do is iterate through your text, a script run at a time starting from the first character past the end of the previous line. Use StyledLineBreak to check each style run in the script run (in memory order) until the function determines that it has arrived at a line break. As you loop through each style run, before calling StyledLineBreak, you must set the text values in the graphics port record that are used by QuickDraw to measure the text. These include the font, font size, and font style of the style run. An example of a loop that uses this function is found in Listing 5-4 on page 5-27.

When used with unformatted text, textStart can be 0, and textEnd is identical to textLen. With styled text, the interval between textStart and textEnd specifies a style run. The interval between textPtr and textLen specifies a script run. Note that the style runs in StyledLineBreak must be traversed in memory order, not in display order.

If the current style run is included in a contiguous sequence of other style runs of the same script, then textPtr should point to the start of the first style run of the same script on the line, and textLen should include the last style run of the same script on the line. This is because word boundaries can extend across style runs, but not across script runs.

StyledLineBreak automatically decrements the textWidth variable by the width of the style run for use on the next call. You need to set the value of textWidth before calling it to process a line.

The textOffset parameter must be nonzero for the first call on a line and zero for each call to the function on the line. This allows StyledLineBreak to act differently when a long word is encountered: if the word is in the first style run on the line, StyledLineBreak breaks the line on a character boundary within the word; if the word is in a subsequent style run on the line, StyledLineBreak breaks the line before the start of the word.

When StyledLineBreak finds a line break, it sets the value of textOffset to the count of bytes that can be displayed starting at textPtr.

IMPORTANT

When StyledLineBreak is called for the second or subsequent style runs within a script run, the textOffset value at exit may be less than the textStart parameter (that is, it may specify a line break before the current style run).

Although the offsets are in long integer values and the widths are in fixed values for future extensions, in the current version the long integer values are restricted to the integer range, and only the integer portion of the widths is used.

StyledLineBreak always chooses a line break for the last style run on the line in memory order as if all whitespace in that style run would be stripped. The VisibleLength function, which is a QuickDraw function used to eliminate trailing spaces from a style run before drawing it, can be called for the style run that is at the display end of a line. This leads to a potential conflict when both functions are used with mixed-directional text: if the end of a line in memory order actually occurs in the middle of the displayed line, StyledLineBreak assumes that the whitespace is stripped from that run, but VisibleLength does not strip the characters. The VisibleLength function is described in the chapter "QuickDraw Text" in this book.

The StyledLineBreak result (defined by the StyledLineBreakCode data type) indicates whether the function broke on a word boundary or a character boundary, or if the width extended beyond the edge of the text.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the StyledLineBreak function are

Trap macro	Selector
_ScriptUtil	$821C FFFE

RESULT CODES

BreakOverflow	2	No line break is yet necessary, since the current style run still fits on the line
BreakChar	1	Line breaks on character boundary
BreakWord	0	Line breaks on word boundary

SEE ALSO

For details on the VisibleLength, TextWidth, and PortionText functions, see the chapter "QuickDraw Text" in this book.