Palm OS Tables

1
Palm OS Tables

• Karen Jeffrey
• Forall Systems, Inc. and DePaul University
• kjeffrey_at_forallsystems.com

2
Introduction to Tables

• What are they good for?
• Displaying columnar data (maybe)
• Displaying data from a database (maybe)
• Edit-in-place of text fields
• Provides some useful predefined types
• Eliminating list box

3
What is Edit-in-Place

• Allows programmer to associate a text field with
  a location in memory
• Uses FldSetText with parameters
• fldPtr, recH, offset, strlen
• Useful for large text fields such as notes
• Automatically resizes string and record
• Can only be used on one field at a time

4
When possible, use Lists

• Are easier to program
• Can dynamically generate list elements from
  database(see LstSetDrawFunction)
• Can display multiple columns
• Can automatically handle scrolling

5
Another alternative

• Implement your own version of tables
• The source code for the implementation of tables
  is available from Palm OS (this is useful to
  look at even if only to understand how tables
  work)
• I have gotten around to doing this myself

6
What is a Table?

• Basically a container for several kinds of
  simpler form elements
• Data is associated with cell
• Event handling is processed based on the assigned
  type of the cell

7
Cell Type Overview
8
Cell Type Overview
9
Programming with Tables

• Initialization
• Specify callback functions (for text fields)
• Loading
• Saving
• Displaying
• Handle table events

10
Table Initialization

• Explicitly set each cell type with
  TblSetItemStyle
• Set initial data values of cells
• Make columns visible with TblSetColumnUsable
• For text and custom cell types, specify custom
  load and save procedures with TblSetLoadDataProced
  ure and TblSetSaveDataProcedure

11
Creating a Custom Item

• Create a custom item if your data doesnt work
  with the built-in cell types
• Specify a custom draw procedure using
  TblSetCustomDrawProcedure
• Use TblSetItemInt and TblSetItemPtr to store your
  custom data

12
Loading and Saving Data

• For use with text fields
• Save procedure is called when
• User clicks on the fields icon
• User moves to another field
• Table loses focus (TblReleaseFocus)
• Your load procedure is called when
• Table gets focus (TblGrabFocus)
• Table is redrawn (TblDrawTable, TblRedrawTable)
• Field cell is entered (tblEnterEvent)

13
Scrolling a Table

• NumRows is of visible rows, not number of items
  in the list
• Invalidate the rows that will change using
  TblMarkRowInvalid
• Redraw the table using TblRedrawTable
• Redraw will force any custom draw or load
  procedures to be called
• Might use TblSetRowID

14
Some Gotchas

• The text cell types do not interact well with the
  other types in the same column, since the load
  and save callback functions are column
• The table manager will resize rows in multi-line
  text cells, but the resizing isnt always
  automatic when the text shrinks.
• Autoshift has to be specified in your code

15
Hints

• Use a list instead
• If possible, avoid multi-line resizable text
  fields
• Take a look at the sample code
• Read the section on tables in the Palm OS
  Programming Bible

16
References

• Palm OS Programming Bible, by Lonnon R.
  FosterAn excellent, in depth presentation
• Palm OS Source Code, available for free from Palm
  OS with license agreement. Also available from
  Knowledgebase