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

20    Tables

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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

For more information on tables, see the section "Tables" in the Palm OS Programmer's Companion, vol. I.

Table Data Structures ^TOP^

TableAttrType Struct ^TOP^

Purpose

The TableAttrType bit field defines the visible characteristics of the table.


WARNING! PalmSource, Inc. does not support or provide backward compatibility for the TableAttrType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.

Prototype

typedef struct {
UInt16 visible:1;
UInt16 editable:1;
UInt16 editing:1;
UInt16 selected:1;
UInt16 hasScrollBar:1;
UInt16 reserved:11;
} TableAttrType;

Your code should treat the TableAttrType bit field as opaque. Use the functions specified in the descriptions below to retrieve and set each value. Do not attempt to change member values directly.

Fields

visible
If set, the table is drawn on the screen. The value of this field is set by TblDrawTable() and cleared by TblEraseTable().
editable
If set, the user can modify the table. You specify this when you create the table resource.
editing
If set, the table is in edit mode. The table is in edit mode while the user edits a text item. The value of this field is returned by TblEditing().
selected
If set, the current item (as identified by the TableType fields currentRow and currentColumn) is selected. Use TblGetSelection() to retrieve this value.
hasScrollBar
If set, the table has a scroll bar. Note that this attribute can only be set programmatically. See TblHasScrollBar().

TableColumnAttrType Struct ^TOP^

Purpose

The TableColumnAttrType structure defines a column in a table.


WARNING! PalmSource, Inc. does not support or provide backward compatibility for the TableColumnAttrType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.

Prototype

typedef struct {
Coord width;
UInt16 reserved1 : 5;
UInt16 masked : 1;
UInt16 editIndicator : 1;
UInt16 usable : 1;
UInt16 reserved2 : 8;
Coord spacing;
TableDrawItemFuncPtr drawCallback;
TableLoadDataFuncPtr loadDataCallback;
TableSaveDataFuncPtr saveDataCallback;
} TableColumnAttrType;

Your code should treat the TableColumnAttrType structure as opaque. Use the functions specified in the descriptions below to retrieve and set each value. Do not attempt to change structure member values directly.

Fields

width
The column's width in pixels. See TblGetColumnWidth() and TblSetColumnWidth().
reserved1
Reserved for future use.
masked
If true and the item's row also has a masked attribute of true, the table cell is drawn on the screen but is shaded to obscure the information that it contains. See TblSetColumnMasked().
editIndicator
If true, items in the column should be highlighted if selected while in edit mode. If false, items in the column should not be highlighted. By default, text field items are highlighted in edit mode, but all other types of items are not highlighted. The default can be overridden with TblSetColumnEditIndicator().
usable
If false, the column is not considered part of the current interface of the application, and it doesn't appear on screen. See TblSetColumnUsable().
reserved2
Reserved for future use.
spacing
The spacing in pixels between this column and the next column. See TblGetColumnSpacing() and TblSetColumnSpacing().
drawCallback
Pointer to a function that draws custom items in the column. This function is called during TblDrawTable() and TblRedrawTable(). See TblSetCustomDrawProcedure().
loadDataCallback
Pointer to a function that loads data into the column. This function is called during TblDrawTable() and TblRedrawTable(). See TblSetLoadDataProcedure().
saveDataCallback
Pointer to a function that saves the data in the column. Called when the focus moves from one table cell to another and when the table loses focus entirely. See TblSetSaveDataProcedure().

Compatibility

The masked field is defined only if 3.5 New Feature Set is present.

TableItemPtr Typedef ^TOP^

Purpose

A TableItemPtr points to a TableItemType.

Prototype

typedef TableItemType *TableItemPtr;

TableItemType Struct ^TOP^

Purpose

The TableItemType structure defines an item, or cell, within the table.


WARNING! PalmSource, Inc. does not support or provide backward compatibility for the TableItemType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.

Prototype

typedef struct {
TableItemStyleType itemType;
FontID fontID;
Int16 intValue;
Char *ptr;
} TableItemType;

Your code should treat the TableItemType structure as opaque. Use the functions specified in the descriptions below to retrieve and set each value. Do not attempt to change structure member values directly.


NOTE: None of the table items create memory that you need to free. The table manager handles all of the allocating and deallocating of memory for table items. The only memory you are responsible for freeing is the memory handle containing the text that you want displayed in editable text fields. (See TableLoadDataFuncType().)

Fields

itemType
The type of the item, such as a control, a text label, and so on. TblSetItemStyle() sets this value. The rest of the fields in this struct are either used or not used depending on the itemType. See Table 20.1.
fontID
ID of the font used to display the item's text. TblGetItemFont() and TblSetItemFont() retrieve and set this value.
intValue
Integer value of the item. TblGetItemInt() and TblSetItemInt() retrieve and set this value.
ptr
Pointer to the item's text. TblGetItemPtr() and TblSetItemPtr() retrieve and set this value.
All text items have a maximum of tableMaxTextItemSize.

The following table lists the possible values for the itemType field, describes how each type is drawn, describes which other fields are used for each itemType, and provides special instructions for setting those fields. Note in particular that the fontID field is often not used. Instead, certain items are displayed in a standard font. These are noted in the last column of this table.

Table 20.1  TableItemType fields

ItemType

Description

TableItemType Fields Used

checkboxTableItem

A checkbox control.

intValue

customTableItem

Application-defined cell. The height of the item is fixed at 11 pixels.

None.

Custom items are drawn using the custom drawing function that you implement. See TableDrawItemFuncType(). If you want, you can store data in the intValue and ptr fields.

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

intValue

The intValue field should be a value that can be cast to DateType. DateType is currently defined as a 16-bit number:

yyyyyyymmmmddddd

The first 7 bits are the year given as the offset since 1904, the next 4 bits are the month, and the next 5 bits are the day.

Dates are always drawn in the current font.

labelTableItem

Non-editable text.

ptr

Labels are displayed in the system's default font along with a terminating colon character (':'). Use a

customTableItem or tallCustomTableItem if you don't want a colon.

numericTableItem

Non-editable number.

intValue

Numbers are displayed in the system's default bold font.

popupTriggerTableItem

A list with a pop-up trigger.

intValue

ptr

intValue is the index of the list item that should be displayed.

ptr is a pointer to the list.

Lists are displayed in the system's default font.

tallCustomTableItem

Application-defined cell. The height of the item is equal to the height of the row in which the item is located. This table item type was added in Palm OS 4.0 and is only supported if 4.0 New Feature Set is defined.

None.

Custom items are drawn using the custom drawing function that you implement. See TableDrawItemFuncType(). If you want, you can store data in the intValue and ptr fields.

textTableItem

Editable text field.

fontID

ptr

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.

textWithNoteTableItem

Editable text field and a note icon to the right of the text.

fontID

ptr

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.

timeTableItem

Not implemented.

narrowTextTableItem

Editable text with space reserved on the right side of the cell.

fontID

ptr

intValue

intValue is the number of pixels to reserve 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.

TablePtr Typedef ^TOP^

Purpose

The TablePtr type defines a pointer to a TableType.

Prototype

typedef TableType *TablePtr;

You pass the table's pointer as an argument to all table functions. You can obtain the table's pointer using the function FrmGetObjectPtr() in this way:


tblPtr = FrmGetObjectPtr(frm, 
FrmGetObjectIndex(frm, tblID)); 

where tblID is the resource ID assigned when you created the table.

TableRowAttrType Struct ^TOP^

Purpose

The TableRowAttrType structure defines a row in a table.


WARNING! PalmSource, Inc. does not support or provide backward compatibility for the TableRowAttrType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.

Prototype

typedef struct {
UInt16 id;
Coord height;
UInt32 data;
UInt16 reserved1 : 7;
UInt16 usable : 1;
UInt16 reserved2 : 4;
UInt16 masked : 1;
UInt16 invalid : 1;
UInt16 staticHeight : 1;
UInt16 selectable : 1;
UInt16 reserved3;
} TableRowAttrType;

Your code should treat the TableRowAttrType structure as opaque. Use the functions specified in the descriptions below to retrieve and set each value. Do not attempt to change structure member values directly.

Fields

id
The ID of this row. See TblFindRowID(), TblGetRowID(), and TblSetRowID().
height
Height of the row in pixels. The functions TblSetRowHeight() and TblGetRowHeight() set and retrieve this value.
data
Any application-specific value you want to store in this row. For example, the Datebook and ToDo applications use this field to store the unique ID of the database record that is displayed in this table row. See TblFindRowData(), TblGetRowData(), and TblSetRowData().
reserved1
Reserved for future use.
usable
If false, the row is not considered part of the current interface of the application, and it doesn't appear on screen. Table rows have usable set to false when they are scrolled off the screen. See TblRowUsable() and TblSetRowUsable(). The function TblGetLastUsableRow() returns the row that appears at the bottom of the screen.
masked
If true and the item's column also has a masked attribute of true, the table cell is drawn on the screen but is shaded to obscure the information that it contains. See TblSetRowMasked() and TblRowMasked().
reserved2
Reserved for future use.
invalid
If true, the row needs to be redrawn. See TblRowInvalid(), TblMarkRowInvalid(), and TblMarkTableInvalid().
staticHeight
true if the row height cannot be changed, false otherwise. If false, text fields in this table row will dynamically resize to multiple lines as necessary. See TblSetRowStaticHeight().
selectable
If true, the user can select individual cells in this row. See TblSetRowSelectable() and TblRowSelectable().
reserved3
Reserved for future use.

Compatibility

The masked field is defined only if 3.5 New Feature Set is present.

TableType Struct ^TOP^

Purpose

The TableType structure represents a table.


WARNING! PalmSource, Inc. does not support or provide backward compatibility for the TableType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.

Prototype

typedef struct TableType {
UInt16 id;
RectangleType bounds;
TableAttrType attr;
Int16 numColumns;
Int16 numRows;
Int16 currentRow;
Int16 currentColumn;
Int16 topRow;
TableColumnAttrType *columnAttrs;
TableRowAttrType *rowAttrs;
TableItemPtr items;
FieldType currentField;
} TableType;

Your code should treat the TableType structure as opaque. Use the functions specified in the descriptions below to retrieve and set each value. Do not attempt to change structure member values directly.

Fields

id
ID value you specified when you created the table resource. This ID is included as part of the event data of tblEnterEvent.
bounds
Position and size of the table object. The functions TblGetBounds(), FrmGetObjectBounds(), TblSetBounds(), and FrmSetObjectBounds() retrieve and set this value.
attr
The table's attributes. See TableAttrType.
numColumns
Number of columns displayed by the table object. You specify the number of columns when you create the table resource, and this value cannot be changed. Access with TblGetNumberOfColumns().
numRows
Maximum number of visible rows in the table object.
You specify this value when you create the table resource, and it does not change; however, the total number of rows in a table can change if you insert new rows in a table, and even the number of currently visible rows can change if a text field within a table cell is dynamically resized.
The function TblGetNumberOfRows() returns the value of this field.
currentRow
Row index of the currently selected table cell. Rows are numbered from top to bottom starting with 0. TblGetSelection() and TblSetSelection() retrieve and set the values of currentRow.
currentColumn
Column index of the currently selected table cell. Columns are numbered from left to right starting with 0. If the TableAttrType selected is true, then this table cell is highlighted. If selected is false, the table still considers this the "current" item, but it is not highlighted. TblGetSelection() and TblSetSelection() retrieve and set the values of currentColumn.
topRow
First visible row of the table object. Access with TblGetTopRow().
columnAttrs
An array of each table column's attributes. See TableColumnAttrType.
rowAttrs
An array of each row's attributes, such as its ID, height, and whether or not it is usable, selectable, or invalid. See TableRowAttrType.
items
An array of each item's (table cell's) attributes, such as the item type, font ID, an integer value, and a character pointer. See TableItemType.
currentField
Field object the user is currently editing. The function TblGetCurrentField() retrieves the value of this item.

Table Constants ^TOP^

Constant

Value

Description

tableDefaultColumnSpacing

1

Never used.

tableNoteIndicatorHeight

11

The height in pixels of the note indicator for tables items of type textWithNoteTableItem.

tableNoteIndicatorWidth

7

The width in pixels of the note indicator for tables items of type textWithNoteTableItem.

tableMaxTextItemSize

255

The maximum length of an editable text field within a table cell.

tblUnusableRow

0xffff

Value returned by TblGetLastUsableRow() if none of the table's rows are usable. This value is only available in version 3.5 and higher.

Table Resource ^TOP^

The Table Resource (tTBL) represents a table on screen. See Palm OS User Interface Guidelines for more information.

Table Functions ^TOP^

TblDrawTable Function ^TOP^

Purpose

Draw a table.

Declared In

Table.h

Prototype

void TblDrawTable (
   TableType*tableP
)

Parameters

tableP
Pointer to a table object. (See TableType.)

Returns

Returns nothing.

Comments

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

This function draws the entire table, marking all rows valid before drawing. See the TableItemType struct 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 TableLoadDataFunc 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().

Compatibility

Color support and masked private records are only supported in Palm OS® version 3.5 and higher.

In versions earlier than 3.5, this function did not erase table cells before it drew them. In earlier releases, consider calling TblEraseTable() before calling this function, particularly if the entire table has changed, as the visual effect of drawing over a white background may be more pleasing.

See Also

TblEraseTable(), TblRedrawTable(), TblSetCustomDrawProcedure()

TblEditing Function ^TOP^

Purpose

Check whether a table is in edit mode.

Declared In

Table.h

Prototype

Boolean TblEditing (
   constTableType*tableP
)

Parameters

tableP
Pointer to a table object. (See TableType.)

Returns

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 a the user places the pen on a note in a textWithNoteTableItem or when the table releases the focus (TblReleaseFocus()).

TblEraseTable Function ^TOP^

Purpose

Erase a table object.

Declared In

Table.h

Prototype

void TblEraseTable (
   TableType*tableP
)

Parameters

tableP
Pointer to a table object. (See TableType.)

Returns

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

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

Declared In

Table.h

Prototype

Boolean TblFindRowData (
   constTableType*tableP,
   UInt32data,
   Int16*rowP
)

Parameters

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

Returns

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(), TableRowAttrType

TblFindRowID Function ^TOP^

Purpose

Return the number of the row with the specified ID.

Declared In

Table.h

Prototype

Boolean TblFindRowID (
   constTableType*tableP,
   UInt16id,
   Int16*rowP
)

Parameters

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

Returns

Returns true if a match was found, false otherwise.

See Also

TblSetRowID(), TblFindRowData(), TableRowAttrType

TblGetBounds Function ^TOP^

Purpose

Return the bounds of a table.

Declared In

Table.h

Prototype

void TblGetBounds (
   constTableType*tableP,
   RectangleType*rP
)

Parameters

tableP
Pointer to a table object. (See TableType.)
rP
A RectangleType structure in which the bounds are returned.

Returns

Returns nothing. The rP parameter contains the bounds.

See Also

TblGetItemBounds()

TblGetColumnSpacing Function ^TOP^

Purpose

Return the spacing after the specified column.

Declared In

Table.h

Prototype

Coord TblGetColumnSpacing(
   constTableType*tableP,
   Int16column
)

Parameters

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

Returns

Returns the spacing after column (in pixels).

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

See Also

TblGetColumnWidth(), TblSetColumnSpacing(), TblSetColumnUsable()

TblGetColumnWidth Function ^TOP^

Purpose

Return the width of the specified column.

Declared In

Table.h

Prototype

Coord TblGetColumnWidth (
   constTableType*tableP,
   Int16column
)

Parameters

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

Returns

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

See Also

TblGetColumnSpacing(), TblSetColumnWidth(), TblSetColumnUsable()

TblGetCurrentField Function ^TOP^

Purpose

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

Declared In

Table.h

Prototype

FieldPtr TblGetCurrentField(
   constTableType*tableP
)

Parameters

tableP
Pointer to a table object. (See TableType.)

Returns

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

Return the bounds of an item in a table.

Declared In

Table.h

Prototype

void TblGetItemBounds (
   constTableType*tableP,
   Int16row,
   Int16column,
   RectangleType*rP
)

Parameters

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

Returns

Returns nothing. Stores the bounds in rP. This function may raise a fatal exception if the row or column parameter specifies a row or column that does not appear on screen.

TblGetItemFont Function ^TOP^

Purpose

Return the font used to display a table item.

Declared In

Table.h

Prototype

FontID TblGetItemFont (
   constTableType*tableP,
   Int16row,
   Int16column
)

Parameters

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

Returns

Returns the ID of the font used for the table item at the row and column indicated. 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.

Comments

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

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

TblSetItemFont()

TblGetItemInt Function ^TOP^

Purpose

Return the integer value stored in a table item.

Declared In

Table.h

Prototype

Int16 TblGetItemInt (
   constTableType*tableP,
   Int16row,
   Int16column
)

Parameters

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

Returns

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

Comments

This function returns the value stored in the intValue field for this table item. Certain types of table items display the value stored in intValue, and other types display the value pointed to by the ptr field. See the TableItemType description for details. If the intValue was never set for this table item, this function returns 0.

See Also

TblSetItemInt(), TblGetItemPtr()

TblGetItemPtr Function ^TOP^

Purpose

Return the pointer value stored in a table item

Declared In

Table.h

Prototype

void *TblGetItemPtr (
   constTableType*tableP,
   Int16row,
   Int16column
)

Parameters

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

Returns

Returns the item's pointer value or NULL if the item does not have a pointer value. This function may display a fatal message if the row or column parameter is invalid.

Comments

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

Compatibility

Implemented only if 3.5 New Feature Set is present. In earlier versions, you can implement this function using the following code:


return tableP->items[row * tableP->numColumns +
column].ptr; 

See Also

TblSetItemPtr()

TblGetLastUsableRow Function ^TOP^

Purpose

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

Declared In

Table.h

Prototype

Int16 TblGetLastUsableRow(
   constTableType*tableP
)

Parameters

tableP
Pointer to a table object. (See TableType.)

Returns

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

See Also

TblGetRowData(), TblGetRowID()

TblGetNumberOfColumns Function ^TOP^

Purpose

Return the number of columns in a table.

Declared In

Table.h

Prototype

Int16 TblGetNumberOfColumns(
   constTableType*tableP
)

Parameters

tableP
Pointer to a TableType.

Returns

This function returns the number of columns in a table.

Compatibility

Implemented only if 4.0 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TblGlueGetNumberOfColumns. For more information, see Chapter 80, "PalmOSGlue Library."

See Also

TblGetTopRow(), TblSetSelection()

TblGetNumberOfRows Function ^TOP^

Purpose

Return the number of rows in a table.

Declared In

Table.h

Prototype

Int16 TblGetNumberOfRows(
   constTableType*tableP
)

Parameters

tableP
Pointer to a table object. (See TableType.)

Returns

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

Return the data value of the specified row.

Declared In

Table.h

Prototype

UInt32 TblGetRowData (
   constTableType*tableP,
   Int16row
)

Parameters

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

Returns

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

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

See Also

TblFindRowData(), TblSetRowData(), TableRowAttrType

TblGetRowHeight Function ^TOP^

Purpose

Return the height of the specified row.

Declared In

Table.h

Prototype

Coord TblGetRowHeight (
   constTableType*tableP,
   Int16row
)

Parameters

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

Returns

Returns the height in pixels. This function may display a fatal error message if the row parameter is invalid.

See Also

TblGetItemBounds(), TblSetRowHeight()

TblGetRowID Function ^TOP^

Purpose

Return the ID value of the specified row.

Declared In

Table.h

Prototype

UInt16 TblGetRowID (
   constTableType*tableP,
   Int16row
)

Parameters

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

Returns

Returns the ID value of the row in the table.

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

See Also

TblGetRowData(), TblSetRowID(), TblFindRowID(), TableRowAttrType

TblGetSelection Function ^TOP^

Purpose

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

Declared In

Table.h

Prototype

Boolean TblGetSelection (
   constTableType*tableP,
   Int16*rowP,
   Int16*columnP
)

Parameters

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

Returns

Returns true if the item is highlighted, false if not.

See Also

TblSetRowSelectable()

TblGetTopRow Function ^TOP^

Purpose

Return the top row visible row of a table.

Declared In

Table.h

Prototype

Int16 TblGetTopRow(
   constTableType*tableP
)

Parameters

tableP
Pointer to a TableType.

Returns

This function returns the top visible row in a table.

Compatibility

Implemented only if 4.0 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TblGlueGetToRow. For more information, see Chapter 80, "PalmOSGlue Library."

See Also

TblGetNumberOfColumns(), TblSetSelection()

TblGrabFocus Function ^TOP^

Purpose

Put a table into edit mode.

Declared In

Table.h

Prototype

void TblGrabFocus (
   TableType*tableP,
   Int16row,
   Int16column
)

Parameters

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

Returns

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

Comments

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 object that previously had it and sets the form's internal structures. After calling this function, you must call FldGrabFocus() to display the insertion point in the field. (You can use TblGetCurrentField() to obtain a pointer to the field.)

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


static void EditViewRestoreEditState () { 
Int16row; 
FormPtrfrm; 
TablePtrtable; 
FieldPtrfld; 
 
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); 
FldGrabFocus (fld); 
} 

See Also

TblReleaseFocus()

TblHandleEvent Function ^TOP^

Purpose

Handle an event for the table.

Declared In

Table.h

Prototype

Boolean TblHandleEvent (
   TableType*tableP,
   EventType*event
)

Parameters

tableP
Pointer to a table object. (See TableType.)
event
The event to be handled.

Returns

Returns true if the event was handled, false if it was not.

Comments

Returns false if the table is not an editable table.

If the table is editable, this function passes along any keyDownEvent, fldEnterEvent, or menuCmdBarOpenEvent 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 FieldAttrType and FldMakeFullyVisible() for more information.

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

Set the hasScrollBar attribute in the table. (See TableAttrType.)

Declared In

Table.h

Prototype

void TblHasScrollBar (
   TableType*tableP,
   BooleanhasScrollBar
)

Parameters

tableP
Pointer to a table object. (See TableType.)
hasScrollBar
true to set the attribute, false to unset it.

Returns

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.

Compatibility

Implemented only if 2.0 New Feature Set is present.

TblInsertRow Function ^TOP^

Purpose

Insert a row into the table before the specified row.

Declared In

Table.h

Prototype

void TblInsertRow (
   TableType*tableP,
   Int16row
)

Parameters

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

Returns

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 with a usable value of false. (See TableRowAttrType.)

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 TblRedrawTable() when you are ready to draw the table.

See Also

TblRemoveRow(), TblSetRowUsable(), TblSetRowSelectable()

TblMarkRowInvalid Function ^TOP^

Purpose

Mark the row invalid.

Declared In

Table.h

Prototype

void TblMarkRowInvalid (
   TableType*tableP,
   Int16row
)

Parameters

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

Returns

Returns nothing.

Comments

After calling this function, call TblRedrawTable() to redraw all rows marked invalid.

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

See Also

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

TblMarkTableInvalid Function ^TOP^

Purpose

Mark all the rows in a table invalid.

Declared In

Table.h

Prototype

void TblMarkTableInvalid (
   TableType*tableP
)

Parameters

tableP
Pointer to a table object. (See TableType.)

Returns

Returns nothing.

Comments

After calling this function, you must call TblRedrawTable() to redraw all rows.

See Also

TblEraseTable(), TblRedrawTable(), TableRowAttrType

TblRedrawTable Function ^TOP^

Purpose

Redraw the rows of the table that are marked invalid.

Declared In

Table.h

Prototype

void TblRedrawTable (
   TableType*tableP
)

Parameters

tableP
Pointer to a table object. (See TableType.)

Returns

Returns nothing.

Comments

This function draws the invalid rows in the table. See the TableItemType struct 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 TableLoadDataFunc 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().

Compatibility

Color support and masked private records are only supported in Palm OS version 3.5 and higher.

See Also

TblMarkTableInvalid(), TblMarkRowInvalid(), TblDrawTable()

TblReleaseFocus Function ^TOP^

Purpose

Release the focus.

Declared In

Table.h

Prototype

void TblReleaseFocus (
   TableType*tableP
)

Parameters

tableP
Pointer to a table object.

Returns

Returns nothing.

Comments

You typically do not call this function yourself. Instead, call FrmSetFocus() with an object 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

Remove the specified row from the table.

Declared In

Table.h

Prototype

void TblRemoveRow (
   TableType*tableP,
   Int16row
)

Parameters

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

Returns

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

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 update the display, call TblRedrawTable().

See Also

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

TblRowInvalid Function ^TOP^

Purpose

Return whether a row is invalid.

Declared In

Table.h

Prototype

Boolean TblRowInvalid (
   constTableType*tableP,
   Int16row
)

Parameters

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

Returns

Returns true if the row is invalid, false if it's valid. This function may raise a fatal error message if the row parameter is invalid.

Comments

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

See Also

TblMarkRowInvalid(), TblMarkTableInvalid()

TblRowMasked Function ^TOP^

Purpose

Return whether a row is masked.

Declared In

Table.h

Prototype

Boolean TblRowMasked (
   constTableType*tableP,
   Int16 row
)

Parameters

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

Returns

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 Datebook application shows the time for a private appointment, but it does not show the description.

Compatibility

Implemented only if 3.5 New Feature Set is present.

See Also

TblSetRowMasked(), TblSetColumnMasked(), TableRowAttrType, SecSelectViewStatus()

TblRowSelectable Function ^TOP^

Purpose

Return whether the specified row is selectable.

Declared In

Table.h

Prototype

Boolean TblRowSelectable(
   constTableType*tableP,
   Int16row
)

Parameters

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

Returns

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

Comments

Rows that are not selectable don't highlight when touched.

See Also

TableRowAttrType

TblRowUsable Function ^TOP^

Purpose

Determine whether the specified row is usable.

Declared In

Table.h

Prototype

Boolean TblRowUsable (
   constTableType*tableP,
   Int16row
)

Parameters

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

Returns

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

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

Comments

Rows that are not usable do not display.

See Also

TblRowSelectable(), TblGetLastUsableRow(), TblSetRowUsable()

TblSelectItem Function ^TOP^

Purpose

Select (highlight) the specified item. If there is already a selected item, it is unhighlighted.

Declared In

Table.h

Prototype

void TblSelectItem (
   TableType*tableP,
   Int16row,
   Int16column
)

Parameters

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

Returns

Returns nothing.

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

Comments

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

This function cannot highlight an entire row; it can only highlight one cell in a row, and it always unhighlights the previously selected table cell. If you want to select an entire row, either create a table that has a single column, or write your own selection code.

If the selected item is a multi-line text field or a text field with a nonstandard height, this function only highlights the top eleven pixels. If you want a larger area highlighted, you must write your own selection code.

See Also

TblRowSelectable(), TblGetItemBounds(), TblGetItemInt()

TblSetBounds Function ^TOP^

Purpose

Sets the bounds of a table.

Declared In

Table.h

Prototype

void TblSetBounds (
   TableType*tableP,
   constRectangleType*rP
)

Parameters

tableP
Pointer to a table object. (See TableType.)
rP
Pointer to a RectangleType structure that specifies the bounds for the table.

Returns

Returns nothing.

Compatibility

Implemented only if 2.0 New Feature Set is present.

TblSetColumnEditIndicator Function ^TOP^

Purpose

Set 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,
   Int16column,
   BooleaneditIndicator
)

Parameters

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

Returns

Returns nothing.

Comments

The edit indicator controls whether the item in the column is highlighted when it is selected. By default, text field items have the editIndicator value of false, while all other table item types have an edit indicator of true.

When the table is drawn, only the leftmost contiguous set of items with the edit indicator set are drawn as highlighted. That is, if columns 1, 2, and 4 have an edit indicator of true and column 3 has an edit indicator of false, only the items in column 1 and 2 are drawn as highlighted when selected. Column 4 items are not drawn as highlighted.

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

TableColumnAttrType

TblSetColumnMasked Function ^TOP^

Purpose

Set whether the column is masked.

Declared In

Table.h

Prototype

void TblSetColumnMasked (
   TableType*tableP,
   Int16column,
   Booleanmasked
)

Parameters

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

Returns

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

Compatibility

Implemented only if 3.5 New Feature Set if present.

See Also

TblRowMasked(), TblSetRowMasked(), TableColumnAttrType, SecSelectViewStatus()

TblSetColumnSpacing Function ^TOP^

Purpose

Set the spacing after the specified column.

Declared In

Table.h

Prototype

void TblSetColumnSpacing (
   TableType*tableP,
   Int16column,
   Coordspacing
)

Parameters

tableP
Pointer to a table object. (See TableType.)
column
Column number (zero-based).
spacing
Spacing after the column in pixels.

Returns

Returns nothing.

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

See Also

TblSetColumnUsable(), TableColumnAttrType

TblSetColumnUsable Function ^TOP^

Purpose

Set a column in a table to usable or unusable.

Declared In

Table.h

Prototype

void TblSetColumnUsable (
   TableType*tableP,
   Int16column,
   Booleanusable
)

Parameters

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

Returns

Returns nothing.

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

Comments

Columns that are not usable do not display.

See Also

TblMarkRowInvalid(), TableColumnAttrType

TblSetColumnWidth Function ^TOP^

Purpose

Set the width of the specified column.

Declared In

Table.h

Prototype

void TblSetColumnWidth (
   TableType*tableP,
   Int16column,
   Coordwidth
)

Parameters

tableP
Pointer to a table object. (See TableType.)
column
Column number (zero-based).
width
Width of the column (in pixels).

Returns

Returns nothing.

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

See Also

TblGetColumnWidth(), TableColumnAttrType

TblSetCustomDrawProcedure Function ^TOP^

Purpose

Set the custom draw callback procedure for the specified column.

Declared In

Table.h

Prototype

void TblSetCustomDrawProcedure (
   TableType*tableP,
   Int16column,
   TableDrawItemFuncPtrdrawCallback
)

Parameters

tableP
Pointer to a table object. (See TableType.)
column
Column number.
drawCallback
Callback function.

Returns

Returns nothing.

Comments

The custom draw callback function is used to draw table items with a TableItemStyleType of customTableItem or tallCustomTableItem. See the TableItemType description for more information.

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

See Also

TableDrawItemFuncType(), TblDrawTable(), TableColumnAttrType

TblSetItemFont Function ^TOP^

Purpose

Set the font used to display a table item.

Declared In

Table.h

Prototype

void TblSetItemFont (
   TableType*tableP,
   Int16row,
   Int16column,
   FontIDfontID
)

Parameters

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

Returns

Returns nothing.

Comments

This function sets the value stored in the fontID field for this table item. Only certain types of table items use the font specified by the fontID field when they are displayed. The TableItemType description specifies what font is used to display each type of table item. It is not an error to set the fontID 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.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

TblGetItemFont()

TblSetItemInt Function ^TOP^

Purpose

Set the integer value of the specified item.

Declared In

Table.h

Prototype

void TblSetItemInt (
   TableType*tableP,
   Int16row,
   Int16column,
   Int16value
)

Parameters

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

Returns

Returns nothing.

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

Comments

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 value stored in the intValue field for this table item. Certain types of table items display the value stored in intValue, and other types display the value pointed to by the ptr field. See the TableItemType description for details. If you set the intValue of an item that displays its ptr value, it is not an error. An application can store whatever value it wants in the intValue 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

Set the item to the specified pointer value.

Declared In

Table.h

Prototype

void TblSetItemPtr (
   TableType*tableP,
   Int16row,
   Int16column,
   void*value
)

Parameters

tableP
Pointer to a table object. (See TableType.)
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

Returns nothing.

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

Comments

This function sets the value stored in the ptr field for this table item. Certain types of table items display the value pointed to by ptr, and other types display the value stored in the intValue field. See the TableItemType description for details. If you set the ptr of an item that displays its intValue, it is not an error. An application can store whatever value it wants in the ptr 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

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

Declared In

Table.h

Prototype

void TblSetItemStyle (
   TableType*tableP,
   Int16row,
   Int16column,
   TableItemStyleTypetype
)

Parameters

tableP
Pointer to a table object. (See TableType.)
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 TableItemType for a list of possible values.

Returns

Returns nothing.

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

Comments

You 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 table in the TableItemType description for details.

Note also that a table column always contains items of the same type. For example, you might initialize a table using this code:


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

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

Declared In

Table.h

Prototype

void TblSetLoadDataProcedure (
   TableType*tableP,
   Int16column,
   TableLoadDataFuncPtrloadDataCallback
)

Parameters

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

Returns

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

Set 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,
   Int16row,
   UInt32data
)

Parameters

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

Returns

Returns nothing.

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

See Also

TblGetRowData(), TblFindRowData()

TblSetRowHeight Function ^TOP^

Purpose

Set the height of the specified row.

Declared In

Table.h

Prototype

void TblSetRowHeight (
   TableType*tableP,
   Int16row,
   Coordheight
)

Parameters

tableP
Pointer to a table object. (See TableType.)
row
Row number (zero-based).
height
New height in pixels.

Returns

Returns nothing.

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

See Also

TblGetRowHeight(), TblSetRowStaticHeight()

TblSetRowID Function ^TOP^

Purpose

Set the ID value of the specified row.

Declared In

Table.h

Prototype

void TblSetRowID (
   TableType*tableP,
   Int16row,
   UInt16id
)

Parameters

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

Returns

Returns nothing.

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

See Also

TblGetRowID(), TblFindRowID(), TableRowAttrType

TblSetRowMasked Function ^TOP^

Purpose

Set a row in a table to masked or unmasked.

Declared In

Table.h

Prototype

void TblSetRowMasked (
   TableType*tableP,
   Int16row,
   Booleanmasked
)

Parameters

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

Returns

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. For example:


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

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 Datebook application shows the time for a private appointment, but it does not show the description.

Compatibility

Implemented only if 3.5 New Feature Set is present.

See Also

TblRowMasked(), TblSetColumnMasked(), TableRowAttrType, SecSelectViewStatus()

TblSetRowSelectable Function ^TOP^

Purpose

Set a row in a table to selectable or nonselectable.

Declared In

Table.h

Prototype

void TblSetRowSelectable (
   TableType*tableP,
   Int16row,
   Booleanselectable
)

Parameters

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

Returns

Returns nothing.

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

Comments

Rows that are not selectable don't highlight when touched.

See Also

TblRowSelectable(), TblSetRowUsable(), TableRowAttrType

TblSetRowStaticHeight Function ^TOP^

Purpose

Set the static height attribute of a row.

Declared In

Table.h

Prototype

void TblSetRowStaticHeight (
   TableType*tableP,
   Int16row,
   BooleanstaticHeight
)

Parameters

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

Returns

Nothing.

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

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.

Compatibility

Implemented only if 2.0 New Feature Set is present.

TblSetRowUsable Function ^TOP^

Purpose

Set 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,
   Int16row,
   Booleanusable
)

Parameters

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

Returns

Returns nothing.

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

See Also

TblRowUsable(), TblSetRowSelectable()

TblSetSaveDataProcedure Function ^TOP^

Purpose

Set the save-data callback procedure for the specified column.

Declared In

Table.h

Prototype

void TblSetSaveDataProcedure (
   TableType*tableP,
   Int16column,
   TableSaveDataFuncPtrsaveDataCallback
)

Parameters

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

Returns

Returns nothing.

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

Comments

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

See Also

TblSetCustomDrawProcedure()

TblSetSelection Function ^TOP^

Purpose

Set a table item.

Declared In

Table.h

Prototype

void TblSetSelection (
   TableType*tableP,
   Int16row,
   Int16column
)

Parameters

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

Returns

Returns nothing.

Comments

This function sets a table item, determined by the row and column arguments, as the current selection. TblDrawTable() must be called afterwards to update the UI.

Compatibility

Implemented only if 4.0 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TblGlueSetSelection. For more information, see Chapter 80, "PalmOSGlue Library."

See Also

TblGetNumberOfColumns(), TblGetTopRow()

TblUnhighlightSelection Function ^TOP^

Purpose

Unhighlight the currently selected item in a table.

Declared In

Table.h

Prototype

void TblUnhighlightSelection (
   TableType*tableP
)

Parameters

tableP
Pointer to a table object. (See TableType.)

Returns

Returns nothing.

Application-Defined Functions ^TOP^

TableDrawItemFuncType Function ^TOP^

Purpose

Draw a custom table item.

Declared In

Table.h

Prototype

void TableDrawItemFuncType (
   void*tableP,
   Int16row,
   Int16column,
   RectangleType*bounds
)

Parameters

tableP
Pointer to a table object. (See TableType.)
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.

Returns

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 or tallCustomTableItem (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 or tallCustomTableItem 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.

See Also

TblSetCustomDrawProcedure(), TableItemType

TableLoadDataFuncType Function ^TOP^

Purpose

Load data into a column.

Declared In

Table.h

Prototype

Err TableLoadDataFuncType (
   void*tableP,
   Int16row,
   Int16column,
   Booleaneditable,
   MemHandle*dataH,
   Int16*dataOffset,
   Int16*dataSize,
   FieldPtrfld
)

Parameters

tableP
Pointer to a table object. (See TableType.)
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

Returns 0 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.

As with FldSetText, 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

Save the data associated with a text field.

Declared In

Table.h

Prototype

Boolean TableSaveDataFuncType (
   void*tableP,
   Int16row,
   Int16column
)

Parameters

tableP
Pointer to a table object. (See TableType.)
row
Row number of the table item to load.
column
Column number of the table item to load.

Returns

Return 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()