Alert readers may have noted that while there is a fair amount of documentation on how ePalm interfaces with PalmOS, there is precious little documentation on how PalmOS programming works, what each and every class does, and what features do what.
The reason is that PalmOS programming, like programming for any platform, has a great body of knowledge associated with it--what an event is, what a form is, how data is accessed, etc. And since the PalmOS platform is so remarkably popular, there is a great deal of documentation out there on it. When running a single-person project like ePalm, I am forced to make a decision: work on extending the project's functionality or work on extending the project's documentation. In many cases, documentation is actually more important than adding functionality, and I recognize this.
Yet at the same time, the object-oriented community is focused on reuse of concepts and ideas, and I see no reason why the ePalm project should not capitalize on the existing documentation available for PalmOS.
The best introduction to PalmOS programming that I've found is slightly out of date but still incredibly useful. That book is Palm Programming: The Developer's Guide, by Neil Rhodes and Julie McKeehan, published by O'Reilly and Associates. It presents a good broad overview of PalmOS concepts and steps the user through design and implementation of several simple programs to get the idea across. It would be fruitless and presumptuous for me to duplicate the information available in that book, so I refer the reader to it for an introduction to PalmOS concepts.
Of course, it would be even more presumptuous of me to require users to purchase a book just to use ePalm. Unfortunately, I can no longer find online the full text of this book (it was once hosted on the www.palm.com site), so can only recommend it in paperback; it is now in its second edition.
As any provider of technology would, Palm itself provides a vast amount of information at http://www.palmos.com/dev/support/docs/. In particular, the "Palm OS Programmer's Companion and Reference" (available at http://www.palmos.com/dev/support/docs/palmos) is a wonderful reference. The Companion volume gives overviews of all common concepts, from forms to bitmaps to databases and beyond. The Reference provides a feature-by-feature introduction to every call used in PalmOS C programming.
While ePalm classes do not use the same names for features, the mapping between an ePalm class feature and a PalmOS C function is fairly intuitive.
For example, you are working on a form and want that form to hide
one of its tenant objects. The PalmOS function to do this would
be FrmHideObject
. You are working on a form, which is
represented in ePalm by the FORM class--and sure enough, it has a
feature hide_object
. It's easy to look at the PalmOS Reference
description of FrmHideObject
and infer what to do with the ePalm
feature FORM.hide_object
.
However, this can get tricky, because the PalmOS API organizes
things along topic lines rather than class lines. If there isn't
an obvious class feature that should map from a function, look for
a class ending in _MANAGER
and then one (for your application)
ending in _MANAGER_CLIENT
, which usually implements a singleton
instance of the _MANAGER
class.
For example, suppose you are working on an
application and want to open up an alert dialog. A quick look
through the PalmOS documentation lets you know that the feature
you want is FrmAlert
. The Frm
at the beginning of the name
lets you know that it's a form function. Coincidentally, ePalm
has a FORM
class. Unfortunately, it has no alert
feature... but that's because FORM
encapsulates the idea of a
form, while FrmAlert
generates a form. Looking at similar class
names in ePalm, we come across FORM_MANAGER
, which does have
an alert
feature. We also see FORM_MANAGER_CLIENT
, which
defines a once
instance of 'FORM_MANAGER'--so the answer is to
have our current class inherit from FORM_MANAGER_CLIENT
and then
call the form_manager.alert
feature.
So the short form: Use existing PalmOS documentation to guide you on how to use ePalm classes. Since that is still quite vague, the next five chapters of documentation will step the user through the sample applications included with ePalm.