|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ResultThis function returns the number of columns in a table. CompatibilityImplemented 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 76, "PalmOSGlue Library." See Also
TblGetNumberOfRows
PurposeReturn the number of rows in a table. PrototypeInt16 TblGetNumberOfRows (const TableType *tableP) Parameters
ResultReturns the maximum number of visible rows in the specified table. CommentsNote 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
PurposeReturn the data value of the specified row. PrototypeUInt32 TblGetRowData (const TableType *tableP, Int16 row) Parameters
ResultReturns 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 AlsoTblFindRowData, TblSetRowData, TableRowAttrType
TblGetRowHeight
PurposeReturn the height of the specified row. PrototypeCoord TblGetRowHeight (const TableType *tableP, Int16 row) Parameters
ResultReturns the height in pixels. This function may display a fatal error message if the row parameter is invalid. See AlsoTblGetItemBounds, TblSetRowHeight
TblGetRowID
PurposeReturn the ID value of the specified row. PrototypeUInt16 TblGetRowID (const TableType *tableP, Int16 row) Parameters
ResultReturns the ID value of the row in the table. This function may display a fatal error message if the row parameter is invalid. See AlsoTblGetRowData, TblSetRowID, TblFindRowID, TableRowAttrType
TblGetSelection
PurposeReturn the row and column of the currently selected table item. PrototypeBoolean TblGetSelection (const TableType *tableP, Int16 *rowP, Int16 *columnP) Parameters
ResultReturns true if the item is highlighted, false if not. See Also
|
-> tableP | Pointer to a TableType. |
This function returns the top visible row in a table. |
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 76, "PalmOSGlue Library."
TblGetNumberOfColumns, TblSetSelection
void TblGrabFocus (TableType *tableP, Int16 row, Int16 column)
-> 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 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.
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 () { Int16 row; FormPtr frm; TablePtr table; FieldPtr 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); FldGrabFocus (fld); }
Handle an event for the table.
Boolean TblHandleEvent (TableType *tableP, EventType *event)
-> tableP | Pointer to a table object. (See TableType.) |
-> event | The event to be handled. |
Returns true if the event was handled, false if it was not.
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.
Set the hasScrollBar attribute in the table. (See TableAttrType.)
void TblHasScrollBar (TableType *tableP, Boolean hasScrollBar)
-> tableP | Pointer to a table object. (See TableType.) |
-> hasScrollBar | true to set the attribute, false to unset it. |
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.
Implemented only if 2.0 New Feature Set is present.
Insert a row into the table before the specified row.
void TblInsertRow (TableType *tableP, Int16 row)
-> tableP | Pointer to a table object. (See TableType.) |
-> row | Row to insert (zero-based). |
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.
TblRemoveRow, TblSetRowUsable, TblSetRowSelectable
void TblMarkRowInvalid (TableType *tableP, Int16 row)
-> tableP | Pointer to a table object. (See TableType.) |
-> row | Row number (zero-based). |
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.
TblRemoveRow, TblSetRowUsable, TblSetRowSelectable, TblMarkTableInvalid, TblRowInvalid, TableRowAttrType
Mark all the rows in a table invalid.
void TblMarkTableInvalid (TableType *tableP)
-> tableP | Pointer to a table object. (See TableType.) |
After calling this function, you must call TblRedrawTable to redraw all rows.
TblEraseTable, TblRedrawTable, TableRowAttrType
Redraw the rows of the table that are marked invalid.
void TblRedrawTable (TableType *tableP)
-> tableP | Pointer to a table object. (See TableType.) |
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 or customTableItem 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.
Color support and masked private records are only supported in Palm OS version 3.5 and higher.
TblMarkTableInvalid, TblMarkRowInvalid, TblDrawTable
void TblReleaseFocus (TableType *tableP)
-> tableP | Pointer to a table object. |
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).
Remove the specified row from the table.
void TblRemoveRow (TableType *tableP, Int16 row)
-> tableP | Pointer to a table object. (See TableType.) |
-> row | Row to remove (zero-based). |
Returns nothing. This function may raise a fatal error message if an invalid row is specified.
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.
TblInsertRow, TblSetRowUsable, TblSetRowSelectable, TblMarkRowInvalid
Return whether a row is invalid.
Boolean TblRowInvalid (const TableType *tableP, Int16 row)
-> tableP | Pointer to a table object. (See TableType.) |
-> row | Row number (zero-based). |
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.
Invalid rows need to be redrawn. Use TblRedrawTable to do so.
TblMarkRowInvalid, TblMarkTableInvalid
Return whether a row is masked.
Boolean TblRowMasked (const TableType *tableP, Int16 row)
-> tableP | Pointer to a table object. (See TableType.) |
-> row | Row number (zero-based). |
Returns true if the row is masked, false otherwise.
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.
Implemented only if 3.5 New Feature Set is present.
TblSetRowMasked, TblSetColumnMasked, TableRowAttrType, SecSelectViewStatus
Return whether the specified row is selectable.
Boolean TblRowSelectable (const TableType *tableP, Int16 row)
-> tableP | Pointer to a table object. (See TableType.) |
-> row | Row number (zero-based). |
Returns true if the row is selectable, false if it's not.
Rows that are not selectable don't highlight when touched.
Determine whether the specified row is usable.
Boolean TblRowUsable (const TableType *tableP, Int16 row)
-> tableP | Pointer to a table object. (See TableType.) |
-> row | Row number (zero-based). |
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.
Rows that are not usable do not display.
TblRowSelectable, TblGetLastUsableRow, TblSetRowUsable
Select (highlight) the specified item. If there is already a selected item, it is unhighlighted.
void TblSelectItem (TableType *tableP, Int16 row, Int16 column)
-> 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). |
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.
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.
TblRowSelectable, TblGetItemBounds, TblGetItemInt
void TblSetBounds (TableType *tableP, const RectangleType *rP)
-> tableP | Pointer to a table object. (See TableType.) |
-> rP | Pointer to a RectangleType structure that specifies the bounds for the table. |
Implemented only if 2.0 New Feature Set is present.
Set the column attribute that controls whether a column highlights when the table is in edit mode.
void TblSetColumnEditIndicator (TableType *tableP, Int16 column, Boolean editIndicator)
-> tableP | Pointer to a table object. (See TableType.) |
-> column | Column number (zero based). |
-> editIndicator | true to highlight, false to turn off highlight. |
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 true, and all other table item types have an edit indicator of false.
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.
Implemented only if 2.0 New Feature Set is present.
Set whether the column is masked.
void TblSetColumnMasked (TableType *tableP, Int16 column, Boolean masked)
-> tableP | Pointer to a table object. (See TableType.) |
-> column | Column number (zero-based). |
-> masked | true to have the column be masked, false otherwise. |
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.
Implemented only if 3.5 New Feature Set if present.
TblRowMasked, TblSetRowMasked, TableColumnAttrType, SecSelectViewStatus
Set the spacing after the specified column.
void TblSetColumnSpacing (TableType *tableP, Int16 column, Coord spacing)
-> tableP | Pointer to a table object. (See TableType.) |
-> column | Column number (zero-based). |
-> spacing | Spacing after the column in pixels. |
This function may display a fatal error message if the column parameter is invalid.
TblSetColumnUsable, TableColumnAttrType
Set a column in a table to usable or unusable.
void TblSetColumnUsable (TableType *tableP, Int16 column, Boolean usable)
-> tableP | Pointer to a table object. (See TableType.) |
-> column | Column number (zero-based). |
-> usable | true for usable or false for not usable. |
This function may display a fatal error message if the column parameter is invalid.
Columns that are not usable do not display.
TblMarkRowInvalid, TableColumnAttrType
Set the width of the specified column.
void TblSetColumnWidth (TableType *tableP, Int16 column, Coord width)
-> tableP | Pointer to a table object. (See TableType.) |
-> column | Column number (zero-based). |
-> width | Width of the column (in pixels). |
This function may display a fatal error message if the column parameter is invalid.
TblGetColumnWidth, TableColumnAttrType
Set the custom draw callback procedure for the specified column.
void TblSetCustomDrawProcedure (TableType *tableP, Int16 column, TableDrawItemFuncPtr drawCallback)
-> tableP | Pointer to a table object. (See TableType.) |
-> column | Column number. |
-> drawCallback | Callback function. |
The custom draw callback function is used to draw table items with a TableItemStyleType of customTableItem. See the TableItemType description for more information.
This function may display a fatal error message if the column parameter is invalid.
TableDrawItemFuncType, TblDrawTable, TableColumnAttrType
Set the font used to display a table item.
void TblSetItemFont (TableType *tableP, Int16 row, Int16 column, FontID fontID)
-> 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. |
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.
Implemented only if 3.0 New Feature Set is present.
Set the integer value of the specified item.
void TblSetItemInt (TableType *tableP, Int16 row, Int16 column, Int16 value)
-> 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). |
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 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.
Set the item to the specified pointer value.
void TblSetItemPtr (TableType *tableP, Int16 row, Int16 column, void *value)
-> 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. |
This function may display a fatal error message if the row or column parameter is invalid.
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.
Set the type of item to display; for example, text, numbers, dates, and so on.
void TblSetItemStyle (TableType *tableP, Int16 row, Int16 column, TableItemStyleType type)
-> 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. |
This function may display a fatal error message if the row or column parameter is invalid.
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); }
Set the load-data callback procedure for the specified column.
void TblSetLoadDataProcedure (TableType *tableP, Int16 column, TableLoadDataFuncPtr loadDataCallback)
-> tableP | Pointer to a table object. (See TableType.) |
-> column | Column number (zero-based). |
-> loadDataCallback | Callback procedure. See TableLoadDataFuncType. |
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.
Set the data value of the specified row. The data value is a placeholder for application-specific values.
void TblSetRowData (TableType *tableP, Int16 row, UInt32 data)
-> 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. |
This function may display a fatal error message if the row parameter is invalid.
Set the height of the specified row.
void TblSetRowHeight (TableType *tableP, Int16 row, Coord height)
-> tableP | Pointer to a table object. (See TableType.) |
-> row | Row number (zero-based). |
-> height | New height in pixels. |
This function may display a fatal error message if the row parameter is invalid.
TblGetRowHeight, TblSetRowStaticHeight
Set the ID value of the specified row.
void TblSetRowID (TableType *tableP, Int16 row, UInt16 id)
-> tableP | Pointer to a table object. (See TableType.) |
-> row | Row number (zero-based). |
-> id | ID to identify a row. |
This function may display a fatal error message if the row parameter is invalid.
TblGetRowID, TblFindRowID, TableRowAttrType
Set a row in a table to masked or unmasked.
void TblSetRowMasked (TableType *tableP, Int16 row, Boolean masked)
-> tableP | Pointer to a table object. (See TableType.) |
-> row | Row number (zero-based). |
-> masked | true to have the row be masked, false otherwise. |
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.
Implemented only if 3.5 New Feature Set is present.
TblRowMasked, TblSetColumnMasked, TableRowAttrType, SecSelectViewStatus
Set a row in a table to selectable or nonselectable.
void TblSetRowSelectable (TableType *tableP, Int16 row, Boolean selectable)
-> tableP | Pointer to a table object. (See TableType.) |
-> row | Row number (zero-based). |
-> selectable | true or false. |
This function may display a fatal error message if the row parameter is invalid.
Rows that are not selectable don't highlight when touched.
TblRowSelectable, TblSetRowUsable, TableRowAttrType
Set the static height attribute of a row.
void TblSetRowStaticHeight (TableType *tableP, Int16 row, Boolean staticHeight)
-> tableP | Pointer to a table object. (See TableType.) |
-> row | Row number (zero-based). |
-> staticHeight | true to set the static height, false to unset it. |
This function may display a fatal error message if the row parameter is invalid.
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.
Implemented only if 2.0 New Feature Set is present.
Set a row in a table to usable or unusable. Rows that are not usable do not display.
void TblSetRowUsable (TableType *tableP, Int16 row, Boolean usable)
-> tableP | Pointer to a table object. (See TableType.) |
-> row | Row number (zero-based). |
-> usable | true or false. |
This function may display a fatal error message if the row parameter is invalid.
TblRowUsable, TblSetRowSelectable
Set the save-data callback procedure for the specified column.
void TblSetSaveDataProcedure (TableType *tableP, Int16 column, TableSaveDataFuncPtr saveDataCallback)
-> tableP | Pointer to a table object. (See TableType.) |
-> column | Column number (zero-based). |
-> saveDataCallback | Callback function. See TableSaveDataFuncType. |
This function may display a fatal error message if the column parameter is invalid.
The callback procedure is called when the table object determines the data of a text object needs to be saved.
void TblSetSelection (TableType *tableP, Int16 row, Int16 column)
-> tableP | Pointer to a TableType. |
-> row | Table row. |
-> column | Table column. |
Returns nothing. |
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.
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 76, "PalmOSGlue Library."
TblGetNumberOfColumns, TblGetTopRow
Unhighlight the currently selected item in a table.
void TblUnhighlightSelection (TableType *tableP)
-> tableP | Pointer to a table object. (See TableType.) |
void TableDrawItemFuncType (void *tableP, Int16 row, Int16 column, RectangleType *bounds)
-> 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. |
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.
TblSetCustomDrawProcedure, TableItemType
Err TableLoadDataFuncType (void *tableP, Int16 row, Int16 column, Boolean editable, MemHandle *dataH, Int16 *dataOffset, Int16 *dataSize, FieldPtr fld)
-> 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 0 upon success or an error if unsuccessful.
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.
TblDrawTable, TblHandleEvent, TableLoadDataFuncType
Save the data associated with a text field.
Boolean TableSaveDataFuncType (void *tableP, Int16 row, Int16 column);
-> 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. |
Return true if the table should be redrawn, or false if the table does not need to be redrawn.
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.
|