The Table Objects: 4 Using a Table Object

The Table object is designed to be easy to use. You cannot use a TableClass object directly; you will need to define a subclass of TableClass in order to intercept certain required messages. You will also need to set a few instance fields when you define the Table in your source code.

The Table object must appear within a TableContent object. If it is within a regular VisContent, crashes may result.

When you create a Table object, you will need to set the following instance data fields (the other fields may be left with there default values):

TI_rows: This is the number of rows in the Table . You may set this field to zero. (You can add and remove rows at run-time.) For more information, see Working with Rows.
TI_columns: This is the number of columns in the Table . This must be at least one. You cannot currently add or remove columns at run-time. For more information, see Defining Columns.
TI_visibleRows: This is the number of rows visible on-screen at any one time; thus, this field, together with TI_rowHeight , define the height of a Table object. This field must be at least 1.
TI_columnDefinitions: This is the handle of a chunk containing an array of TableColumnDefinition structures, which specify the properties of the Table 's columns. For more information, see Defining Columns.
TI_rowHeight: This is the height of a row in points (72 points = 1 inch, so 28.3 points ª 1 centimeter). This must be larger than zero.

In order to use a TableClass object, you must define handlers for a few messages. As a general rule, your handlers should call the TableClass handlers after they take their actions; in some cases, your handlers's main role is to add extra data to the message, which will be interpreted by the default handler.

You should define handlers for the following tasks:

You must define a handler for MSG_TABLE_QUERY_DRAW , which redraws a specified cell to a GState. (The TableClass object doesn't actually know what the contents of the cells are; it relies on your subclass's code to draw the cells.) For more information, see Drawing Cells.
You may wish to define a handler for MSG_TABLE_SELECT . This will let you know when the user has selected a cell; you can perform appropriate actions, and decide whether to call the default handler (which highlights the selection and performs other selection actions). For more information, see Selecting Cells.
You should provide handlers for MSG_TABLE_START_EDIT_CELL_TEXT and MSG_TABLE_DONE_EDIT_CELL_TEXT . These messages let the user edit the text in Table cells. By subclassing the messages, you can provide the current cell contents for the user to edit, and store the user's text after he or she has finished entering it. For more information, see Editing Cells.
The Table object supports drag-and-drop copying. However, it does not actually know what the cells contain, so it can't perform the copying itself. Instead, when the user performs a drag-and-drop operation, the Table object sends MSG_TABLE_DRAG_DROP_COMPLETE ; the application should intercept the message, and do any appropriate copying of data. For more information, see Dragging and Dropping.
You may want to implement your own custom scrolling behavior. (TableClass supports auto-scrolling with the addition of the TF_ENABLE_AUTO_SCROLLING flag; auto scrolling does not, however, provide any visual UI (such as scroll buttons) to enable scrolling.) If you want custom scrolling behavior, you will need to implement scroll buttons in your TableView and appropriate messages to your Table object (such as MSG_TABLE_SCROLL_SINGLE_UP and MSG_TABLE_SCROLL_SINGLE_DOWN) . For more information, see Custom Scrolling Behavior.
If you link a Locator object to your Table (see LocatorClass) you will want to intercept MSG_TABLE_CHAR_LOCATE and MSG_TABLE_STRING_LOCATE to implement your own search methods. For more information, see Handling Locator Searches.
If you want to change your column definitions dynamically, you will need to define additional column definitions and switch which ones you use under the Table. There is no API currently for this behavior; you will need to write the messages and handle them yourself. This is discussed in Changing Column Definitions.

Drawing Cells

Selecting Cells

Editing Cells

Dragging and Dropping

Custom Scrolling Behavior

Handling Locator Searches

Table Headings

Changing Column Definitions

GEOS SDK TechDocs|

3 TableClass Instance Data | Next:

5 TableContentClass