Carbon


ATSUBreakLine

Header: ATSUnicode.h Carbon status: Supported

Suggests and optionally sets a soft line break in a range of text.

OSStatus ATSUBreakLine (
    ATSUTextLayout iTextLayout, 
    UniCharArrayOffset iLineStart, 
    ATSUTextMeasurement iLineWidth, 
    Boolean iUseAsSoftLineBreak, 
    UniCharArrayOffset *oLineBreak
);
Parameter descriptions
iTextLayout

A reference to an initialized text layout object containing the range of text whose optimal line break you wish to calculate. You cannot pass NULL for this parameter.

iLineStart

The edge offset that corresponds to the beginning of the range of text whose optimal line break you wish to calculate. On subsequent calls, pass the value passed back in the oLineBreak parameter in the previous call to ATSUBreakLine. To specify the beginning of the text buffer, pass the constant kATSUFromTextBeginning, described in “Text Offset and Length Constants”. If the specified range of text is outside the text buffer, ATSUBreakLine returns the result code kATSUInvalidTextRangeErr.

iLineWidth

The width of the line from the offset you specify in the iLineStart parameter. You must pass a nonzero value. If you want the line width set for the line in the previous call to ATSUBreakLine, pass the constant kATSUUseLineControlWidth, described in “Line Layout Width Constant”.

iUseAsSoftLineBreak

A value indicating whether ATSUBreakLine should set the line break passed back in the oLineBreak parameter. If true, ATSUBreakLine will set the line break.

oLineBreak

On return, a pointer to the edge offset that corresponds to the recommended line break. If the line break occurs in the middle of the word, ATSUBreakLine passes back the location of the soft line break and returns the result code kATSULineBreakInWord. If ATSUBreakLine passes back the same value as specified in iLineStart, you have made an input parameter error. In this case, check to make sure that the line width specified in iLineWidth is big enough for ATSUBreakLine to perform line breaking. ATSUBreakLine will not return an error in this case.

function result

A result code. The result code kATSUQuickDrawTextErr indicates that the QuickDraw function DrawText encounters an error rendering or measuring a line of ATSUI text.

DISCUSSION

The ATSUBreakLine function suggests and optionally sets a soft line break in a line based on the line width specified in iLineWidth.

Before calculating soft line breaks, ATSUBreakLine turns off any previously set line justification, rotation, width alignment, descent, and ascent values and treats the text as a single line. It then examines the text layout object to make sure that the style runs cover the entire range of text. If there are gaps between style runs, ATSUBreakLine assigns the characters in the gap to the style run following the gap. If there is no style run at the beginning of the range of text, ATSUBreakLine assigns these characters to the first style run it can find. If there no style run at the end of the range of text, ATSUBreakLine assigns the remaining characters to the last style run it can find.

You should call ATSUBreakLine when the user inserts or deletes text or changes text layout attributes that affect how glyphs are laid out. If the user changes attributes that don’t affect glyph layout, it will pass back the previously set soft line breaks. You should call ATSUBreakLine repeatedly until it does not find any more soft line breaks.

If ATSUBreakLine does not encounter a hard line break, it uses the line width you specify to determine how many characters can fit on a line. If you pass true for iUseAsSoftLineBreak, it uses the soft line break it calculated to perform line layout on the characters. ATSUBreakLine then determines whether the characters still fit within the line. This is necessary due to end-of-line effects like swashes. When ATSUBreakLine sets a soft line break, it clear previously set soft line breaks in the line.

To implement word break hyphenation, pass false to the iUseAsSoftLineBreak parameter and call the function ATSUSetSoftLineBreak.

ATSUBreakLine suggests a soft line break each time it encounters a hard line break character like a carriage return, line feed, form feed, line separator, or paragraph separator.

ATSUBreakLine may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

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)