Moving Resources Between the Mac and PC
EC is a Euro calculator I built for the Palm Computing platform. The development environment I used was the C-based Metrowerks CodeWarrior, Release 5 (CWR5) on both the Macintosh and PC. The Mac was a 266-MHz PowerBook G3 running OS 8.5, while the PC was a 133-MHz Pentium running Windows NT 4.0, service pack 3. Although the PC sounds underpowered by today's standards, the toolset still performed well. The only sign of strain came from the Palm OS Emulator (POSE), which I used for testing and debugging (see Figure 1). In that case, a 200-plus MHz machine would have been more appropriate. The complete source code and related files for EC are available electronically; see "Resource Center," page 5.
The three major components of CWR5 are the integrated development environment and debugger (IDE), a user-interface and bitmap editor (the Constructor), and the POSE emulator. CWR5 runs almost identically on both the Mac and PC. This was nice because, when switching back and forth between the machines, I had a uniform experience. For PC developers, however, the UI model can take some getting used to because it generally follows Mac standards. For example, to get an application's focus and pull down its menu, the Mac requires two mouse clicks, whereas the PC normally needs one. CWR5 requires two mouse clicks, regardless of the platform. In the future, Metrowerks will produce two distinct versions of CodeWarrior to better take advantage of each platform's relative strengths.
Like most IDEs, CWR5 has project files, an editor that can edit multiple source files with syntax color coding, a built-in "make" facility, and plug-ins for Visual SourceSafe version control. It compiles and links C and C++ code into a PRC binary file. This file is your application, which you normally download to your device using the Palm install tool. You can debug your application directly on the device, or load it into POSE and debug from there. Debugging directly on the device requires that you seat the handheld into its cradle and put it in debug mode with the graffiti sequence "shortcut ..2." There are several other hidden shortcuts that help with debugging; see Table 1. Shortcuts are useful if you must test on the actual hardware; for example, if your application uses the infrared port. The drawback is that you drain the handheld's battery much more rapidly. Also, if your code locks up the Palm device, you need to insert a paperclip into the back of the unit to reset it -- a process that can grow tedious.
Most of the time, I debug using POSE. It requires none of the aforementioned steps and CWR5 IDE debugger integrates seamlessly with it. POSE has other advantages as well. To registered developers, Palm makes available the ROMs for its family of handheld devices. This means you don't need to own the Palm Personal/Pro, Palm III, Palm IIIx, Palm V, and Palm VII devices just to see if your application works on them. Instead, you load the desired ROM into POSE and test it. Also available are the European ROMs and the Japanese ROM.
One indispensable part of POSE is a tool called "gremlins." Appropriately named, gremlins is a process that generates random events in an attempt to stress and crash your application. It's good programming practice to verify that your application survives 1 million gremlin steps; indeed, this is one of the many requirements for Palm Platinum Certification. The gremlins tool was able to identify several bugs for me, usually when I trampled uninitialized memory. Still, this kind of automated testing is no substitute for intelligent testing. The gremlins process does not know if the results of the Euro conversion are correct, nor does it care that users should be able to enter only one decimal point.
Running 1 million gremlin steps against EC on the 133-MHz Pentium PC took over 24 hours. The 266-MHz Mac required seven hours. Thus, another advantage of having two systems became clear; I could run gremlins on the Mac while continuing to develop on the PC. Even with two systems, it wasn't practical to frequently run 1 million gremlin steps. Instead, at major milestones during development, I would run 100,000 gremlin steps, deferring the 1 million step test until EC made it to beta.
EC Anatomy
The Constructor lets you layout the appearance of the calculator using drag-and-drop (see Figure 2). Basically, you create a form and populate it with various objects. EC has several objects, including buttons, fields, lists, popup triggers, and menus. The buttons are used for input and the two fields are for output -- one field for the selected country's currency, and the other for the equivalent in Euro currency. The list object stores the list of participating European countries (see Table 2) and the popup trigger is used to popup that list. Unlike a Windows combo-listbox, a Palm OS listbox and trigger are separate controls. I use the menu to display the full name of the currencies because not every EC user will recognize, for example, that "ATS" refers to "Austrian schillings." Within this group of 11 countries, the conversion rates do not fluctuate.
The Constructor on the Mac has a more capable bitmap editor than the PC version. Specifically, the Mac version allowed text entry, whereas the PC version didn't. This was important when creating the Euro symbol, which looks like a letter C with an equal sign through it. One unfortunate downside of working on both platforms was that moving the resources between them wasn't seamless (see the accompanying text box entitled "Moving Resources Between the Mac and PC").
You also use the Constructor to name the application and create the application icon. You might find it useful to prefix the application name with an underscore during development. Hence, "EC" was temporarily named "_EC." When downloaded to the handheld or POSE, it appeared as the first application icon, which made it easier to find and launch for debugging.
Palm OS 3.0 supports normal and small icons. On the launch screen, applications can be displayed using icon (normal) mode or list (small) mode. The normal icon can be no larger than 22×22 pixels and must use resource ID 1000. The small icon is multibit (4-level grayscale), can be no larger than 9×15 pixels, and must use resource ID 1001.
Palm OS applications are event driven and each form has an event handler to manage its objects. EC has only one form and about a dozen objects, so its event loop in ECFormHandleEvent() isn't particularly complex (refer to the file ec.c, available electronically; see "Resource Center," page 5). Your application is responsible for handling at least two events: frmOpenEvent and frmCloseEvent. The event frmOpenEvent is a request to initialize and draw the form. Here, EC allocates memory, draws the form, and sets the focus to a default currency field. The event frmCloseEvent gets invoked when users go to another form within the application or leave the application entirely. During frmCloseEvent, EC frees its allocated memory and, by setting handled=false, passes control to the Palm OS, where it does its own cleaning up.
The fldEnterEvent event is sent whenever a pen tap occurs within a field's boundaries. I used this to determine which of the two currency fields had focus: If users tap the Euro field, then I know to convert to the selected country's currency. Similarly, if users tapped the country's currency field, I know to convert to the Euro currency. Trapping fldEnterEvent also let me do some validation on the number. For example, if the number in the field already has a decimal point, I prevent users from entering another one.
Palm OS applications also require some housekeeping. One task is to always verify the ROM version to see if it meets your application's requirements. EC requires a minimum of Palm OS 2.0. If that is not the case, EC informs users, then quits. Palm Computing has provided a snippet of code to perform this check: RomVersionCompatible(); see ec.c (available electronically).
Other tasks include starting the application where the user left off and saving the state of the application when the user leaves it. The Palm OS supports a preference database where you can load and save the state of your application. You define the type of data to save in a structure. For example, in ECPreferenceType EC stores, items such as the active currency, the contents of the display fields, the field that has the focus, and any pending mathematical operation. When users return to EC, this information is reloaded, creating the illusion that the application never quit. These actions are performed in AppStart() and AppStop(), respectively.
When saving preferences, PrefSetAppPreferences() takes as its last argument a Boolean flag called save. A True setting transfers the preference record to your desktop during the hotsync process, whereas a False setting does not. Thus, the former lets your preference data survive a cold reset, while the latter lets your preference data survive only a warm reset. The tradeoff is the time it takes for a hotsync process to complete. Well-behaved applications should not add to the duration of the hotsync process unnecessarily. Thus, if the preference data isn't critical, such as high scores in a game or EC's data, set the flag to False. If EC used memory registers or let users store custom exchange rates, I would deem that data critical and would set the flag to True. Whatever the setting of this flag, be sure you use the same setting when retrieving your preferences with PrefGetAppPreferences().
Finally, Palm OS applications must set a creator ID. Mac developers are already familiar with this concept. For PC developers, a creator ID is a 4-byte value unique to each application and is used to identify databases related to the application. In a small way, it serves a similar purpose as the PC's registry. Creator IDs must be all caps or mixed case; all lowercase IDs are reserved by the Palm OS. In EC's case, I've used "YEC1" for Y Technology (my company) EuroCalculator 1. If I were to write Version 2.0 of EC, I would use the same creator ID YEC1. If, for some unusual reason, I wanted both versions of EC to coexist on the same Palm device, I would need to assign a new creator ID for EC Version 2.0.
To maintain uniqueness across all created applications, you must register your ID with Palm Computing at http://www .palm.com/devzone/crid/cridsub.html. It's a quick process. While the combinations of letters and numbers make for a virtually limitless supply of creator IDs, I still don't like to pollute the namespace. Register when you are reasonably sure your application will be released; my rule of thumb is anytime after design but before alpha.
If all this housekeeping sounds tedious, it's because it is. Fortunately for PC users (Mac users are out of luck), CWR5 comes with an unsupported tool to help -- easysrc.exe (see Figure 3). This program takes the header file (ec_res.h) created by the Constructor and generates the skeletal C source code, which includes event handlers, a ROM version check, and a creator ID set to APPL. To help you remember to change the creator ID and do other similar chores, easysrc leaves handy reminders in the source code; just search on TODO. Lastly, easysrc generates code in one of two styles: Palm OS or Hungarian Notation.
Floating Point
Floating-point support has improved since Palm OS 1.0, but it is still weak. Palm OS documentation is obsolete in this area and you should refer to the header file NewFloatMgr.h for more current information. To use floating point for Palm OS 2.0 and greater, you must include NewFloatMgr.h in your source and configure the CWR5 IDE program settings: Code Generation|68K Processor|Floating Point should be set to Palm OS, and the option 8-Byte Doubles should be enabled (see Figure 4).
Palm OS 2.0 and up supports float and double as well as its own defined types FlpFloat and FlpDouble, which are 32- and 64-bits long, respectively. With floats and doubles, you use the standard mathematical symbols (+ - · / ) to operate on them, but you run into difficulties if you need to convert the values to ASCII. The popular idiom sprintf (buffer, ''%lf'', pi); will not work because under Palm OS, sprintf() is replaced with a version named StrPrintF() that doesn't support floating-point conversions. This is just one of many trade-offs programming for a small memory footprint demands.
With FlpFloat and FlpDouble, you cannot use standard mathematical symbols to operate on them; rather, you need to call routines to do arithmetic. For example, you would use _d_add() to add two FlpDoubles. There are, however, routines to convert these types between ASCII and floating point: FlpFToA() and FlpAToF(). Unfortunately, the ASCII result is always in exponential format ([-]x.yyyyyyyye[-]zz), which isn't very friendly. Thus, routines to round the value and to format the display were sorely missed.
FlpBase10Info() is an important function that extracts three components from the floating-point type into ASCII format: the base 10 mantissa, the exponent, and the sign. Given this information, I was able to format the value in more familiar terms. For the most part, I succeeded in removing the exponent and relocating the decimal, except where the numbers were very small or very large.
Another area where I compromised was I only supported two operands and one operator. This means EC calculates x+y=z but not a+b·c=d. A more robust calculator would use stacked-based algorithms that would also allow operations with parentheses. If you need sophisticated floating-point support -- trigonometric functions, logarithms, floor and ceiling routines, and the like -- you should look into mathlib. It comes with CWR5, but is not supported by Metrowerks or Palm Computing. Ported to the Palm OS by Rick Huebner, it's available under the GNU Library General Public License.
Localization
When it comes to number formats, the United States uses a period to indicate a decimal separator and comma to denote a thousands separator. Parts of Europe employ this same convention, while other parts employ the reverse. Switzerland uses a third convention where an apostrophe signifies a thousands separator. Fortunately, developers don't need to know these details because the Palm OS provides LocGetNumberSeparators(), a routine that identifies the proper characters used for decimal and thousands separators. What gets returned depends on the country setting in your Palm handheld.
I call LocGetNumberSeparators() in AppStart() and store the characters in global variables. The function ECFormatResult() uses this information to format the currency with the correct decimal separator (EC doesn't use the thousands separator yet). EC's keypad must also provide the correct decimal button -- period or comma -- and I dynamically update the button's label in the function ECFormHandleEvent(). Specifically, I used the Palm OS function CtlSetLabel() during frmOpenEvent. CtlSetLabel() is called before FrmDrawForm() to prevent the control from visually redrawing.
To help with number formats, the Palm OS provides the StrLocalizeNumber() and StrDelocalizeNumber() functions. Unfortunately, these routines are broken for both Palm OS 2.0 and 3.0, and I recommend writing your own versions -- which is a relatively simple task. StrLocalizeNumber() is supposed to format a number to a specific locale, whereas StrDelocalizeNumber() is supposed to format a number specifically for the United States. The conversions do not always work, but Palm Computing is aware of this problem.
Localization means more than just displaying the correct formats for numbers and dates. EC's menus, dialogs, and buttons are still in English. If I were to make a Dutch edition of EC, I would have to isolate the strings in a separate resource file. Were I to make a Japanese edition of EC, I would also have to be concerned with wide characters. These issues are beyond the scope of this article, but Palm OS 3.0 does provide an international manager API to help with these matters.
Conclusion
EC involved only a few aspects of programming for the Palm platform. It is a simple, but useful application, and requires a modest 9K of memory. Still, there are advanced topics such as database and memory management, and the synchronization of data between the device and the desktop that you can explore at Palm Computing's developer zone (http://www .palm.com/devzone/). Finally, I'd like to thank Roger Flores for his comments and corrections to this article.
DDJ
