Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 4 - List Manager / Using the List Manager

Adding Rows and Columns to a List

Your application can choose to preallocate the cells it needs when it creates a list. For example, an application might preallocate the columns it needs, and then add rows to the list one by one. Other applications might create a list and add both rows and columns to it later. Regardless of the technique your application uses to create its cells, it can set the data in a cell by using the LSetCell procedure.

You specify the data, the length of the data, the location of the cell whose data you wish to set, and a handle to the list containing the cell, as parameters to the LSetCell procedure. Listing 4-4 demonstrates an application-defined procedure that adds rows to a one-column list based on the contents of a string list resource. The MyAddItemsFromStringList procedure adds each row to the list using the LAddRow function, then sets the data of the cell in the first (and only) column of the newly added row using the LSetCell procedure.

Listing 4-4 Adding items from a string list to a one-column, text-only list

PROCEDURE MyAddItemsFromStringList (myList: ListHandle;
                                    stringListID: Integer);
VAR
   index:      Integer;             {index within string list}
   rowNum:     Integer;             {row number to add string to}
   myString:   Str255;              {string to add}
   aCell:      Cell;                {cell to store string in}
BEGIN
                                    {compute new row number}
   rowNum := myList^^.dataBounds.bottom;
   index := 1;                      {start with first string}
   REPEAT
      GetIndString(myString, stringListID, index);
      IF myString <> '' THEN
      BEGIN    {add new row for string}
         {specify #rows to add, row number of first new row}
         rowNum := LAddRow(1, rowNum, myList);
         {prepare to set cell data--specify }
         { the cell's column number, row number}
         SetPt(aCell, 0, rowNum);
         {set cell data to string}
         LSetCell(@myString[1], Length(myString), aCell,
                  myList);          
      END;
      rowNum := rowNum + 1;
      index := index + 1;
   UNTIL myString = '';
END;

The MyAddItemsFromStringList procedure defined in Listing 4-4 adds strings from a string list resource to the end of a list. It keeps track of the index of the string in the string list with the index variable, and it tracks the number of the new row to add in the rowNum variable.

The MyAddItemsFromStringList procedure adds a new row by calling the LAddRow function. The first parameter to LAddRow specifies the number of rows to add, and the second parameter specifies the row number of the first new row. LAddRow returns the row number of the first row added, which differs from the second parameter only if that parameter specifies a row number that is out of range.

After creating a new row, MyAddItemsFromStringList sets the cell in the first column of the added row to the text contained within the string. Note that the procedure does not copy the length byte of the string.

To add columns to a list, your application can use the LAddColumn function, which works just like LAddRow.

To delete a row or column from a list, your application can call the LDelRow procedure or the LDelColumn procedure. The first parameter of each of these procedures is
the number of rows (or columns) to delete, and the second parameter is the row or column number of the first to be deleted. For example, this code deletes the first row
of a list:

LDelRow(1, 0, myList);{#rows to delete, starting row number}

When making many changes to a list, your application should temporarily disable the automatic drawing mode (unless the list is in a window that is not yet visible). To do so, call the LSetDrawingMode procedure to turn off the automatic drawing mode, make the changes to the list, turn the automatic drawing mode back on, and redraw the list (by invalidating a rectangle containing the list and its scroll bars and later calling the LUpdate procedure when your application receives an update event). You might do these steps as follows:

LSetDrawingMode (FALSE, myList);
{...(make changes to the list)...}
LSetDrawingMode (TRUE, myList);
InvalRect(myList^^.rView);
IF (myList^^.vScroll <> NIL) THEN
   InvalRect(myList^^.vScroll^^.contrlRect);
IF (myList^^.hScroll <> NIL) THEN
   InvalRect(myList^^.hScroll^^.contrlRect);