ADC Home > Reference Library > Reference > Carbon > User Experience > List Manager Reference (Not Recommended) >

< Previous PageNext Page > Hide TOC

Legacy Documentclose button

Important: The List Manager is deprecated in Mac OS X version 10.5 and later. The replacement API is the Data Browser. For more information, see Data Browser Programming Guide.

Deprecated List Manager Reference (Not Recommended) Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.5

CreateCustomList

(Deprecated in Mac OS X v10.5.)

OSStatus CreateCustomList (
   const Rect *rView,
   const ListBounds *dataBounds,
   Point cellSize,
   const ListDefSpec *theSpec,
   WindowRef theWindow,
   Boolean drawIt,
   Boolean hasGrow,
   Boolean scrollHoriz,
   Boolean scrollVert,
   ListHandle *outList
);

Parameters
rView
dataBounds
cellSize
theSpec
theWindow
drawIt
hasGrow
scrollHoriz
scrollVert
outList
Return Value

A result code.

Availability
Declared In
Lists.h

DisposeListClickLoopUPP

Disposes of the universal procedure pointer (UPP) to a list click loop callback function. (Deprecated in Mac OS X v10.5.)

void DisposeListClickLoopUPP (
   ListClickLoopUPP userUPP
);

Parameters
userUPP
Discussion

See the ListClickLoopProcPtr callback for more information.

Availability
Declared In
Lists.h

DisposeListDefUPP

Disposes of the universal procedure pointer (UPP) to a list definition callback function. (Deprecated in Mac OS X v10.5.)

void DisposeListDefUPP (
   ListDefUPP userUPP
);

Parameters
userUPP
Discussion

See the ListDefProcPtr callback for more information.

Availability
Declared In
Lists.h

DisposeListSearchUPP

Disposes of the universal procedure pointer (UPP) to a list search callback function. (Deprecated in Mac OS X v10.5.)

void DisposeListSearchUPP (
   ListSearchUPP userUPP
);

Parameters
userUPP
Discussion

See the ListSearchProcPtr callback for more information.

Availability
Declared In
Lists.h

GetListActive

(Deprecated in Mac OS X v10.5.)

Boolean GetListActive (
   ListHandle list
);

Parameters
list
Availability
Declared In
Lists.h

GetListCellIndent

(Deprecated in Mac OS X v10.5.)

Point * GetListCellIndent (
   ListHandle list,
   Point *indent
);

Parameters
list
indent
Availability
Declared In
Lists.h

GetListCellSize

(Deprecated in Mac OS X v10.5.)

Point * GetListCellSize (
   ListHandle list,
   Point *size
);

Parameters
list
size
Availability
Declared In
Lists.h

GetListClickLocation

(Deprecated in Mac OS X v10.5.)

Point * GetListClickLocation (
   ListHandle list,
   Point *click
);

Parameters
list
click
Availability
Declared In
Lists.h

GetListClickLoop

(Deprecated in Mac OS X v10.5.)

ListClickLoopUPP GetListClickLoop (
   ListHandle list
);

Parameters
list
Return Value

See the description of the ListClickLoopUPP data type.

Availability
Declared In
Lists.h

GetListClickTime

(Deprecated in Mac OS X v10.5.)

SInt32 GetListClickTime (
   ListHandle list
);

Parameters
list
Availability
Declared In
Lists.h

GetListDataBounds

(Deprecated in Mac OS X v10.5.)

ListBounds * GetListDataBounds (
   ListHandle list,
   ListBounds *bounds
);

Parameters
list
bounds
Return Value

See the description of the ListBounds data type.

Availability
Declared In
Lists.h

GetListDataHandle

(Deprecated in Mac OS X v10.5.)

DataHandle GetListDataHandle (
   ListHandle list
);

Parameters
list
Return Value

See the description of the DataHandle data type.

Availability
Declared In
Lists.h

GetListDefinition

(Deprecated in Mac OS X v10.5.)

Handle GetListDefinition (
   ListHandle list
);

Parameters
list
Availability
Declared In
Lists.h

GetListFlags

(Deprecated in Mac OS X v10.5.)

OptionBits GetListFlags (
   ListHandle list
);

Parameters
list
Availability
Declared In
Lists.h

GetListHorizontalScrollBar

(Deprecated in Mac OS X v10.5.)

ControlRef GetListHorizontalScrollBar (
   ListHandle list
);

Parameters
list
Return Value

See the Control Manager documentation for a description of the ControlRef data type.

Availability
Declared In
Lists.h

GetListMouseLocation

(Deprecated in Mac OS X v10.5.)

Point * GetListMouseLocation (
   ListHandle list,
   Point *mouse
);

Parameters
list
mouse
Availability
Declared In
Lists.h

GetListPort

(Deprecated in Mac OS X v10.5.)

CGrafPtr GetListPort (
   ListHandle list
);

Parameters
list
Return Value

See the QuickDraw Manager documentation for a description of the CGrafPtr data type.

Availability
Declared In
Lists.h

GetListRefCon

(Deprecated in Mac OS X v10.5.)

SInt32 GetListRefCon (
   ListHandle list
);

Parameters
list
Availability
Declared In
Lists.h

GetListSelectionFlags

(Deprecated in Mac OS X v10.5.)

OptionBits GetListSelectionFlags (
   ListHandle list
);

Parameters
list
Availability
Declared In
Lists.h

GetListUserHandle

(Deprecated in Mac OS X v10.5.)

Handle GetListUserHandle (
   ListHandle list
);

Parameters
list
Availability
Declared In
Lists.h

GetListVerticalScrollBar

(Deprecated in Mac OS X v10.5.)

ControlRef GetListVerticalScrollBar (
   ListHandle list
);

Parameters
list
Return Value

See the Control Manager documentation for a description of the ControlRef data type.

Availability
Declared In
Lists.h

GetListViewBounds

(Deprecated in Mac OS X v10.5.)

Rect * GetListViewBounds (
   ListHandle list,
   Rect *view
);

Parameters
list
view
Availability
Declared In
Lists.h

GetListVisibleCells

(Deprecated in Mac OS X v10.5.)

ListBounds * GetListVisibleCells (
   ListHandle list,
   ListBounds *visible
);

Parameters
list
visible
Return Value

See the description of the ListBounds data type.

Availability
Declared In
Lists.h

InvokeListClickLoopUPP

Calls your list click loop callback function. (Deprecated in Mac OS X v10.5.)

Boolean InvokeListClickLoopUPP (
   ListClickLoopUPP userUPP
);

Parameters
userUPP
Discussion

See the ListClickLoopProcPtr callback for more information.

Availability
Declared In
Lists.h

InvokeListDefUPP

Calls your list definition callback function. (Deprecated in Mac OS X v10.5.)

void InvokeListDefUPP (
   short lMessage,
   Boolean lSelect,
   Rect *lRect,
   Cell lCell,
   short lDataOffset,
   short lDataLen,
   ListHandle lHandle,
   ListDefUPP userUPP
);

Parameters
lMessage
lSelect
lRect
lCell
lDataOffset
lDataLen
lHandle
userUPP
Discussion

See the ListDefProcPtr callback for more information.

Availability
Declared In
Lists.h

InvokeListSearchUPP

Calls your list search callback function (Deprecated in Mac OS X v10.5.)

short InvokeListSearchUPP (
   Ptr aPtr,
   Ptr bPtr,
   short aLen,
   short bLen,
   ListSearchUPP userUPP
);

Parameters
aPtr
bPtr
aLen
bLen
userUPP
Return Value
Discussion

See the ListSearchProcPtr callback for more information.

Availability
Declared In
Lists.h

LActivate

Activates or deactivates a list. (Deprecated in Mac OS X v10.5.)

void LActivate (
   Boolean act,
   ListHandle lHandle
);

Parameters
act

Indicates whether the list should be activated. Specify TRUE to activate the list. Specify FALSE to deactivate the list.

lHandle

The list to be activated or deactivated.

Discussion

If a list is being deactivated, this function removes highlighting from selected cells and hides the scroll bars. If a list is being activated, the function highlights selected cells and shows the scroll bars.

This function has no effect on a list’s size box, if one exists.

Availability
Declared In
Lists.h

LAddColumn

Adds one or more columns to a list. (Deprecated in Mac OS X v10.5.)

short LAddColumn (
   short count,
   short colNum,
   ListHandle lHandle
);

Parameters
count

The number of columns to add.

colNum

The column number of the first column to add.

lHandle

The list to which to add the columns.

Return Value

The column number of the first column added, which is equal to the value specified by the colNum parameter if that value is a valid column number. If the column number specified by colNum is not already in the list, then new last columns are added. The value returned by this function thus has significance only in this case.

Discussion

This function inserts columns starting at the column specified by the colNum parameter. If there is insufficient memory in the heap to add the new columns, this function may fail to add the new columns although it returns a positive function result. Be sure there is enough memory in the heap to allocate the new columns before calling LAddColumn.

Columns whose column numbers are initially greater than colNum have their column numbers increased by count.

If the automatic drawing mode is enabled and the columns added by the function are visible, then the list (including its scroll bars) is updated. New cells created by a call to this function are initially empty.

You may add columns to a list that does not yet have rows. The dataBounds field of the list record reflects that the list has columns, but you can only access cells when both rows and columns have been added.

Availability
Declared In
Lists.h

LAddRow

Adds one or more rows to a list. (Deprecated in Mac OS X v10.5.)

short LAddRow (
   short count,
   short rowNum,
   ListHandle lHandle
);

Parameters
count

The number of rows to add.

rowNum

The row number of the first row to add.

lHandle

The list to add the rows to.

Return Value

The row number of the first row added, which is equal to the value specified by the rowNum parameter if that value is a valid row number. If the row number specified by rowNum is not already in the list, then new last rows are added. The value returned by this function thus has significance only in this case.

Discussion

This function inserts rows starting at the row specified by the rowNum parameter. If there is insufficient memory in the heap to add the new rows, the function may fail to add the new rows although it returns a positive function result. Be sure there is enough memory in the heap to allocate the new rows before calling this function.

Rows whose row numbers are initially greater than rowNum have their row numbers increased by count.

If the automatic drawing mode is enabled and the rows added by this function are visible, then the list (including its scroll bars) is updated. New cells created by a call to this function are initially empty.

You may add rows to a list that does not yet have columns. The dataBounds field of the list record reflects that the list has rows, but you can only access cells when both rows and columns have been added.

Availability
Declared In
Lists.h

LAddToCell

Appends data to the data already contained in a cell. (Deprecated in Mac OS X v10.5.)

void LAddToCell (
   const void *dataPtr,
   short dataLen,
   Cell theCell,
   ListHandle lHandle
);

Parameters
dataPtr

A pointer to the data to be appended.

dataLen

The length in bytes of the data to be appended.

theCell

The coordinates of the cell to which the data should be appended.

lHandle

The list containing the cell given in the theCell parameter.

Discussion

If the cell coordinates specified by the parameter theCell are invalid, then this function does nothing.

If the data of a visible cell is changed and the automatic drawing mode is enabled, the function updates the list.

Availability
Declared In
Lists.h

LAutoScroll

Scrolls a list so that the first selected cell is in the upper-left corner of the list’s visible rectangle. (Deprecated in Mac OS X v10.5.)

void LAutoScroll (
   ListHandle lHandle
);

Parameters
lHandle

The list to be scrolled.

Availability
Declared In
Lists.h

LCellSize

Changes the size of cells in a list. (Deprecated in Mac OS X v10.5.)

void LCellSize (
   Point cSize,
   ListHandle lHandle
);

Parameters
cSize

The new size of each cell in the list. This function sets the cellSize field of the list record of the list to the value of the cSize parameter. That is, the list’s new cells will be of width cSize.h and of height cSize.v.

All cells in a list must be the same size.

lHandle

The list whose cells’ size is being changed.

Discussion

The function updates the list’s visible rectangle to contain cells of the specified size. However, it does not redraw any cells.

Availability
Declared In
Lists.h

LClick

Processes a mouse-down event in a list. (Deprecated in Mac OS X v10.5.)

Boolean LClick (
   Point pt,
   EventModifiers modifiers,
   ListHandle lHandle
);

Parameters
pt

The location in local coordinates of the mouse-down event. Your application can simply call GlobalToLocal(myEvent.where) and then pass myEvent.where in this parameter.

If the pt parameter specifies a portion of the list’s visible rectangle, then cells are selected with an algorithm that depends on the list’s selection flags and on the modifiers parameter. If the user drags the cursor above or below the list’s visible rectangle and vertical autoscrolling is enabled, then the List Manager vertically autoscrolls the list. If the user drags the cursor to the right or the left of the list’s visible rectangle and horizontal autoscrolling is enabled, then the List Manager horizontally autoscrolls the list.

If the pt parameter specifies a point within the list’s scroll bar, then the List Manager calls the scroll bar’s control definition function to track the cursor and it scrolls the list appropriately.

modifiers

An integer value corresponding to the modifiers field of the event record.

lHandle

The list in which the mouse-down event occurred.

Return Value

TRUE if the click was a double-click, or FALSE otherwise.

Discussion

The LClick function handles all user interaction until the user releases the mouse button.

Availability
Declared In
Lists.h

LClrCell

Clears the data contained in a cell. (Deprecated in Mac OS X v10.5.)

void LClrCell (
   Cell theCell,
   ListHandle lHandle
);

Parameters
theCell

The coordinates of the cell to be cleared.

lHandle

The list containing the cell given in the theCell parameter.

Discussion

If the cell coordinates specified by the theCell parameter are invalid, then the function does nothing.

If the data of a visible cell is cleared and the automatic drawing mode is enabled, the function updates the list.

Availability
Declared In
Lists.h

LDelColumn

Deletes one or more columns from a list. (Deprecated in Mac OS X v10.5.)

void LDelColumn (
   short count,
   short colNum,
   ListHandle lHandle
);

Parameters
count

The number of columns to delete, or 0 to delete all columns.

colNum

The column number of the first column to delete.

lHandle

The list from which to delete the columns.

Discussion

This function deletes columns starting at the column specified by the colNum parameter. If the column specified by colNum is invalid, then nothing is done.

Your application can quickly delete all columns from a list (and thus delete all cell data) simply by setting the count parameter to 0. The number of rows is left unchanged. Your application can achieve the same effect by setting the colNum parameter to (**lHandle).dataBounds.left and setting the count parameter to a value greater than (**lHandle).dataBounds.right – (**lHandle).dataBounds.left.

Columns whose column numbers are initially greater than colNum have their column numbers decreased by count.

If the automatic drawing mode is enabled and one or more of the columns deleted by this function are visible, then the list (including its scroll bars) is updated.

Availability
Declared In
Lists.h

LDelRow

Deletes one or more rows from a list. (Deprecated in Mac OS X v10.5.)

void LDelRow (
   short count,
   short rowNum,
   ListHandle lHandle
);

Parameters
count

The number of rows to delete, or 0 to delete all rows.

rowNum

The row number of the first row to delete.

lHandle

The list from which to delete the rows.

Discussion

This function deletes rows starting at the row specified by the rowNum parameter. If the row specified by rowNum is invalid, then nothing is done.

Your application can quickly delete all rows from a list (and thus delete all cell data) simply by setting the count parameter to 0. The number of columns is left unchanged. Your application can achieve the same effect by setting the rowNum parameter to (**lHandle).dataBounds.top and setting the count parameter to a value greater than (**lHandle).dataBounds.bottom – (**lHandle).dataBounds.top.

Rows whose row numbers are initially greater than rowNum have their row numbers decreased by count.

If the automatic drawing mode is enabled and one or more of the rows deleted by the function are visible, then the list (including its scroll bars) is updated.

Availability
Declared In
Lists.h

LDispose

Disposes of the memory associated with a list. (Deprecated in Mac OS X v10.5.)

void LDispose (
   ListHandle lHandle
);

Parameters
lHandle

The list to be disposed of.

Discussion

This function releases all memory allocated by the List Manager in creating a list. First, it issues a close request to the list definition function and calls the Control Manager function DisposeControl for the list’s scroll bars (if any). The function then uses the Memory Manager to free the memory referenced by the cells field, then disposes of the list record itself.

Because it disposes of data associated with cells in your list, there is no need to clear the data from list cells or to delete individual rows and columns before calling this function.

This function does not dispose of any memory associated with a list that the List Manager has not allocated. In particular, it does not dispose of any memory referenced by the userHandle field of the list record. Your application is responsible for deallocating any memory it has allocated through the userHandle field before calling this function.

Availability
Declared In
Lists.h

LDraw

Draws a cell in a list. (Deprecated in Mac OS X v10.5.)

void LDraw (
   Cell theCell,
   ListHandle lHandle
);

Parameters
theCell

The cell to draw.

lHandle

The list containing the cell identified by the parameter theCell.

Discussion

The List Manager makes the list’s graphics port the current port, sets the clipping region to the cell’s rectangle, and calls the list definition function to draw the cell. It restores the clipping region and port before exiting.

Ordinarily, you should only need to use this function when the automatic drawing mode has been disabled.

Availability
Declared In
Lists.h

LGetCell

Copies a cell’s data. (Deprecated in Mac OS X v10.5.)

void LGetCell (
   void *dataPtr,
   short *dataLen,
   Cell theCell,
   ListHandle lHandle
);

Parameters
dataPtr

A pointer to the location to which to copy the cell’s data.

dataLen

On input, a pointer to the maximum number of bytes to copy. On return, a pointer to the number of bytes actually copied.

theCell

The cell whose data is to be copied.

lHandle

The list containing the cell specified by the parameter theCell.

Discussion

If the cell data is longer than dataLen, only dataLen bytes are copied and the dataLen parameter is unchanged. If the cell data is shorter than dataLen, then the function sets dataLen to the length in bytes of the cell’s data.

Availability
Declared In
Lists.h

LGetCellDataLocation

Finds the memory location of cell data. (Deprecated in Mac OS X v10.5.)

void LGetCellDataLocation (
   short *offset,
   short *len,
   Cell theCell,
   ListHandle lHandle
);

Parameters
offset

On return, a pointer to the offset of the cell’s data, specified from the beginning of the data handle referenced by the cells field of the list record.

len

On return, a pointer to the length of the cell’s data in bytes.

theCell

The cell whose data’s location is sought.

lHandle

The list containing the cell specified by the parameter theCell.

Discussion

Your application can use this function to read cell data. The cells field of the list record contains a handle to a relocatable block used to store all cell data. When this function returns, the offset parameter contains the offset of the specified cell’s data in this relocatable block, and the len parameter specifies the length in bytes of the cell’s data. In other words, the first byte of cell data is located at Ptr(ORD4(lHandle^^.cells^) + offset), and the last byte of cell data is located at Ptr(ORD4(lHandle^^.cells^) + offset + len). Your application should not modify the contents of the cells field directly. To change a cell’s data, use the LSetCell function or the LAddToCell function.

If the cell coordinates specified by the parameter theCell are invalid, then the function sets the offset and len parameters to –1.

This function is also available as the LFind function.

Availability
Declared In
Lists.h

LGetSelect

Gets information about which cells are selected. (Deprecated in Mac OS X v10.5.)

Boolean LGetSelect (
   Boolean next,
   Cell *theCell,
   ListHandle lHandle
);

Parameters
next

Indicates whether the function should check only the cell specified by the parameter theCell, or whether it should try to find the next selected cell. If next is TRUE, then the function searches the list for the first selected cell beginning at the cell specified by theCell. (In particular, it first checks cells in row theCell.v, and then cells in the next row, and so on.)

If next is FALSE, then the function checks only the cell specified by the parameter theCell.

theCell

On input, a pointer to the first cell whose selection status should be checked. If next is TRUE, then, on return this parameter is a pointer to the next selected cell greater than or equal to the cell specified on input. Otherwise, this parameter remains unchanged.

lHandle

The list in which the selection is being checked.

Return Value

TRUE if next is TRUE and the function finds a selected cell, or if next is FALSE and the cell specified by theCell is selected. If this function does not find a selected cell, FALSE.

Special Considerations

This function is contained in a resource of resource type 'PACK'. Calling it could result in the loading of the package resource and the allocation of memory. Thus, your application should not call this function from within an interrupt, such as in a completion function or VBL task.

Availability
Declared In
Lists.h

LLastClick

Determines the coordinates of the last cell clicked in a particular list. (Deprecated in Mac OS X v10.5.)

Cell LLastClick (
   ListHandle lHandle
);

Parameters
lHandle

The list to be checked for the last cell clicked.

Return Value

The cell coordinates of the last cell clicked. If the user has not clicked a cell since the creation of the list, then both the h and v fields of the cell returned contain negative numbers. See the description of the Cell data type.

Discussion

Note that the last cell clicked is not necessarily the last cell selected. The user could Shift-click in one cell and then drag the cursor to select other cells.

Availability
Declared In
Lists.h

LNew

Creates a new list in a window. (Deprecated in Mac OS X v10.5.)

ListHandle LNew (
   const Rect *rView,
   const ListBounds *dataBounds,
   Point cSize,
   short theProc,
   WindowRef theWindow,
   Boolean drawIt,
   Boolean hasGrow,
   Boolean scrollHoriz,
   Boolean scrollVert
);

Parameters
rView

A pointer to 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

A pointer to 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 function, 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) / (dataBounds.right – dataBounds.left).

theProc

The resource ID of the list definition function to use for the list. To use the default list definition function, 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

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 function. 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

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 function.

scrollHoriz

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.

Return Value

A handle to the newly created list, or if the function cannot allocate the list, NULL. This might happen if there is not enough memory available or if the function cannot load the resource specified by the theProc parameter. If it returns successfully, then all of the fields of the list record referenced by the returned handle are correctly set. See the description of the ListHandle data type.

Discussion

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

Availability
Declared In
Lists.h

LNextCell

Finds the next cell in a given row, in a given column, or in an entire list. (Deprecated in Mac OS X v10.5.)

Boolean LNextCell (
   Boolean hNext,
   Boolean vNext,
   Cell *theCell,
   ListHandle lHandle
);

Parameters
hNext

Indicates whether the function should check columns other than the current column. To get the next cell in a row, set this parameter to TRUE and set vNext to FALSE. The function then tries to find a cell whose coordinates are greater than those of the cell specified in theCell parameter but that is in the same row as theCell.

To get the next cell in a column, set this parameter to FALSE and set vNext to TRUE. The function then tries to find a cell whose coordinates are greater than those of the cell specified in theCell but that is in the same column as theCell.

To get the next cell in a list, set both this parameter and vNext to TRUE. This function then tries to find a cell whose coordinates are greater than those of the cell specified in the parameter theCell.

vNext

Indicates whether the function should check rows other than the current row. To get the next cell in a row, set this parameter to FALSE and set hNext to TRUE. The function then tries to find a cell whose coordinates are greater than those of the cell specified in theCell parameter but that is in the same row as theCell.

To get the next cell in a column, set this parameter to TRUE and set hNext to FALSE. The function then tries to find a cell whose coordinates are greater than those of the cell specified in theCell but that is in the same column as theCell.

To get the next cell in a list, set both this parameter and hNext to TRUE. This function then tries to find a cell whose coordinates are greater than those of the cell specified in the parameter theCell.

theCell

A pointer to the coordinates of the current cell. On return, a pointer to the next cell in the list, column or row being searched. If there are no more cells in the list, column or row, this parameter remains unchanged.

lHandle

The list in which to find the next cell.

Return Value

TRUE, if the function finds the next cell in the list, column or row being searched. FALSE, if the cell initially specified by theCell is the last in the row, column or list being searched. Also FALSE when both hNext and vNext are FALSE.

Availability
Declared In
Lists.h

LRect

Finds a rectangle that encloses a cell. (Deprecated in Mac OS X v10.5.)

void LRect (
   Rect *cellRect,
   Cell theCell,
   ListHandle lHandle
);

Parameters
cellRect

On return, a pointer to the rectangle enclosing the cell, specified in local coordinates of the list’s graphics port. This rectangle is not necessarily within the list’s rectangle.

theCell

The cell for which an enclosing rectangle is sought. This function does not check whether the cell is actually contained within the list’s visible rectangle.

If this parameter specifies cell coordinates not contained within the list, this function sets the cellRect parameter to (0,0,0,0).

lHandle

The list containing the cell specified by the parameter theCell.

Discussion

Because the List Manager automatically draws cells, few applications need to call this function directly.

Availability
Declared In
Lists.h

LScroll

Scrolls a list a specified number of rows and columns. (Deprecated in Mac OS X v10.5.)

void LScroll (
   short dCols,
   short dRows,
   ListHandle lHandle
);

Parameters
dCols

The number of columns to scroll. Specify a positive number to scroll down (that is, each cell moves up), and a negative number to scroll up.

dRows

The number of rows to scroll. Specify a positive number to scroll right (that is, each cell moves left), and a negative number to scroll left.

lHandle

The list to be scrolled.

Discussion

The List Manager will not scroll beyond the data bounds of the list. If the automatic drawing mode is enabled, this function does all necessary updating of the list.

Availability
Declared In
Lists.h

LSearch

Finds a cell whose data matches data that you specify. (Deprecated in Mac OS X v10.5.)

Boolean LSearch (
   const void *dataPtr,
   short dataLen,
   ListSearchUPP searchProc,
   Cell *theCell,
   ListHandle lHandle
);

Parameters
dataPtr

A pointer to the data being searched for.

dataLen

The length in bytes of the data being searched for.

searchProc

A pointer to a function to be used to compare the data being searched for with cell data. If NULL, the Text Utilities Package function IUMagIDString is used.

If either the function pointed to by searchProc or IUMagIDString returns 0, LSearch has found a match; otherwise, it checks the next cell in the list.

theCell

A pointer to the first cell to be searched. If the function finds a match, this parameter is, on return, a pointer to the coordinates of the first cell whose data matches the data being searched for.

lHandle

The list to be searched.

Return Value

If the function finds a match, TRUE. Otherwise, FALSE.

Availability
Declared In
Lists.h

LSetCell

Changes the data contained in a cell. (Deprecated in Mac OS X v10.5.)

void LSetCell (
   const void *dataPtr,
   short dataLen,
   Cell theCell,
   ListHandle lHandle
);

Parameters
dataPtr

A pointer to the new data for a cell.

dataLen

The length in bytes of the new data.

theCell

The coordinates of the cell to hold the new data.

lHandle

The list containing the cell given in the theCell parameter.

Discussion

Any previous cell data in theCell is replaced. If there is insufficient memory in the heap, the function may fail to set the cell’s data. If the cell coordinates specified by the theCell parameter are invalid, the function does nothing.

If the data of a visible cell is changed and the automatic drawing mode is enabled, the function updates the list.

Availability
Declared In
Lists.h

LSetDrawingMode

Changes the automatic drawing mode specified when creating a list. (Deprecated in Mac OS X v10.5.)

void LSetDrawingMode (
   Boolean drawIt,
   ListHandle lHandle
);

Parameters
drawIt

Indicates whether the List Manager should enable the automatic drawing mode. Specify TRUE to enable the automatic drawing mode. Specify FALSE to disable the automatic drawing mode.

lHandle

The list whose drawing mode is being changed.

Discussion

Your application can use the LSetDrawingMode function to enable or disable automatic drawing of lists. If your application uses LSetDrawingMode to temporarily disable list drawing, then it must call the LDraw function to draw a cell when its appearance changes, or when new rows or columns are added to the list. .

While the automatic drawing mode is turned off, all cell drawing and highlighting are disabled, and the scroll bar does not function properly. Thus, your application should disable the automatic drawing mode only for short periods of time. After enabling it, your application should ensure that the list is redrawn.

This function is also available as the LDoDraw function.

Availability
Declared In
Lists.h

LSetSelect

Selects or deselects a cell. (Deprecated in Mac OS X v10.5.)

void LSetSelect (
   Boolean setIt,
   Cell theCell,
   ListHandle lHandle
);

Parameters
setIt

Indicates whether the function should select or deselect the specified cell. Specify TRUE to select the cell. If the cell is already selected, the function does nothing. Specify FALSE to deselect the cell. If the cell is already deselected, the function does nothing.

theCell

The cell to be selected or deselected.

lHandle

The list containing the cell to be selected or deselected.

Discussion

If a cell’s selection status is changed and the cell is visible, LSetSelect redraws the cell.

Availability
Declared In
Lists.h

LSize

Changes the size of a list. (Deprecated in Mac OS X v10.5.)

void LSize (
   short listWidth,
   short listHeight,
   ListHandle lHandle
);

Parameters
listWidth

The new width (in pixels) of the list’s visible rectangle.

listHeight

The new height (in pixels) of the list’s visible rectangle.

lHandle

The list whose size is being changed.

Discussion

This function adjusts the lower-right side of the list so that the list’s visible rectangle is the width and height specified by the listWidth and listHeight parameters.

Because the list’s visible rectangle does not include room for the scroll bars, your application should make listWidth 15 pixels less than the desired width of the list if it contains a vertical scroll bar, and it should make listHeight 15 pixels less than the desired height of the list if it contains a horizontal scroll bar.

The contents of the list and the scroll bars are adjusted and redrawn as necessary. However, this function does not draw a border around the list’s rectangle. Also, it does not erase any portions of the old list that may still be visible. This approach should not be a problem if your application only calls LSize after the user resizes a window containing a list in its lower-right corner.

Usually, you need to call this function only after calling the Window Manager function SizeWindow.

Availability
Declared In
Lists.h

LUpdate

Responds to an update event. (Deprecated in Mac OS X v10.5.)

void LUpdate (
   RgnHandle theRgn,
   ListHandle lHandle
);

Parameters
theRgn

The visible region of the list’s port after a call to the Window Manager’s BeginUpdate function.

lHandle

The list to be updated.

Discussion

This function redraws all visible cells in the list specified by the lHandle parameter that intersect the region specified by the parameter theRgn. It also redraws the scroll bars if they intersect the region.

You should bracket calls to LUpdate by calls to the Window Manager functions BeginUpdate and EndUpdate.

Availability
Declared In
Lists.h

NewListClickLoopUPP

Creates a new universal procedure pointer (UPP) to a list click loop callback function. (Deprecated in Mac OS X v10.5.)

ListClickLoopUPP NewListClickLoopUPP (
   ListClickLoopProcPtr userRoutine
);

Parameters
userRoutine
Return Value

See the description of the ListClickLoopUPP data type.

Discussion

See the ListClickLoopProcPtr callback for more information.

Availability
Declared In
Lists.h

NewListDefUPP

Creates a new universal procedure pointer (UPP) to a list definition callback function. (Deprecated in Mac OS X v10.5.)

ListDefUPP NewListDefUPP (
   ListDefProcPtr userRoutine
);

Parameters
userRoutine
Return Value

See the description of the ListDefUPP data type.

Discussion

See the ListDefProcPtr callback for more information.

Carbon Porting Notes
Availability
Declared In
Lists.h

NewListSearchUPP

Creates a new universal procedure pointer (UPP) to a list search callback function. (Deprecated in Mac OS X v10.5.)

ListSearchUPP NewListSearchUPP (
   ListSearchProcPtr userRoutine
);

Parameters
userRoutine
Return Value

See the description of the ListSearchUPP data type.

Discussion

See the ListSearchProcPtr callback for more information.

Availability
Declared In
Lists.h

RegisterListDefinition

(Deprecated in Mac OS X v10.5.)

OSStatus RegisterListDefinition (
   SInt16 inResID,
   ListDefSpecPtr inDefSpec
);

Parameters
inResID
inDefSpec
Return Value

A result code.

Availability
Declared In
Lists.h

SetListCellIndent

(Deprecated in Mac OS X v10.5.)

void SetListCellIndent (
   ListHandle list,
   Point *indent
);

Parameters
list
indent
Availability
Declared In
Lists.h

SetListClickLoop

(Deprecated in Mac OS X v10.5.)

void SetListClickLoop (
   ListHandle list,
   ListClickLoopUPP clickLoop
);

Parameters
list
clickLoop
Availability
Declared In
Lists.h

SetListClickTime

(Deprecated in Mac OS X v10.5.)

void SetListClickTime (
   ListHandle list,
   SInt32 time
);

Parameters
list
time
Availability
Declared In
Lists.h

SetListFlags

(Deprecated in Mac OS X v10.5.)

void SetListFlags (
   ListHandle list,
   OptionBits listFlags
);

Parameters
list
listFlags
Availability
Declared In
Lists.h

SetListLastClick

(Deprecated in Mac OS X v10.5.)

void SetListLastClick (
   ListHandle list,
   Cell *lastClick
);

Parameters
list
lastClick
Availability
Declared In
Lists.h

SetListPort

(Deprecated in Mac OS X v10.5.)

void SetListPort (
   ListHandle list,
   CGrafPtr port
);

Parameters
list
port
Availability
Declared In
Lists.h

SetListRefCon

(Deprecated in Mac OS X v10.5.)

void SetListRefCon (
   ListHandle list,
   SInt32 refCon
);

Parameters
list
refCon
Availability
Declared In
Lists.h

SetListSelectionFlags

(Deprecated in Mac OS X v10.5.)

void SetListSelectionFlags (
   ListHandle list,
   OptionBits selectionFlags
);

Parameters
list
selectionFlags
Availability
Declared In
Lists.h

SetListUserHandle

(Deprecated in Mac OS X v10.5.)

void SetListUserHandle (
   ListHandle list,
   Handle userHandle
);

Parameters
list
userHandle
Availability
Declared In
Lists.h

SetListViewBounds

(Deprecated in Mac OS X v10.5.)

void SetListViewBounds (
   ListHandle list,
   const Rect *view
);

Parameters
list
view
Availability
Declared In
Lists.h

< Previous PageNext Page > Hide TOC

© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-12-11)

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.