The Table Objects: 4.1 Using a Table Object: Drawing Cells

MSG_TABLE_QUERY_DRAW, MSG_TABLE_REDRAW_TABLE, MSG_TABLE_REDRAW_ROW, MSG_TABLE_REDRAW_COLUMN, MSG_TABLE_REDRAW_CELL, MSG_TABLE_REDRAW_RANGE

The Table object does not actually store the contents of any of the cells. Instead, it helps the application manage and display its data. This means that whenever the Table needs to draw a cell (e.g. when the Table scrolls, or when a cell is covered and then exposed), it has to ask the application to draw it.

Whenever the Table object needs to draw a cell, it sends itself MSG_TABLE_QUERY_DRAW , once for each cell that needs to be redrawn. This message is designed to be subclassed; if you do not subclass it, the default handler will not do anything, and the cell will not be drawn.

The message comes with two arguments:

A TableCellLocation structure, specifying which cell needs to be redrawn.
A GStateHandle . The GState's clipping region is set to the current cell's boundaries; the current position in the GState is the upper-left corner of the cell.

You should intercept this message and take whatever actions are necessary to draw the contents of the cell. Ordinarily, this means calling a routine such as GrDrawTextAtCP() . The default handler doesn't do anything, so you need not call the superclass. You should not free the passed GState.

For efficiency reasons, the Table object actually uses the same GState for several cells that all need to be redrawn at once. For example, suppose the Table needs to redraw cells (10, 0), (10, 1), (10, 2), and (10, 3). The table will take the following steps:

First, the Table creates a GState.
The Table sets the GState's clipping region to the boundaries of cell (10, 0), and puts the current position in the upper-left corner of that cell.
The Table sends itself MSG_TABLE_QUERY_DRAW, specifying that cell (10, 0) needs to be redrawn.
The application intercepts this message, drawing the contents of cell (10, 0) to the passed GState.
The Table changes the GState's clipping region to the boundaries of cell (10, 1), and moves the current position to the upper-left corner of that cell.
The Table sends itself MSG_TABLE_QUERY_DRAW, specifying that cell (10, 1) needs to be redrawn.
The application intercepts this message, drawing the contents of cell (10, 1) to the passed GState.
The Table repeats steps 5-7 for cells (10, 2) and (10, 3).
Finally, the Table frees the GState.

Code Display 5-2 Handling MSG_TABLE_QUERY_DRAW

/* For simplicity, we previously defined an instance field to hold the optr of the 
 * chunk array we are using. We will lock down that data using that instance 
 * field. CoffeeTableClass is a subclass of TableClass. */

@method CoffeeTableClass, MSG_TABLE_QUERY_DRAW
{
    char *data;
    word cArrayIndex, size;

    cArrayIndex = (location.TCL_row * TABLE_COLS) + location.TCL_column;

    MemLock(OptrToHandle(pself->CTI_chunkArray));

    data = ChunkArrayElementToPtr((pself->CTI_chunkArray),
				cArrayIndex, &size);

    GrDrawTextAtCP(gstate, data, 0);

    MemUnlock(OptrToHandle(pself->CTI_chunkArray);
}

The Table automatically sends MSG_TABLE_QUERY_DRAW when it knows a part of the Table may be inaccurate, e.g. when the user has edited a cell. You can also instruct the Table to redraw part or all of itself by sending it one of the MSG_TABLE_REDRAW... messages. These messages instruct the Table to send out appropriate MSG_TABLE_QUERY_DRAW messages for one or more visible cells. There are five MSG_TABLE_REDRAW... messages:

MSG_TABLE_REDRAW_TABLE: This instructs the Table to redraw all cells visible on-screen.
MSG_TABLE_REDRAW_ROW: This instructs the Table to redraw a specified row, if it's on-screen.
MSG_TABLE_REDRAW_COLUMN: This instructs the Table to redraw those cells in a specified column which are on-screen.
MSG_TABLE_REDRAW_CELL: This instructs the Table to redraw a specified cell, if it's on-screen.
MSG_TABLE_REDRAW_RANGE: This instructs the Table to redraw the portion of a specified range of cells that is visible on-screen.

MSG_TABLE_QUERY_DRAW

void	MSG_TABLE_QUERY_DRAW(
        TableCellLocation		location,
        GStateHandle		gstate);

The Table object sends itself this message whenever a cell needs to be redrawn. The default handler does nothing; when you use a Table object, you must subclass this message to draw the cell.

Source: A TableClass object.

Destination: The Table sends this message to itself.

Parameters: location The cell which needs to be redrawn.

gstate: A GStateHandle specifying a GState you should draw to. The GState's clipping region is set to the cell boundaries; the current position (CP) is the upper-left corner of the cell.

Return: Nothing. (You should not free the GState.)

Structures: TableCellLocation (see A TableCellLocation structure is used to specify a cell within the Table. It has the following definition:).

Interception: This message must be intercepted; your handler must draw the cell's contents. You need not call the superclass's handler (which does nothing).

MSG_TABLE_REDRAW_TABLE

void	MSG_TABLE_REDRAW_TABLE();

This message instructs the Table to redraw the entire portion of the Table visible on-screen (creating a GState, sending out appropriate MSG_TABLE_QUERY_DRAW messages, etc.).

Source: Unrestricted.

Destination: Any TableClass object.

Parameters: None.

Return: Nothing.

MSG_TABLE_REDRAW_ROW

void	MSG_TABLE_REDRAW_ROW(
        word	row);

This message instructs the Table to redraw a specified row, if it's visible on-screen (creating a GState, sending out appropriate MSG_TABLE_QUERY_DRAW messages, etc.).

Source: Unrestricted.

Destination: Any TableClass object.

Parameters: row The index of the row to redraw. (The first row has index 0.)

Return: Nothing.

MSG_TABLE_REDRAW_COLUMN

void	MSG_TABLE_REDRAW_COLUMN(
        word	column);

This message instructs the Table to redraw those cells in a specified column that are visible on-screen (creating a GState, sending out appropriate MSG_TABLE_QUERY_DRAW messages, etc.).

Source: Unrestricted.

Destination: Any TableClass object.

Parameters: column The index of the column to redraw. (The first column has index 0.)

Return: Nothing.

MSG_TABLE_REDRAW_CELL

void	MSG_TABLE_REDRAW_CELL(
        TableCellLocation		location);

This message instructs the Table to redraw a specified cell if it is visible on-screen (creating a GState, sending out appropriate MSG_TABLE_QUERY_DRAW messages, etc.).

Source: Unrestricted.

Destination: Any TableClass object.

Parameters: location The cell to redraw.

Return: Nothing.

Structures: The cell is specified with a TableCellLocation structure (described on A TableCellLocation structure is used to specify a cell within the Table. It has the following definition:).

MSG_TABLE_REDRAW_RANGE

void	MSG_TABLE_REDRAW_RANGE(
        TableCellRange		cellRange);

This message instructs the Table to redraw a range of cells (creating a GState, sending out appropriate MSG_TABLE_QUERY_DRAW messages, etc.).

Source: Unrestricted.

Destination: Any TableClass object.

Parameters: cellRange The range of cells to redraw.

Return: Nothing.

Structures: The cell range to redraw is specified with a TableCellRange structure (described on A TableCellRange structure is used to specify a range of cells. It has the following definition:).

GEOS SDK TechDocs|

4 Using a Table Object | Next:

4.2 Selecting Cells