Skeletal Documentation

Skeletal Documentation

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.

First Steps: _Palm Programming: The Developer's Guide_

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.

Online: The palm website

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.

Powered by Zope