Legacy Document

Inside Macintosh: Text /

Chapter 3 - QuickDraw Text / QuickDraw Text Reference

Routines / Laying Out a Line of Text

GetFormatOrder

The GetFormatOrder procedure determines the display order of multiple style runs with mixed directions.

PROCEDURE GetFormatOrder (ordering: FormatOrderPtr; 
                          firstFormat: Integer;
                          lastFormat: Integer; 
                          lineRight: Boolean; 
                          rlDirProc: Ptr; dirParam: Ptr);

ordering

A pointer to a format order array. Upon completion of the call, the format order array contains the numbers identifying the style runs in display order. This is its type declaration:

   TYPE
    FormatOrder = ARRAY [0..0] OF Integer;
    FormatOrderPtr = ^FormatOrder;

firstFormat

A number greater than or equal to 0 identifying the first style run in storage order that is part of the line for which you are calling GetFormatOrder.

lastFormat

A number greater than or equal to 0 identifying the last style run in storage order that is part of the line for which you are calling GetFormatOrder.

lineRight

A flag that you set to TRUE if the primary line direction is right-to-left.

rlDirProc

A pointer to an application-supplied function that calculates the correct direction, given the style run identifier. The GetFormatOrder procedure calls the application-defined rlDirProc function for each identifier from firstFormat to lastFormat. The interface to this function looks
like this:

   FUNCTION MyRlDirProc(theFormat: Integer;
         dirParam: Ptr ): Boolean;

This function returns TRUE for right-to-left text direction and FALSE for left-to-right. Given dirParam and a style run identifier, the application-defined rlDirProc routine should be able to determine the style run direction.

theFormat

A number identifying the style run and its associated attribute information in the information block pointed to by dirParam.

dirParam

A pointer to a parameter block that contains the font and script information for each style run in the text. This parameter block is used by the application-supplied routine.

DESCRIPTION

The GetFormatOrder procedure helps you determine how to draw text that contains multiple style runs with mixed directions. For mixed-directional text, after you determine where to break the line, you need to call GetFormatOrder to determine the display order. When you call GetFormatOrder, you supply a Boolean function, and reference it using the rlDirProc parameter. This function calculates the direction of each style run identified by number. Do not call GetFormatOrder if there is only one style run on the line.

You must index the style runs in storage order. You pass GetFormatOrder numbers identifying the first and last style runs of the line in storage order and the primary line direction. The GetFormatOrder procedure returns to you an equivalent sequence in display order.

If you do not explicitly define the primary line direction of the text, base the lineRight parameter on the value of the SysDirection global variable. (The SysDirection global variable is set to -1 if the system direction is right to left, and 0 if the system direction is left to right.)

The ordering parameter points to an array of integers, with (lastFormat - firstFormat + 1) entries. The GetFormatOrder procedure fills an array (the size of the number of the style runs) with the display order of each style run. On exit, the array contains a permuted list of the numbers from firstFormat to lastFormat. The first entry in the array is the number of the style run to draw first; this is the leftmost style run in display order. The last entry in the array is the number of the entry to draw last, the rightmost style run in display order. For more information about how to use the GetFormatOrder procedure, see "Determining the Display Order for Style Runs," which begins on page 3-33. For more information about the rlDirProc function, see "Application-Supplied Routine" on page 3-97.