Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 4 - List Manager / List Manager Reference

List Manager Routines / Creating and Disposing of Lists

LNew

You can use the LNew function to create a new list in a window.

FUNCTION LNew (rView, dataBounds: Rect; cSize: Point; 
               theProc: Integer; theWindow: WindowPtr; 
               drawit, hasGrow, scrollHoriz, scrollVert: Boolean)
               : ListHandle;

rView

The rectangle in which to display the list, in local coordinates of the window specified by the theWindow parameter. This rectangle does not include the area to be taken up by the list's scroll bars.

dataBounds

The initial data bounds for the list. By setting the left and top fields of this rectangle to (0,0) and the right and bottom fields to (kMyInitialColumns,kMyInitialRows), your application can create a list that has kMyInitialColumns columns and kMyInitialRows rows.

cSize

The size of each cell in the list. If your application specifies (0,0) and is using the default list definition procedure, the List Manager sets the v coordinate of this parameter to the sum of the ascent, descent, and leading of the current font, and it sets the h coordinate using the following formula:

            cSize.h := (rView.right - rView.left) DIV
                           (dataBounds.right - dataBounds.left)

theProc

The resource ID of the list definition procedure to use for the list. To use the default list definition procedure, which supports the display of unstyled text, specify a resource ID of 0.

theWindow

A pointer to the window in which to install the list.

drawIt

A Boolean value that indicates whether the List Manager should initially enable the automatic drawing mode. When the automatic drawing mode is enabled, the List Manager automatically redraws the list whenever a change is made to it. You can later change this setting using the LSetDrawingMode procedure. Your application should leave the automatic drawing mode disabled only for short periods of time when making changes to a list (by, for example, adding rows and columns).

hasGrow

A Boolean value that indicates whether the List Manager should leave room for a size box. The List Manager does not actually draw the grow icon. Usually, your application can draw it with the Window Manager's DrawGrowIcon procedure.

scrollHoriz

A Boolean value that indicates whether the list should contain a horizontal scroll bar. Specify TRUE if your list requires a horizontal scroll bar; specify FALSE otherwise.

scrollVert

Indicates whether the list should contain a vertical scroll bar. Specify TRUE if your list requires a vertical scroll bar; specify FALSE otherwise.

DESCRIPTION

The LNew function attempts to create a list defined by the function's parameters and returns a handle to the newly created list. If the LNew function cannot allocate the list,
it returns NIL. This might happen if there is not enough memory available or if LNew cannot load the resource specified by the theProc parameter. If the LNew function returns successfully, then all of the fields of the list record referenced by the returned handle are correctly set.

If the list contains a horizontal or vertical scroll bar and the window specified by the parameter theWindow is visible, LNew draws the scroll bar for the new list in the window just outside the list's visible rectangle specified by the rView parameter. The LNew function does not, however, draw a 1-pixel border around the list's visible rectangle.

SPECIAL CONSIDERATIONS

You should not call the LNew function from within an interrupt, such as in a completion routine or VBL task.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the LNew function are

Trap macro	Selector
_Pack0	$0044

SEE ALSO

See Listing 4-1 on page 4-18 for an example of how to use the LNew function.