Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

Breaking Lines

ATSUI provides two functions for calculating and setting soft line breaks programmatically: ATSUBreakLine and ATSUBatchBreakLines. Calling the function ATSUBatchBreakLines is equivalent to repeatedly calling the function ATSUBreakLine, as shown in Listing 3-4. It’s preferable that you use ATSUBatchBreakLines because this function performs more efficiently than repeated calls to ATSUBreakLine.

The code fragment in Listing 3-4 compares batch line breaking to calculating breaks on a line-by-line basis. A detailed explanation for each numbered line of code appears following the listing. If you’ve used the ATSUBreakLine function before, you’ll see that replacing it with ATSUBatchBreakLines reduces your code by a few lines and improves the performance of your application.

Listing 3-4  A code fragment that performs line breaking

ATSUTextLayout       myTextLayout;

Fixed                myLineBreakWidth;

ItemCount            myNumSoftBreaks;

UniCharCount         myTextLength;

UniCharArrayOffset   *mySoftBreaks,

                     myStarting Offset,

                     myCurrentStart,

                     myCurrentEnd;

 /* Insert your code to set up the text layout object

#if USE_BATCHBREAKLINES // 1

    ATSUBatchBreakLines (myTextLayout,

                            myStartingOffset,

                            myTextLength,

                            myLineBreakWidth,

                            &myNumSoftBreaks);// 2

#else

    myCurrentStart = myStartingOffset;// 3

    myCurrentEnd = myTextLength;

    do

    {

        status = ATSUBreakLine (myTextLayout,

                            myCurrentStart,

                            myLineBreakWidth,

                            true,

                            &myCurrentEnd);// 4

        myCurrentStart = myCurrentEnd;

    } while (myCurrentEnd < myTextLength);

#endif

ATSUGetSoftLineBreaks (myTextLayout,

            kATSUFromTextBeginning,

            kATSUToTextEnd,

            0, NULL, &myNumSoftBreaks);// 5

mySoftBreaks = (UniCharArrayOffset *) malloc(myNumSoftBreaks *

                     sizeof(UniCharArrayOffset));// 6

ATSUGetSoftLineBreaks (myTextLayout,

            kATSUFromTextBeginning,

            kATSUToTextEnd,

            myNumSoftBreaks, mySoftBreaks, &myNumSoftBreaks);// 7

 // Insert your code here to loop over all the soft breaks and draw them

free (mySoftBreaks);// 8

Here’s what the code does:

1. Checks to see if batch line breaking should be used. This code is here only to illustrate the difference between batch line breaking and using the older function ATSUBreakLine.

2. Calls the function ATSUBatchBreakLines. You must supply the text layout object that is associated with the text you want to process. You must also supply a starting offset, the length of the text, and a line width. ATSUI returns the number of soft breaks that are calculated.

3. If batch line breaking isn’t used, sets up variables for the starting and ending offsets of the text for which you want to calculate line breaks.

4. Calls the function ATSUBreakLine to calculate line breaks. The parameter iUseAsSoftLineBreak is set to true to indicate that ATSUI should automatically set the line break to the value returned by the oLineBreak parameter (myCurrentEnd). You must also provide as parameters the first character of the text range associated with the text layout object and the line width.

5. Calls the function ATSUGetSoftLineBreaks to obtain the number of soft line breaks calculated by ATSUI. This is a function you typically call twice. The first time, pass NULL for the oBreaks parameter to obtain the number of line breaks. Then, allocate memory for the line break array and call the function again to obtain the array, as shown in the next two steps.

6. Allocates the appropriate amount of memory for the line break array.

7. Calls the function ATSUGetSoftLineBreaks a second time, but this time passes an array of the appropriate size. On output, the array contains offsets from the beginning of the text buffer to each of the soft line breaks in the text range.

8. Frees the previously allocated memory.

Although it is possible for you to set soft line breaks instead of letting ATSUI do it for you (by passing false for the parameter iUseAsSoftLineBreak), you shouldn’t do so unless it is absolutely necessary. See “Flowing Text Around a Graphic ” for an example of using the function ATSUBreakLine to set line breaks.

< Previous PageNext Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice