Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

34    Table Reference

User Interface

Exploring Palm OS®

This chapter describes the table API as declared in the header file Table.h. It discusses the following topics:

Table Structures and Types
Table Constants
Table Events
Table Functions and Macros
Application-Defined Functions

For more information on tables, see "Tables."

Table Structures and Types ^TOP^

TableType Struct ^TOP^

Purpose

Internal structure that represents a table. A TablePtr defines a pointer to a TableType structure.

Declared In

Table.h

Prototype

typedef struct TableType TableType;
typedef TableType *TablePtr

Fields

None.

Table Constants ^TOP^

Miscellaneous Table Constants ^TOP^

Purpose

Constants defined in Table.h.

Declared In

Table.h

Constants

#define tableDefaultColumnSpacing 1
Never used.
#define tableMaxTextItemSize 255
The maximum length of an editable text field within a table cell.
#define tableNoteIndicatorHeight 11
The height in standard coordinates of the note indicator for tables items of type textWithNoteTableItem.
#define tableNoteIndicatorWidth 7
The width in standard coordinates of the note indicator for tables items of type textWithNoteTableItem.
#define tblUnusableRow 0xffff
Value returned by TblGetLastUsableRow() if none of the table's rows are usable.

TableItemStyleType Typedef ^TOP^

Purpose

The type of the item, such as a control, a text label, and so on within a table cell.

Declared In

Table.h

Prototype

typedef Enum8 TableItemStyleType

Constants

checkboxTableItem
A check box control.
The table stores an integer value for this type of table cell. Retrieve its value with TblGetItemInt(). The pointer value is not defined.
customTableItem
A cell drawn using the callback function TableDrawItemFuncType().
If you want, you can store data for custom cells within the table by using TblSetItemInt() or TblSetItemPtr().
dateTableItem
Non-editable date in the form month/day, or a dash if the date value is –1. The date is followed by an exclamation point if it has passed.
The table stores an integer value for this type of table cell. Retrieve its value with TblGetItemInt(). The returned value should be cast to DateType. DateType is currently defined as a 16-bit number:
dddddmmmmyyyyyyy
The first 5 bits are the day, the next 4 bits are the month, and the next 7 bits are the year given as the offset since 1904.
Dates are always drawn in the current font.
labelTableItem
Non-editable text displayed in the system's default font with a terminating colon character (":"). Use a labelNoColonTableItem if you don't want a colon.
The table stores a string pointer value for this type of table cell. Retrieve its value with TblGetItemPtr(). The integer value is not defined.
numericTableItem
Non-editable integer. Integers are displayed in the system's default bold font.
The table stores an integer value for this type of table cell. Retrieve its value with TblGetItemInt(). The pointer value is not defined.
popupTriggerTableItem
A pop-up list displayed in the system's default font with a trailing colon character. Use popupTriggerNoColonTableItem if you don't want the trailing colon.
For this type of table cell, both an integer and a pointer are defined. TblGetItemInt() returns the index of the list item that should be displayed. TblGetItemPtr() returns a pointer to the list (ListType *).
textTableItem
Editable text field. For this item type, implement the callback function TableLoadDataFuncType() to load text into the table cell and implement the callback TableSaveDataFuncType() to save data before the field is freed.
You can set the font used in the text field with TblSetItemFont(). TblGetItemPtr() returns a pointer to the field (FieldType *). The integer value is not defined.
textWithNoteTableItem
Editable text field and a note icon to the right of the text. For this item type, implement the callback function TableLoadDataFuncType() to load text into the table cell and implement the callback TableSaveDataFuncType() to save data before the field is freed.
You can set the font used in the text field with TblSetItemFont(). TblGetItemPtr() returns a pointer to the field (FieldType *). The integer value is not defined.
timeTableItem
Not implemented.
narrowTextTableItem
Editable text with space reserved on the right side of the cell. For this item type, implement the callback function TableDrawItemFuncType() to draw in the space reserved on the right side of the cell, the TableLoadDataFuncType() callback function to load text into the table cell, and the callback function TableSaveDataFuncType() to save data before the field is freed.
You can set the font used in the text field with TblSetItemFont(). TblGetItemPtr() returns a pointer to the field (FieldType *). The integer value set by TblSetItemInt() is the number of standard coordinates to reserve on the right side of the cell.
tallCustomTableItem
A cell drawn using the callback function TableDrawItemFuncType(). The height of the item is equal to the height of the row (set by TblSetRowHeight()) in which the item is located. In Palm OS Cobalt, this style is identical to customTableItem.
If you want, you can store data for custom cells within the table by using TblSetItemInt() or TblSetItemPtr().
labelNoColonTableItem
Non-editable text displayed in the system's default font without the terminating colon character.
The table stores a string pointer value for this type of table cell. Retrieve its value with TblGetItemPtr(). The integer value is not defined.
popupTriggerNoColonTableItem
A pop-up list displayed in the system's default font without a trailing colon.
For this type of table cell, both an integer and a pointer are defined. TblGetItemInt() returns the index of the list item that should be displayed. TblGetItemPtr() returns a pointer to the list (ListType *).

Comments

The private TableType structure has fields in which to store an integer, a pointer, and a bitmapped font ID for each table item. In many cases, only one of the three is defined. Which values are defined determines how you retrieve the value of the table cell. See the descriptions above to determine how to work with each item type.

See Also

TblSetItemStyle(), TblGetItemStyle()

Table Events ^TOP^

tblEnterEvent ^TOP^

Purpose

Sent when a penDownEvent occurs within the bounds of an active item in a table.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct tblEnter {
   struct TableType *pTable;
   uint16_t tableID;
   int16_t row;
   int16_t column;
   _BA32_PADDING_16(1)
} tblEnter

Fields

pTable
Pointer to a table structure.
tableID
Resource ID of the table.
row
Row of the item.
column
Column of the item.

tblExitEvent ^TOP^

Purpose

Sent when the stylus had previously entered the bounds of the table but is lifted outside of the bounds of the table.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct tblExit {
   struct TableType *pTable;
   uint16_t tableID;
   int16_t row;
   int16_t column;
   _BA32_PADDING_16(1)
} tblExit

Fields

pTable
Pointer to a table structure.
tableID
Resource ID of the table.
row
Row of the item.
column
Column of the item.

tblSelectEvent ^TOP^

Purpose

Sent when the stylus had previously entered the bounds of the table and is now lifted within the bounds of the table. The pen must be lifted within the bounds of the same table item on which the original penDownEvent occurred.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct tblSelect {
   struct TableType *pTable;
   uint16_t tableID;
   int16_t row;
   int16_t column;
   _BA32_PADDING_16(1)
} tblSelect

Fields

pTable
Pointer to a table structure.
tableID
Resource ID of the table.

row

Row of the item.

column

Column of the item.

See Also

TblGetSelection()

Table Functions and Macros ^TOP^

TblColumnUsable Function ^TOP^

Purpose

Returns whether a specified column is usable. Unusable columns do not display.

Declared In

Table.h

Prototype

Boolean TblColumnUsable (
   const TableType *tableP,
   int16_t column
)

Parameters

tableP
Pointer to a table.
column
Column number (zero-based).

Returns

true if the column is usable or false otherwise.

See Also

TblSetColumnUsable()

TblDrawTable Function ^TOP^

Purpose

Draws a table.

Declared In

Table.h

Prototype

void TblDrawTable (
   TableType *tableP
)

Parameters

tableP
Pointer to a table.

Returns

Nothing.

Comments

This function is called as part of FrmDrawForm() when the form contains a table.

This function draws into a graphics context. Therefore, you must call it from within a frmUpdateEvent if the form that contains the table uses an update-based window.

This function draws the entire table, marking all rows valid before drawing. See the TableItemStyleType description for more information about how each type of table cell is drawn.

When drawing cells with editable text fields (textTableItem, textWithNoteTableItem, or narrowTextTableItem), this function uses the TableLoadDataFuncType() callback function to load the text into the table cells. The text field does not retain the text handle that your TableLoadDataFuncType() returns, meaning that you are responsible for freeing the memory that you load into the table.

When drawing narrowTextTableItem cells, customTableItem cells or tallCustomTableItem cells, this function uses the TableDrawItemFuncType() callback function to draw the extra pixels after the text or to draw the entire cell.

On color systems, tables are always drawn using the same color as is used for the field background color.

When the user has set the security setting to mask private records, table cells that contain private database records are drawn as shaded cells to obscure the information they contain. You must explicitly tell the table which cells are masked by making the appropriate calls to TblSetRowMasked() and TblSetColumnMasked().

See Also

TblEraseTable(), TblRedrawTable(), TblSetCustomDrawProcedure(), TblInvalidate()

TblEditing Function ^TOP^

Purpose

Checks whether a table is in edit mode.

Declared In

Table.h

Prototype

Boolean TblEditing (
   const TableType *tableP
)

Parameters

tableP
Pointer to a table.

Returns

true if the table is in edit mode, false otherwise.

Comments

The table is in edit mode while the user edits a text item. More specifically, the table is in edit mode when a tblEnterEvent is received on an editable table cell (textTableItem, textWithNoteTableItem, or narrowTextTableItem), or when TblGrabFocus() is called.

The table is taken out of edit mode when the user places the pen on a note in a textWithNoteTableItem or when the table releases the focus (TblReleaseFocus()).

TblEraseTable Function ^TOP^

Purpose

Erases a table.

Declared In

Table.h

Prototype

void TblEraseTable (
   TableType *tableP
)

Parameters

tableP
Pointer to a table.

Returns

Nothing.

Comments

This function sets the table's visible and selected attributes to false. It does not invalidate table rows.

See Also

TblDrawTable(), TblSetCustomDrawProcedure(), TblRedrawTable()

TblFindRowData Function ^TOP^

Purpose

Returns the number of the row that contains the specified data value.

Declared In

Table.h

Prototype

Boolean TblFindRowData (
   const TableType *tableP,
   uint32_t data,
   int16_t *rowP
)

Parameters

tableP
Pointer to a table.
data
Row data to find.
rowP
Pointer to the row number (return value).

Returns

true if a match was found, false otherwise.

Comments

This function searches for a row whose attributes contain the specified data. The data is any application-specific data that you have set with TblSetRowData().

See Also

TblGetRowData(), TblFindRowID()

TblFindRowID Function ^TOP^

Purpose

Returns the number of the row with the specified ID.

Declared In

Table.h

Prototype

Boolean TblFindRowID (
   const TableType *tableP,
   uint16_t id,
   int16_t *rowP
)

Parameters

tableP
Pointer to a table.
id
Row ID to find.
rowP
Pointer to the row number (return value).

Returns

true if a match was found, false otherwise.

See Also

TblSetRowID(), TblFindRowData()

TblGetBounds Function ^TOP^

Purpose

Returns the bounds of a table.

Declared In

Table.h

Prototype

void TblGetBounds (
   const TableType *tableP,
   RectangleType *rP
)

Parameters

tableP
Pointer to a table.
rP
A RectangleType structure in which the bounds are returned.

Returns

Nothing.

See Also

TblGetItemBounds()

TblGetColumnMasked Function ^TOP^

Purpose

Determines whether a particular table column is masked.

Declared In

Table.h

Prototype

Boolean TblGetColumnMasked (
   const TableType *tableP,
   int16_t column
)

Parameters

tableP
Pointer to a table.
column
Column number (zero-based).

Returns

true if the column is masked, false otherwise.

Comments

If a table cell's column is masked and the cell's row is also masked, the table cell is drawn on the screen but is shaded to obscure the information that it contains.

See Also

TblSetColumnMasked()

TblGetColumnSpacing Function ^TOP^

Purpose

Returns the spacing after the specified column.

Declared In

Table.h

Prototype

Coord TblGetColumnSpacing (
   const TableType *tableP,
   int16_t column
)

Parameters

tableP
Pointer to a table.
column
Column number (zero-based).

Returns

The spacing after the column (in standard coordinates).

This function may display a fatal error message if the column parameter is invalid.

See Also

TblGetColumnWidth(), TblSetColumnSpacing(), TblSetColumnUsable()

TblGetColumnWidth Function ^TOP^

Purpose

Returns the width of the specified column.

Declared In

Table.h

Prototype

Coord TblGetColumnWidth (
   const TableType *tableP,
   int16_t column
)

Parameters

tableP
Pointer to a table.
column
Column number (zero-based).

Returns

The width of a column (in standard coordinates). This function may display a fatal error message if the column parameter is invalid.

See Also

TblGetColumnSpacing(), TblSetColumnWidth(), TblSetColumnUsable()

TblGetCurrentField Function ^TOP^

Purpose

Returns a pointer to the FieldType in which the user is currently editing a text item.

Declared In

Table.h

Prototype

FieldPtr TblGetCurrentField (
   const TableType *tableP
)

Parameters

tableP
Pointer to a table.

Returns

A pointer to the currently selected field, or NULL if the table is not in edit mode.

See Also

TblGetSelection()

TblGetItemBounds Function ^TOP^

Purpose

Returns the bounds of an item in a table.

Declared In

Table.h

Prototype

void TblGetItemBounds (
   const TableType *tableP,
   int16_t row,
   int16_t column,
   RectangleType *rP
)

Parameters

tableP
Pointer to a table.
row
Row number of the item (zero-based).
column
Column number of the item (zero-based).
rP
Pointer to a RectangleType structure that holds the bounds of the item.

Returns

Nothing.

Comments

This function may raise a fatal exception if the row or column parameter specifies a row or column that does not appear on screen.

If the item is a customTableItem, the returned height is equal to the height of the font used to draw the item. If the item is a tallCustomTableItem, the return height is the full height of the table row.

TblGetItemFont Function ^TOP^

Purpose

Returns the font used to display a table item.

Declared In

Table.h

Prototype

FontID TblGetItemFont (
   const TableType *tableP,
   int16_t row,
   int16_t column
)

Parameters

tableP
Pointer to a table.
row
Row number of the item (zero-based).
column
Column number of the item (zero-based).

Returns

The ID of the font used for the table item at the row and column indicated.

Comments

This function returns the font ID stored in the table structure for this item. Only certain types of table items use the font specified by the table structure when they are displayed. The TableItemStyleType description specifies what font is used to display each type of table item.

This function may display a fatal error message if the row or column parameter specifies a row or column that is not on the screen.

See Also

TblSetItemFont()

TblGetItemInt Function ^TOP^

Purpose

Returns the integer value stored in a table item.

Declared In

Table.h

Prototype

int16_t TblGetItemInt (
   const TableType *tableP,
   int16_t row,
   int16_t column
)

Parameters

tableP
Pointer to a table.
row
Row number of the item (zero-based).
column
Column number of the item (zero-based).

Returns

The integer value.

Comments

This function returns the integer value stored internally for this table item. Certain types of table items display the integer value, and other types display the value pointed to by the internal pointer value. See the TableItemStyleType description for details. If the integer value was never set for this table item, this function returns 0.

This function may display a fatal message if the row or column does not appear on the screen.

See Also

TblSetItemInt(), TblGetItemPtr()

TblGetItemPtr Function ^TOP^

Purpose

Returns the pointer value stored in a table item.

Declared In

Table.h

Prototype

void *TblGetItemPtr (
   const TableType *tableP,
   int16_t row,
   int16_t column
)

Parameters

tableP
Pointer to a table.
row
Row number of the item (zero-based).
column
Column number of the item (zero-based).

Returns

The item's pointer value or NULL if the item does not have a pointer value.

Comments

This function returns the pointer value stored internally for this table item. Certain types of table items display the value pointed to by this pointer, and other types display an integer value stored in an integer field. See the TableItemStyleType description for details. An application may have set the value of the pointer anyway, even for items that use the integer value. This function always returns that pointer value.

This function may display a fatal message if the row or column parameter is invalid.

See Also

TblSetItemPtr()

TblGetItemStyle Function ^TOP^

Purpose

Returns a table item's style.

Declared In

Table.h

Prototype

TableItemStyleType TblGetItemStyle (
   const TableType *tableP,
   int16_t row,
   int16_t column
)

Parameters

tableP
Pointer to a table.
row
Row number of the item (zero-based).
column
Column number of the item (zero-based).

Returns

A TableItemStyleType constant that specifies the item's style.

TblGetLastUsableRow Function ^TOP^

Purpose

Returns the last row in a table that is usable (visible).

Declared In

Table.h

Prototype

int16_t TblGetLastUsableRow (
   const TableType *tableP
)

Parameters

tableP
Pointer to a table.

Returns

The row index (zero-based) or tblUnusableRow if there are no usable rows.

See Also

TblGetRowData(), TblGetRowID()

TblGetNumberOfColumns Function ^TOP^

Purpose

Returns the number of columns in a table.

Declared In

Table.h

Prototype

int16_t TblGetNumberOfColumns (
   const TableType *tableP
)

Parameters

tableP
Pointer to a table.

Returns

The number of columns in a table.

See Also

TblGetTopRow(), TblSetSelection()

TblGetNumberOfRows Function ^TOP^

Purpose

Returns the number of rows in a table.

Declared In

Table.h

Prototype

int16_t TblGetNumberOfRows (
   const TableType *tableP
)

Parameters

tableP
Pointer to a table.

Returns

The maximum number of visible rows in the specified table.

Comments

Note that even though you can add and remove rows to and from a table, the value returned by this function does not change. The value returned by this function indicates the maximum number of rows that can be displayed on the screen at one time. It is set when you create the table resource.

TblGetRowData Function ^TOP^

Purpose

Returns the data value of the specified row.

Declared In

Table.h

Prototype

uint32_t TblGetRowData (
   const TableType *tableP,
   int16_t row
)

Parameters

tableP
Pointer to a table.
row
Number of the row (zero-based).

Returns

The application-specific data stored for this row, if any. Returns 0 if there is no application-specific data value.

Comments

This function may display a fatal error message if the row parameter is invalid.

See Also

TblFindRowData(), TblSetRowData()

TblGetRowHeight Function ^TOP^

Purpose

Returns the height of the specified row.

Declared In

Table.h

Prototype

Coord TblGetRowHeight (
   const TableType *tableP,
   int16_t row
)

Parameters

tableP
Pointer to a table.
row
Number of the row (zero-based).

Returns

The height in standard coordinates.

Comments

This function may display a fatal error message if the row parameter is invalid.

See Also

TblGetItemBounds(), TblSetRowHeight()

TblGetRowID Function ^TOP^

Purpose

Returns the ID value of the specified row.

Declared In

Table.h

Prototype

uint16_t TblGetRowID (
   const TableType *tableP,
   int16_t row
)

Parameters

tableP
Pointer to a table.
row
Number of the row (zero-based).

Returns

The ID value of the row in the table.

Comments

This function may display a fatal error message if the row parameter is invalid.

See Also

TblGetRowData(), TblSetRowID(), TblFindRowID()

TblGetSelection Function ^TOP^

Purpose

Returns the row and column of the currently selected table item.

Declared In

Table.h

Prototype

Boolean TblGetSelection (
   const TableType *tableP,
   int16_t *rowP,
   int16_t *columnP
)

Parameters

tableP
Pointer to a table.
rowP, columnP
The row and column indexes (zero-based) of the currently selected item.

Returns

true if the item is selected, false if not.

See Also

TblSetRowSelectable(), TblSetSelection()

TblGetTopRow Function ^TOP^

Purpose

Returns the top visible row of a table.

Declared In

Table.h

Prototype

int16_t TblGetTopRow (
   const TableType *tableP
)

Parameters

tableP
Pointer to a table.

Returns

The top visible row in a table.

See Also

TblGetNumberOfColumns()

TblGrabFocus Function ^TOP^

Purpose

Puts a table into edit mode.

Declared In

Table.h

Prototype

void TblGrabFocus (
   TableType *tableP,
   int16_t row,
   int16_t column
)

Parameters

tableP
Pointer to a table.
row
Current row to be edited (zero-based).
column
Current column to be edited (zero-based).

Returns

Nothing.

Comments

This function may display a fatal error message if the table already has the focus or if the row or column parameter is invalid.

This function puts the table into edit mode and sets the current item to the one at the row and column passed in. An editable field must exist in the coordinates passed to this function.

You must call FrmSetFocus() before calling this function. FrmSetFocus() releases the focus from the UI element that previously had it and sets the form's internal structures.

Example

The following function from the Address Book application sets the focus in an editable field within a table:


static void EditViewRestoreEditState () { 
  uint16_t row; 
  FormType *frm; 
  TableType *table; 
  FieldType *fld; 
  
  if (CurrentFieldIndex == noFieldIndex)  
    return; 
  
  // Find the row that the current field is in. 
  table = GetObjectPtr (EditTable); 
  if ( ! TblFindRowID (table, CurrentFieldIndex, &row) ) 
    return; 
  
  frm = FrmGetActiveForm (); 
  FrmSetFocus (frm, FrmGetObjectIndex (frm, EditTable)); 
  TblGrabFocus (table, row, editDataColumn); 
   
  // Restore the insertion point position. 
  fld = TblGetCurrentField (table); 
  FldSetInsPtPosition (fld, EditFieldPosition); 
} 

See Also

TblReleaseFocus()

TblHandleEvent Function ^TOP^

Purpose

Handles an event for the table.

Declared In

Table.h

Prototype

Boolean TblHandleEvent (
   TableType *tableP,
   EventType *event
)

Parameters

tableP
Pointer to a table.
event
The event to be handled.

Returns

true if the event was handled, false if the event was not handled or if the table is not editable.

Comments

If the table is editable, this function passes along any keyDownEvent, fldEnterEvent, menuCmdBarOpenEvent, FEP events, or insertion point events to the currently selected field.

When a fldHeightChangedEvent occurs, this function changes the height of the specified field as indicated by the event. If the field being resized is going to scroll off the bottom of the screen, then instead the table scrolls the rows above it up off the top. Otherwise, the table is scrolled downward and rows below the current row are scrolled off the bottom as necessary.

Note that the fldHeightChangedEvent is only handled for dynamically sized fields. See the descriptions of "Multi-line Text Fields" for more information on dynamically sized fields.

When a penDownEvent occurs, the table checks to see if the focus is being changed. If it is and the user was previously editing a text field within the table, it saves the data in the table cell using the TableSaveDataFuncType() callback function, then it enqueues a tblEnterEvent with the new row and column that are selected.

When a tblEnterEvent occurs, this function tracks the pen until it is lifted. If the pen is lifted within the bounds of the same item it went down in, a tblSelectEvent is added to the event queue; if not, a tblExitEvent is added to the event queue.

TblHasScrollBar Function ^TOP^

Purpose

Sets whether the table has a scroll bar associated with it.

Declared In

Table.h

Prototype

void TblHasScrollBar (
   TableType *tableP,
   Boolean hasScrollBar
)

Parameters

tableP
Pointer to a table.
hasScrollBar
true to set the attribute, false to unset it.

Returns

Nothing.

Comments

Your application must scroll the table itself and keep track of the scroll values. See the ListViewUpdateScrollers() function in the Memo example application (MemoMain.c) for an example of setting scroll bar values for a table.

TblInsertRow Function ^TOP^

Purpose

Inserts a row into the table before the specified row.

Declared In

Table.h

Prototype

void TblInsertRow (
   TableType *tableP,
   int16_t row
)

Parameters

tableP
Pointer to a table.
row
Row to insert (zero-based).

Returns

Nothing.

Comments

The number of rows in a table is the maximum number of rows displayed on the screen. Unlike a multi-line text field, there is no notion of a table that is bigger than the available screen. For this reason, this function does not increase the number of table rows.

Instead of keeping track of a total number of rows in the table and a number of rows displayed on the screen, tables mark any row that isn't currently displayed as unusable.

The newly inserted row is marked as invalid, unusable, and not masked. If you want to display the newly inserted row, call TblSetRowUsable() after making sure that the row displays a value and then call TblInvalidate() to trigger a frmUpdateEvent that redraws the table.

See Also

TblRemoveRow(), TblSetRowUsable(), TblSetRowSelectable()

TblInvalidate Function ^TOP^

Purpose

Invalidates the table's region and redraws the table if possible.

Declared In

Table.h

Prototype

void TblInvalidate (
   TableType *tblP
)

Parameters

tblP
Pointer to a table.

Returns

Nothing.

Comments

This function invalidates the region of the form that contains the table so that a frmUpdateEvent is generated. If the form's window is a transitional window, the table is redrawn immediately using a private callback function. If the form is an update-based window, the callback function may be called if this is the only pending drawing update. Otherwise, your application receives and should handle the frmUpdateEvent.

See Also

WinInvalidateRect(), WinInvalidateWindow(), TblDrawTable(), TblRedrawTable()

TblMarkRowInvalid Function ^TOP^

Purpose

Marks the row invalid.

Declared In

Table.h

Prototype

void TblMarkRowInvalid (
   TableType *tableP,
   int16_t row
)

Parameters

tableP
Pointer to a table.
row
Row number (zero-based).

Returns

Nothing.

Comments

Invalidating a table row does not trigger a frmUpdateEvent. If you want to trigger a frmUpdateEvent, you must call TblInvalidate() after calling this function.

This function may display a fatal error message if the row parameter is invalid.

See Also

TblRemoveRow(), TblSetRowUsable(), TblSetRowSelectable(), TblMarkTableInvalid(), TblRowInvalid()

TblMarkTableInvalid Function ^TOP^

Purpose

Marks all the rows in a table invalid.

Declared In

Table.h

Prototype

void TblMarkTableInvalid (
   TableType *tableP
)

Parameters

tableP
Pointer to a table.

Returns

Nothing.

Comments

Invalidating table rows does not trigger a frmUpdateEvent. If you want to trigger a frmUpdateEvent, you must call TblInvalidate() after calling this function.

See Also

TblEraseTable(), TblRedrawTable()

TblRedrawTable Function ^TOP^

Purpose

Redraws the rows of the table that are marked invalid.

Declared In

Table.h

Prototype

void TblRedrawTable (
   TableType *tableP
)

Parameters

tableP
Pointer to a table.

Returns

Nothing.

Comments

This function draws into a graphics context. Therefore, you must call it from within a frmUpdateEvent if the form that contains the field uses an update-based window.

This function draws the invalid rows in the table. See the TableItemStyleType description for more information about how each type of table cell is drawn.

When drawing cells with editable text fields (textTableItem, textWithNoteTableItem, or narrowTextTableItem), this function uses the TableLoadDataFuncType() callback function to load the text into the table cells. The text field does not retain the text handle that your TableLoadDataFuncType() returns, meaning that you are responsible for freeing the memory that you load into the table.

When drawing narrowTextTableItem cells, customTableItem cells, or tallCustomTableItem cells, this function uses the TableDrawItemFuncType() callback function to draw the extra pixels after the text or to draw the entire cell.

On color systems, tables are always drawn using the same color as is used for the field background color.

When the user has set the security setting to mask private records, table cells that contain private database records are drawn as shaded cells to obscure the information they contain. You must explicitly tell the table which cells are masked by making the appropriate calls to TblSetRowMasked() and TblSetColumnMasked().

See Also

TblMarkTableInvalid(), TblMarkRowInvalid(), TblDrawTable(), TblInvalidate()

TblReleaseFocus Function ^TOP^

Purpose

Releases the focus.

Declared In

Table.h

Prototype

void TblReleaseFocus (
   TableType *tableP
)

Parameters

tableP
Pointer to a table.

Returns

Nothing.

Comments

Applications typically do not call this function. Instead, they call FrmSetFocus() with an element index of noFocus to notify the form that the table has lost focus. The form code calls TblReleaseFocus() for you.

If the current item is a text item, the TableSaveDataFuncType() callback function is called to save the text in the currently selected field, the memory allocated for editing is released, and the insertion point is turned off.

Also note that you might have to call FldReleaseFocus() if the focus is in an editable text field and that field uses a custom drawing function (TableDrawItemFuncType()).

See Also

TblGrabFocus()

TblRemoveRow Function ^TOP^

Purpose

Removes the specified row from the table.

Declared In

Table.h

Prototype

void TblRemoveRow (
   TableType *tableP,
   int16_t row
)

Parameters

tableP
Pointer to a table.
row
Row to remove (zero-based).

Returns

Nothing.

Comments

The number of rows in the table is not decreased; instead, this row is moved from its current spot to the end of the table and is marked unusable so that it won't be displayed when the table is redrawn.

This function does not visually update the display. To do so, you must call TblInvalidate().

This function may raise a fatal error message if an invalid row is specified.

See Also

TblInsertRow(), TblSetRowUsable(), TblSetRowSelectable(), TblMarkRowInvalid()

TblRowInvalid Function ^TOP^

Purpose

Returns whether a row is invalid.

Declared In

Table.h

Prototype

Boolean TblRowInvalid (
   const TableType *tableP,
   int16_t row
)

Parameters

tableP
Pointer to a table.
row
Row number (zero-based).

Returns

true if the row is invalid, false if it's valid.

Comments

Invalid rows need to be redrawn. Use TblRedrawTable() to do so.

This function may raise a fatal error message if the row parameter is invalid.

See Also

TblMarkRowInvalid(), TblMarkTableInvalid()

TblRowMasked Function ^TOP^

Purpose

Returns whether a row is masked.

Declared In

Table.h

Prototype

Boolean TblRowMasked (
   const TableType *tableP,
   int16_t row
)

Parameters

tableP
Pointer to a table.
row
Row number (zero-based).

Returns

true if the row is masked, false otherwise.

Comments

Your code should set a row to masked if it contains a private database record and the user has set the display preference for private records to masked. Masked cells are displayed as shaded.

Note that a table cell is not masked unless both its row and column are masked. This allows non-private information in the row item to remain visible. For example, the Date Book application shows the time for a private appointment, but it does not show the description.

See Also

TblSetRowMasked(), TblSetColumnMasked(), SecSelectViewStatus()

TblRowSelectable Function ^TOP^

Purpose

Returns whether the specified row is selectable.

Declared In

Table.h

Prototype

Boolean TblRowSelectable (
   const TableType *tableP,
   int16_t row
)

Parameters

tableP
Pointer to a table.
row
Row number (zero-based).

Returns

true if the row is selectable, false if it's not.

TblRowUsable Function ^TOP^

Purpose

Determines whether the specified row is usable.

Declared In

Table.h

Prototype

Boolean TblRowUsable (
   const TableType *tableP,
   int16_t row
)

Parameters

tableP
Pointer to a table.
row
Row number (zero-based).

Returns

true if the row is usable, false if it's not.

Comments

This function may display a fatal error message if the row parameter is invalid.

Rows that are not usable do not display.

See Also

TblRowSelectable(), TblGetLastUsableRow(), TblSetRowUsable()

TblSelectItem Function ^TOP^

Purpose

Selects the specified item. If there is already a selected item, that item is deselected.

Declared In

Table.h

Prototype

void TblSelectItem (
   TableType *tableP,
   int16_t row,
   int16_t column
)

Parameters

tableP
Pointer to a table.
row
Row of the item to select (zero-based).
column
Column of the item to select (zero-based).

Returns

Nothing.

Comments

This function may display a fatal error message if the column or row parameter point to an item that is not on the screen.

If row contains a masked private database record, then the item remains unselected.

If the selected table item contains a text field, the text field displays the insertion point, and all of the other items in the same row as the text field that have the edit indicator flag set are highlighted.

If the selected table item does not contain a text field, that item is highlighted and the previously selected table item is unhighlighted. If you want to the entire row to be highlighted, either create a table that has a single column, or write your own selection code.

If the selected item contains a check box or pop-up trigger, it is not highlighted; however, the current selection is still set to this table item.

See Also

TblRowSelectable(), TblGetItemBounds(), TblGetItemInt()

TblSetBounds Function ^TOP^

Purpose

Sets the bounds of a table.

Declared In

Table.h

Prototype

void TblSetBounds (
   TableType *tableP,
   const RectangleType *rP
)

Parameters

tableP
Pointer to a table.
rP
Pointer to a RectangleType structure that specifies the bounds for the table.

Returns

Nothing.

TblSetColumnEditIndicator Function ^TOP^

Purpose

Sets the column attribute that controls whether a column highlights when the table is in edit mode.

Declared In

Table.h

Prototype

void TblSetColumnEditIndicator (
   TableType *tableP,
   int16_t column,
   Boolean editIndicator
)

Parameters

tableP
Pointer to a table.
column
Column number (zero based).
editIndicator
true to highlight, false to turn off highlight.

Returns

Nothing.

Comments

The edit indicator controls whether the item in the column is highlighted when a field within the current row is being edited. By default, text field items have the edit indicator value of false, while all other table item types have an edit indicator of true.

TblSetColumnMasked Function ^TOP^

Purpose

Sets whether the column is masked.

Declared In

Table.h

Prototype

void TblSetColumnMasked (
   TableType *tableP,
   int16_t column,
   Boolean masked
)

Parameters

tableP
Pointer to a table.
column
Column number (zero-based).
masked
true to have the column be masked, false otherwise.

Returns

Nothing.

Comments

Masked cells are displayed as shaded. You should set a column to masked if its contents should be hidden when it contains information from a private database record and the user has set the display preference for private records to masked.

A table cell is not masked unless both its row and column are masked. This allows non-private information in the row item to remain visible. For example, the Date Book application shows the time for a private appointment, but it does not show the description.

Because the number of columns is static, you only need to call this function once per column when you first set up the table. The masked attribute on the row will determine if the contents of the table cell are actually displayed as shaded.

See Also

TblRowMasked(), TblSetRowMasked(), SecSelectViewStatus()

TblSetColumnSpacing Function ^TOP^

Purpose

Sets the spacing after the specified column.

Declared In

Table.h

Prototype

void TblSetColumnSpacing (
   TableType *tableP,
   int16_t column,
   Coord spacing
)

Parameters

tableP
Pointer to a table.
column
Column number (zero-based).
spacing
Spacing after the column in standard coordinates.

Returns

Nothing.

Comments

This function may display a fatal error message if the column parameter is invalid.

See Also

TblSetColumnUsable()

TblSetColumnUsable Function ^TOP^

Purpose

Sets a column in a table to usable or unusable.

Declared In

Table.h

Prototype

void TblSetColumnUsable (
   TableType *tableP,
   int16_t column,
   Boolean usable
)

Parameters

tableP
Pointer to a table.
column
Column number (zero-based).
usable
true for usable or false for not usable.

Returns

Nothing.

Comments

This function may display a fatal error message if the column parameter is invalid.

Columns that are not usable do not display.

See Also

TblMarkRowInvalid()

TblSetColumnWidth Function ^TOP^

Purpose

Sets the width of the specified column.

Declared In

Table.h

Prototype

void TblSetColumnWidth (
   TableType *tableP,
   int16_t column,
   Coord width
)

Parameters

tableP
Pointer to a table.
column
Column number (zero-based).
width
Width of the column (in standard coordinates).

Returns

Nothing.

This function may display a fatal error message if the column parameter is invalid.

See Also

TblGetColumnWidth()

TblSetCustomDrawProcedure Function ^TOP^

Purpose

Sets the custom draw callback procedure for the specified column.

Declared In

Table.h

Prototype

void TblSetCustomDrawProcedure (
   TableType *tableP,
   int16_t column,
   TableDrawItemFuncPtr drawCallback
)

Parameters

tableP
Pointer to a table.
column
Column number.
drawCallback
Callback function.

Returns

Nothing.

Comments

The custom draw callback function is used to draw table items with a TableItemStyleType of customTableItem or tallCustomTableItem.

This function may display a fatal error message if the column parameter is invalid.

See Also

TableDrawItemFuncType(), TblDrawTable()

TblSetItemFont Function ^TOP^

Purpose

Sets the font used to display a table item.

Declared In

Table.h

Prototype

void TblSetItemFont (
   TableType *tableP,
   int16_t row,
   int16_t column,
   FontID fontID
)

Parameters

tableP
Pointer to a table.
row
Row number of the item (zero-based).
column
Column number of the item (zero-based).
fontID
FontID of the font to be used.

Returns

Nothing.

Comments

This function sets the internal font value stored for this table item. Only certain types of table items use this stored font value when they are displayed. The TableItemStyleType description specifies what font is used to display each type of table item. It is not an error to set the font for a table item that does not use it.

This function may display a fatal error message if the row or column parameter specifies a row or column that is not on the screen.

See Also

TblGetItemFont()

TblSetItemInt Function ^TOP^

Purpose

Sets the integer value of the specified item.

Declared In

Table.h

Prototype

void TblSetItemInt (
   TableType *tableP,
   int16_t row,
   int16_t column,
   int16_t value
)

Parameters

tableP
Pointer to a table.
row
Row number of the item (zero-based).
column
Column number of the item (zero-based).
value
Any byte value (an integer).

Returns

Nothing.

Comments

This function may display a fatal error message if the row or column parameter is invalid.

You typically use this function when setting up and initializing a table for the first time to set the value of each table cell.

This function sets the internal integer value stored for this table item. Certain types of table items display their integer value, and other types display the value pointed to by their internal pointer value. See the TableItemStyleType description for details. If you set the integer value of an item that displays its pointer value, it is not an error. An application can store whatever value it wants in the integer value field; however, be aware that this has nothing to do with the value displayed by such a table cell.

See Also

TblGetItemInt(), TblSetItemPtr()

TblSetItemPtr Function ^TOP^

Purpose

Sets the item to the specified pointer value.

Declared In

Table.h

Prototype

void TblSetItemPtr (
   TableType *tableP,
   int16_t row,
   int16_t column,
   void *value
)

Parameters

tableP
Pointer to a table.
row
Row number of the item (zero-based).
column
Column number of the item (zero-based).
value
Pointer to data to display in the table item.

Returns

Nothing.

Comments

This function may display a fatal error message if the row or column parameter is invalid.

This function sets the internal pointer value stored for this table item. Certain types of table items display the value pointed to by this pointer, and other types display an integer value. See the TableItemStyleType description for details. If you set the pointer value of an item that displays its integer value, it is not an error. An application can store whatever value it wants in the pointer field; however, be aware that this has nothing to do with the value displayed by such a table cell.

See Also

TblGetItemPtr(), TblSetItemInt()

TblSetItemStyle Function ^TOP^

Purpose

Sets the type of item to display; for example, text, numbers, dates, and so on.

Declared In

Table.h

Prototype

void TblSetItemStyle (
   TableType *tableP,
   int16_t row,
   int16_t column,
   TableItemStyleType type
)

Parameters

tableP
Pointer to a table.
row
Row number of the item (zero-based).
column
Column number of the item (zero-based).
type
The type of item, such as an editable text field or a check box. See TableItemStyleType for a list of possible values.

Returns

Nothing.

Comments

This function may display a fatal error message if the row or column parameter is invalid.

Applications typically use this function when first setting up and initializing a table; you do not dynamically change item styles.

Follow this function with a call to either TblSetItemInt() or TblSetItemPtr() to set the value displayed by the table item. You should call one or the other of these functions depending on the type of table item you specified. See the TableItemStyleType description for details.

Note also that a table column always contains items of the same type.

Example

The following code initializes a table:


for (row = 0; row < rowsInTable; row++) { 
  TblSetItemStyle (table, row, completedColumn,  
    checkboxTableItem); 
  TblSetItemStyle (table, row, priorityColumn,  
    numericTableItem); 
  TblSetItemStyle (table, row, descColumn, textTableItem); 
  TblSetItemStyle (table, row, dueDateColumn,  
    customTableItem); 
  TblSetItemStyle (table, row, categoryColumn, 
    customTableItem); 
} 

See Also

TblSetCustomDrawProcedure()

TblSetLoadDataProcedure Function ^TOP^

Purpose

Sets the load-data callback procedure for the specified column.

Declared In

Table.h

Prototype

void TblSetLoadDataProcedure (
   TableType *tableP,
   int16_t column,
   TableLoadDataFuncPtr loadDataCallback
)

Parameters

tableP
Pointer to a table.
column
Column number (zero-based).
loadDataCallback
Callback procedure. See TableLoadDataFuncType().

Returns

Nothing.

Comments

The callback procedure is used to load the data values of a table item. See the TableLoadDataFuncType() for more information on writing the callback function.

You typically use this function when first setting up and initializing a table.

See Also

TblSetCustomDrawProcedure()

TblSetRowData Function ^TOP^

Purpose

Sets the data value of the specified row. The data value is a placeholder for application-specific values.

Declared In

Table.h

Prototype

void TblSetRowData (
   TableType *tableP,
   int16_t row,
   uint32_t data
)

Parameters

tableP
Pointer to a table.
row
Row number (zero-based).
data
Application-specific data value to store for this row. For example, the Date Book and To Do applications use this field to store the unique ID of the database record displayed by this row.

Returns

Nothing.

Comments

This function may display a fatal error message if the row parameter is invalid.

See Also

TblGetRowData(), TblFindRowData()

TblSetRowHeight Function ^TOP^

Purpose

Sets the height of the specified row.

Declared In

Table.h

Prototype

void TblSetRowHeight (
   TableType *tableP,
   int16_t row,
   Coord height
)

Parameters

tableP
Pointer to a table.
row
Row number (zero-based).
height
New height in standard coordinates.

Returns

Nothing.

Comments

This function may display a fatal error message if the row parameter is invalid.

See Also

TblGetRowHeight(), TblSetRowStaticHeight()

TblSetRowID Function ^TOP^

Purpose

Sets the ID value of the specified row.

Declared In

Table.h

Prototype

void TblSetRowID (
   TableType *tableP,
   int16_t row,
   uint16_t id
)

Parameters

tableP
Pointer to a table.
row
Row number (zero-based).
id
ID to identify a row.

Returns

Nothing.

Comments

This function may display a fatal error message if the row parameter is invalid.

See Also

TblGetRowID(), TblFindRowID()

TblSetRowMasked Function ^TOP^

Purpose

Sets a row in a table to masked or unmasked.

Declared In

Table.h

Prototype

void TblSetRowMasked (
   TableType *tableP,
   int16_t row,
   Boolean masked
)

Parameters

tableP
Pointer to a table.
row
Row number (zero-based).
masked
true to have the row be masked, false otherwise.

Returns

Nothing.

Comments

Masked cells are displayed as shaded. You should call this function before drawing or redrawing the table. If a table row contains a private database record and the user has set the display preference for private records to masked, you must call this function on that row.

Note that a table cell is not masked unless both its row and column are masked. This allows non-private information in the row item to remain visible. For example, the Date Book application shows the time for a private appointment, but it does not show the description.

Example

The following example shows how to mask private records:


uint16_t attr; 
privateRecordViewEnum privateRecordStatus;  
Boolean masked; 
  
privateRecordStatus = (privateRecordViewEnum) 
  PrefGetPreference(prefShowPrivateRecords); 
.... 
DmGetRecordAttr (ToDoDB, recordNum, &attr); 
masked = ((attr & dmRecAttrSecret) &&  
  (privateRecordStatus == maskPrivateRecords)); 
TblSetRowMasked(tableP, row, masked); 

See Also

TblRowMasked(), TblSetColumnMasked(), SecSelectViewStatus()

TblSetRowSelectable Function ^TOP^

Purpose

Sets a row in a table to selectable or unselectable.

Declared In

Table.h

Prototype

void TblSetRowSelectable (
   TableType *tableP,
   int16_t row,
   Boolean selectable
)

Parameters

tableP
Pointer to a table.
row
Row number (zero-based).
selectable
true or false.

Returns

Nothing.

Comments

This function may display a fatal error message if the row parameter is invalid.

See Also

TblRowSelectable(), TblSetRowUsable()

TblSetRowStaticHeight Function ^TOP^

Purpose

Sets the static height attribute of a row.

Declared In

Table.h

Prototype

void TblSetRowStaticHeight (
   TableType *tableP,
   int16_t row,
   Boolean staticHeight
)

Parameters

tableP
Pointer to a table.
row
Row number (zero-based).
staticHeight
true to set the static height, false to unset it.

Returns

Nothing.

Comments

A row that has its static height attribute set will not expand or contract the height of the row as text is added or removed from a text item.

This function may display a fatal error message if the row parameter is invalid.

TblSetRowUsable Function ^TOP^

Purpose

Sets a row in a table to usable or unusable. Rows that are not usable do not display.

Declared In

Table.h

Prototype

void TblSetRowUsable (
   TableType *tableP,
   int16_t row,
   Boolean usable
)

Parameters

tableP
Pointer to a table.
row
Row number (zero-based).
usable
true or false.

Returns

Nothing.

Comments

This function may display a fatal error message if the row parameter is invalid.

See Also

TblRowUsable(), TblSetRowSelectable()

TblSetSaveDataProcedure Function ^TOP^

Purpose

Sets the save-data callback function for the specified column.

Declared In

Table.h

Prototype

void TblSetSaveDataProcedure (
   TableType *tableP,
   int16_t column,
   TableSaveDataFuncPtr saveDataCallback
)

Parameters

tableP
Pointer to a table.
column
Column number (zero-based).
saveDataCallback
Callback function. See TableSaveDataFuncType().

Returns

Nothing.

Comments

The callback function is called when the table determines the data of a text field needs to be saved.

This function may display a fatal error message if the column parameter is invalid.

See Also

TblSetCustomDrawProcedure()

TblSetSelection Function ^TOP^

Purpose

Sets a table item.

Declared In

Table.h

Prototype

void TblSetSelection (
   TableType *tableP,
   int16_t row,
   int16_t column
)

Parameters

tableP
Pointer to a table.
row
Table row.
column
Table column.

Returns

Nothing.

Comments

This function sets a table item, determined by the row and column parameters, as the current selection. This function does not update the display. To do so, you must call TblInvalidate(). Do not call TblDrawTable() directly unless your code is handling a frmUpdateEvent.

See Also

TblGetNumberOfColumns(), TblGetTopRow()

TblUnhighlightSelection Function ^TOP^

Purpose

Unhighlights the currently selected item in a table.

Declared In

Table.h

Prototype

void TblUnhighlightSelection (
   TableType *tableP
)

Parameters

tableP
Pointer to a table.

Returns

Nothing.

Application-Defined Functions ^TOP^

TableDrawItemFuncType Function ^TOP^

Purpose

Draws a custom table item.

Declared In

Table.h

Prototype

void TableDrawItemFuncType (
   void *tableP,
   int16_t row,
   int16_t column,
   RectangleType *bounds
)

Parameters

tableP
Pointer to a table.
row
Row number of the item to be drawn (zero-based).
column
Column number of the item to be drawn (zero-based).
bounds
The area of the screen in which the item is to be drawn. See RectangleType.

Returns

Nothing.

Comments

This function is called during TblDrawTable() and TblRedrawTable().

You implement a custom drawing function when your table contains items of type customTableItem (to draw the entire item) or narrowTextTableItem (to draw whatever is required in the space between the text and the right edge of the table cell).

You may implement a custom drawing function to include any style of information in the table. If you don't like the way a predefined item is drawn, you may prefer to use a customTableItem instead. For example, if you want to include a date in your table but you want it to show the year as well as the month and day, you should implement a custom drawing function.

Compatibility

Previously, this callback function never had to do anything special to draw a selected table item. The operating system would swap the foreground and background colors for selected table items after the callback function returned. In Palm OS Cobalt, this is no longer possible. The Palm OS Cobalt table drawing code sets the colors that the table item should use before calling this callback function. If the item is not selected, it sets the colors to the normal table colors. If the item is selected, it sets the colors to the highlighted colors when appropriate.

If your callback function sets its own colors, it must check to see if it is drawing an item that should be highlighted and adjust its color scheme accordingly.

  • Use TblGetSelection() to determine what the currently selected item is. If the row and column it returns match the row and column passed to the callback function, then you should draw the item as highlighted.
  • If you have set the edit indicator flag for the column that is passed in, the function TblEditing() returns true, and the row returned by TblGetSelection() matches the row passed into the callback function, the table item should be drawn as highlighted to indicate that the item is in the row currently being edited.

    There is no function to check whether a column has the edit indicator flag set, so your code will need to keep track of which custom drawn columns should have an edit indicator.

    Listing 34.1 shows some code that determines if the cell should draw as selected.

You only need to worry about setting the appropriate color if the custom drawn item uses its own color scheme. If the item uses the colors currently set in the UI color table, then the operating system handles setting the color for you. This is true whether the application uses the system default application colors or it uses UIColorSetTableEntry() to set a color scheme before this callback function is called.

Listing 34.1  Determining if an item should draw as selected


void MyCustomDrawItemFunction(void *tableP, int16_t row, 
int16_t column, RectangleType *bounds) { 
   int16_t selectedRow, selectedColumn; 
   Boolean drawAsSelected = false; 
 
   if (TblGetSelection((TableType *)tableP, &selectedRow,  
         &selectedColumn) { 
      if (selectedRow == row) { 
         if (selectedColumn == column)  
            drawAsSelected = true; 
          else if (TblEditing((TableType *)tableP) &&  
               (column == myColumnWithEditIndicator))  
            drawAsSelected = true; 
      } 
   } 
   if (drawAsSelected) 
      // Set colors to highlighted colors.  
   else 
      // Set colors to normal colors.  
   // Now draw the item.  
} 

See Also

TblSetCustomDrawProcedure()

TableLoadDataFuncType Function ^TOP^

Purpose

Loads data into a column.

Declared In

Table.h

Prototype

status_t TableLoadDataFuncType (
   void *tableP,
   int16_t row,
   int16_t column,
   Boolean editable,
   MemHandle *dataH,
   int16_t *dataOffset,
   int16_t *dataSize,
   FieldPtr fld
)

Parameters

tableP
Pointer to a table.
row
Row number of the table item to load.
column
Column number of the table item to load.
editable
If true, the table is currently being edited. If false, the table is being drawn but not necessarily being edited.
dataH
Unlocked handle of a block containing a null-terminated text string.
dataOffset
Offset from start of block to start of the text string.
dataSize
Allocated size of text string, not the string length.
fld
Pointer to the text field in this table cell.

Returns

errNone upon success or an error if unsuccessful.

Comments

This function is called in two cases: when a text field item is being drawn (TblDrawTable() or TblRedrawTable()) and when a text field item is being selected (part of TblHandleEvent()'s handling of tblEnterEvent). If this function returns an error (any nonzero value) and the item is being selected, then the item is not selected and the table's editing attribute is set to false.

You return the same values for dataH, dataOffset, and dataSize that you would pass to FldSetText(). That is, you can use this function to point the table cell's text field to a string in a database record so that you can edit that string directly using text field routines. To do so, return the handle to a database record in dataH, the offset from the start of the record to the start of the string in dataOffset, and the allocated size of the string in dataSize.

The handle that you return from this function is assumed to contain a null-terminated string starting at dataOffset bytes in the memory chunk. The string should be between 0 and dataSize - 1 bytes in length.

You are responsible for freeing the memory associated with the dataH parameter. You can do so in the TableSaveDataFuncType() function, but it is only called for a cell that has been edited. For non-editable text cells or text cells that are editable but were never selected, free the memory when you close the form.

The fld pointer passed to your function has already been initialized with default values by the table code. If you want to override a field's attributes (for example, if you want to change the underline mode) you can do so in this function.

See Also

TblDrawTable(), TblHandleEvent(), TableLoadDataFuncType()

TableSaveDataFuncType Function ^TOP^

Purpose

Saves the data associated with a text field.

Declared In

Table.h

Prototype

Boolean TableSaveDataFuncType (
   void *tableP,
   int16_t row,
   int16_t column
)

Parameters

tableP
Pointer to a table.
row
Row number of the table item to load.
column
Column number of the table item to load.

Returns

true if the table should be redrawn, or false if the table does not need to be redrawn.

Comments

This is called before the memory associated with the currently selected text field in a table cell is freed. Implement this function if you need to do any special cleanup before this memory is freed.

This function is called only when the currently selected editable text field is releasing the focus. You can use TblGetCurrentField() to retrieve a pointer to this field. It is called only on the currently selected field, not on any other fields in the table.

Note that the table manager already disassociates the memory handle from the text field for you so that the memory associated with your data is not freed when the field is freed. The table manager also calls FldCompactText() for you.

If the text handle you returned in your TableLoadDataFuncType() callback points to a string on the dynamic heap, you should implement this callback function to store or free the handle. You can use FldGetTextHandle() to obtain the handle.

If you return true from this function, TblRedrawTable() is called. You should mark invalid any table rows that you want redrawn before returning.

See Also

TblSetSaveDataProcedure()