2 Good Design Practices

This chapter helps you design an application that's fast, robust, and consistent with other applications on the device. The previous chapter described at a very high level the sorts of issues involved with writing a Palm OS^® application. This chapter goes into much more detail about what is appropriate application design and user interface design. Its focus is how to:

• Avoid potential problems
  
  
• Make your application integrate well with others
  
  
• Achieve the best performance possible
  
  
• Localize with the minimum amount of work
  
  
• Maintain backward compatibility
  

The information was collected from engineers, testers, and other experts who designed, developed, and tested the four applications shipped with the first Palm OS device.

Paying attention to user interface guidelines and, if applicable, to localization guidelines early in your development cycle will save you time and trouble later. However, there's a lot to digest here. You may want to revisit this chapter from time to time to make sure you haven't forgotten anything.

This chapter discusses these topics:

• Designing Your Application
  
  
• User Interface Guidelines
  
  
• Localization Guidelines
  
  
• Making Your Application Run on Different Devices
  

  ---

  NOTE:  

  Be sure to read the "Avoiding Potential Pitfalls" and "Writing Robust Code" sections for information on the problems developers encounter most frequently.

  ---

  
  

Designing Your Application

This section provides Palm OS application design guidelines. It discusses these topics:

• Integrating Programs With the Palm OS Environment
  
  
• Naming Conventions
  
  
• Achieving Optimum Performance
  
  
• Assigning a Creator ID
  
  
• Working With Databases
  
  
• Writing Robust Code
  
  
• Avoiding Potential Pitfalls
  

Integrating Programs With the Palm OS Environment

When users work with a Palm OS application, they expect to be able to switch to other applications, have access to Graffiti^® and the on-screen keyboard, access information with the global find, receive alarms, and so on. Your application will integrate well with others if you follow the guidelines in this section. Integrate with the system software as follows:

• Handle sysAppLaunchCmdNormalLaunch
  
  
• Handle or ignore other application launch codes as appropriate. For more information, see the next chapter, Chapter 3, "Application Startup and Stop."
  
  
• Handle system preferences properly. System preferences determine the display of
  
  • Date formats
  • Time formats
  • Number formats
  • First day of week (Sunday or Monday)

    Be sure your application uses the system preferences for numeric formats, date, time, and start day of week.

  
  
• Allow the system to post these messages:
  
  • alarms
  • low-battery warnings
  • system messages during synchronization
  
  
• Be sure your application does not obscure or change the Graffiti area, silk-screened buttons, and power button.
  
  
• Don't obscure Graffiti shift indicators.
  

In addition, follow these rules:

• Store state information in the application preferences database, not in the application record database. Call PrefGetAppPreferences and PrefSetAppPreferences to save and restore preferences. This is important if your application returns to the last displayed view by default.
  
  
• If your application uses the serial port, be sure to free the port when you no longer need it so that the HotSync^® application can use it.
  
  
• Ensure that your application properly handles the global find. Generally, searches and sorts aren't case sensitive.
  
  
• If your application supports private records, be sure they are unavailable to the global find when they should be hidden.
  
  
• The application name is defined in two ways:
  

  The application name (required) is specified in the PalmRez panel of your CodeWarrior project and used by HotSync, the About box, the Memory display, and the database header.

  • The application icon name (optional) is a string resource in the application's resource file. It is used by the launcher screen and in the Button Assignment preferences panel (available in OS versions 2.0 and later). You assign the name using the Constructor Project Settings panel.

    Using the icon name is useful if you plan to localize your application.

    Note: If you use an application icon name, make it short!

  
  
• Together with the application name, each application displays a application icon in the launcher.
  

  Your application should have two icons: one for the main view of the launcher and a smaller version for the list view. The first icon should be 22 x 22 pixels. It should be numbered 1000 and have the type tAIN. The smaller icon should be 15 x 9 pixels, should be numbered 1001 and have the type tAIB.

  
  
• Follow the guidelines listed in User Interface Guidelines and pay special attention to these points:
  
  • Ensure that the different user input modes (e.g., Graffiti and keyboard) are available for each field.
  • Ensure that menu items work with shortcuts as advertised.
  • Put limits on the length of fields and test them.
  • Ensure that any growable control, such as the launcher window or the menus, scrolls correctly.
  
  
• Ensure that your application properly handles system messages during and after synchronization.
  
  
• Ensure that deleted records are not displayed.
  
  
• Ensure that your application doesn't exceed the maximum number of categories: 15 categories and the obligatory category "Unfiled" for a total of 16.
  
  
• Ensure that your application uses a consistent default state when the user enters it:
  
  • Some applications have a fixed default; for example, the Date Book always displays the current day when launched.
  • Other applications return to the place the user exited last. In that case, remember to provide a default if that place is no longer available. Because of HotSync and Preferences, don't assume the application data is the same as it was when the user looked at it last.
  
  
• If your application uses sounds, be sure it uses the Warning and Confirmation sounds properly.
  

Naming Conventions

The following conventions are used throughout the Palm OS API:

• Functions start with a capital letter.
  
  
• All functions belonging to a particular manager start with a two- or three-letter prefix, such as "Ctl" for control functions or "Ftr" for functions that are part of the feature manager.
  
  
• Events and other constants start with a lowercase letter.
  
  
• Structure elements start with a lowercase letter.
  
  
• Global variables start with a capital letter.
  
  
• Typedefs start with a capital letter and end with "Type" (for example, DateFormatType, found in DateTime.h).
  
  
• Macintosh ResEdit resource types usually start with a lowercase letter followed by three capital letters, for example tSTR or tTBL. (Customized Macintosh resources provided with your developer package are all uppercase, for example, MENU. Some resources, such as Talt, don't follow the conventions.)
  
  
• Members of an enumerated type start with a lowercase prefix followed by a name starting with a capital letter, as follows:
  

enum formObjects {

    frmFieldObj,
    frmControlObj,
    frmListObj,
    frmTableObj,
    frmBitmapObj,
    frmLineObj,
    frmFrameObj,
    frmRectangleObj,
    frmLabelObj,
    frmTitleObj,
    frmPopupObj,
    frmGraffitiStateObj,
    frmGadgetObj};
    typedef enum formObjects FormObjectKind;

Achieving Optimum Performance

Because the Palm OS device has limited heap space and storage, optimization is critical. The Palm OS device currently has no wait cursor, so users will expect rapid response. Test for performance. Launching, switching, and finding should be fast.

To make your application as fast and efficient as possible, optimize for heap space first, speed second, code size third.

Follow these guidelines to optimize memory use:

• Allocate handles for your memory to avoid heap fragmentation.
  
  
• Sort on demand; don't keep different sort lists around. This makes your program simpler and requires less storage.
  
  
• Dynamic memory is a potential bottleneck. Don't put large structures on the stack.
  
  
• Arrange subroutines within the application to avoid 32K jumps.
  
  
• To have your application run well within the constraints of the limited dynamic heap, follow these guidelines:
  
  • Allocate memory chunks instead of using global variables where possible.
  • Switch from one UI form to another instead of stacking up dialog boxes.
  • Edit database records in place; don't make extra copies on the dynamic heap.
  
  
• Avoid placing large amounts of data on the stack. Heap corruption is hard to debug. Global variables are preferable to local variables (however, chunks are preferable to global variables). Your application only has from 2K or 4K of stack space depending on the system software version.
  

Assigning a Creator ID

Each Palm OS application has a distinct creator ID. A creator ID is a 4-byte value used to tie together all the databases related to the application.

Creator IDs are unique to the application, not the creator of the application. Each database on the Palm device has an application value and a type. The type value should be set to sysFileTApplication for the executable's database and can be set to any value for other databases associated with an application.

Creator IDs need to be either all caps or mixed case. The Palm OS creator IDs differ from the creator ID and type that appear in the CodeWarrior Project Settings dialog boxes.

The creator ID for a Palm OS application is assigned in the PalmRez Project Settings panel.

• The Type should be set to APPL. Type is a 4-byte value.
  
  
• For information about creator IDs, and to register a creator ID, see this web page:
  

http://www.palmos.com/dev/crid/cridsub.html

The system uses the creator ID in various ways:

• Creator ID and type is used by the system launcher window to determine which databases are applications that should be displayed for selection.
  
  
• The memory application uses a creator ID and type to determine names of applications for display and to calculate total memory used by an application.
  

Working With Databases

Working properly with databases makes your application run faster and synchronize without problems. Follow these suggestions:

• When the user deletes a record, call DmDeleteRecord to remove all data from the record, not DmRemoveRecord to remove the record itself. That way, the desktop application can retrieve the information that the record is deleted the next time there is a HotSync.
  

  Note: If your application doesn't have an associated conduit, call DmRemoveRecord to completely remove the record.

  
  
• Keep data in database records compact. To avoid performance problems, Palm OS databases are not compressed, but all data are tightly packed. This pays off for storage and during HotSync.
  
  
• All records in a database should be of the same type and format. This is not a requirement, but is highly recommended to avoid processing overhead.
  
  
• Be sure your application modifies the flags in the database header appropriately when the user deletes or otherwise modifies information. This flag modification is only required if you're synchronizing with the Palm PIM applications.
  
  
• Don't display deleted records.
  
  
• Call DmSetDatabaseInfo when creating a database to assign a version number to your application. Databases default to version 0 if the version isn't explicitly set.
  
  
• Call DmDatabaseInfo to check the database version at application start-up.
  

Writing Robust Code

To make your programs more robust and to increase their compatibility with the next generation of Palm Computing products, it is strongly recommended that you follow the guidelines and practices outlined in this section.

• Check assumptions
  

  You can write defensive code by adding frequent calls to the ErrNonFatalDisplayIf function, which enables your debug builds to check assumptions. Many bugs are caught in this way, and these "extra" calls don't weigh down your shipping application. You can keep more important checks in the release builds by using the ErrFatalDisplayIf function.

  
  
• Avoid continual polling
  

  To conserve the battery, avoid continual polling. If your application is in a wait loop, poll at short intervals (for example, every tenth of a second) instead. The event loop of the Hardball example application included with your Palm OS SDK illustrates how to do this.

  
  
• Avoid reading and writing to NULL (or low memory)
  

  When calling functions that allocate memory (MemSet, MemMove and similar functions) make sure that the pointers they return are non-NULL. (If you can do better validation than that, so much the better.) Also check that pointers your code obtains from structures or other function calls are not NULL. Consider adding to your debug build a #define that overrides MemMove (and similar functions) with a version that validates the arguments passed to it.

  
  
• Use dynamic heap space frugally
  

  It is important not to use the extra dynamic heap space available on Palm units running 2.0 and higher unless it is truly necessary to do so. Wasteful use of heap space may limit your application to running only on the latest devices--which prevents it from running on the very large number of units already in the marketplace.

  Note that some system services, such as the IrDA stack or the Find window, can require additional memory while your application is running; for example, if the unit starts to receive a beam or other external input, the system may need to allocate additional heap space for the incoming data. Don't use all available dynamic memory just because it's there; instead, consider using the storage heap for working with large amounts of temporary data.

  
  
• Check result codes when allocating memory
  

  Because future devices may have larger or smaller amounts of available memory, it is always a good idea to check result codes carefully when allocating memory. It's also good practice to use the storage heap (and possibly file streams) to work with large objects.

  
  
• Avoid allocating zero-length objects
  

  It's not valid to allocate a zero-byte buffer, or to resize a buffer to zero bytes. Palm OS 2.0 and previous releases allowed this practice, but future revisions of the OS may not permit zero-length objects.

  
  
• Avoid making assumptions about the screen
  

  The location of the screen buffer, its size, and the number of pixels per bit aren't set in stone--they might well change. Don't hack around the windowing and drawing functions. If you are going to hack the hardware to circumvent the APIs, save the state and return the system to that saved state when you quit.

  
  
• Don't access globals or hardware directly
  

  Global variables and their locations can change; to avoid mishaps, use the documented API functions and disable your application if it is run on anything but a tested version of the OS. Future devices might run on a different processor than the current one.

  Similarly, don't hardcode references to cards. Although current Palm OS hardware provides only a single card slot, this may not always be the case. Thus, when calling functions that manipulate cards, such as database manager and file streaming functions, pass a variable that references the target card, rather than passing a hardcoded reference to card 0.

  
  
• Built-in applications can change
  

  The format and size of the preferences (and data) for the built-in applications is subject to change. Write your code defensively, and consider disabling your application if it is run on an untested version of the OS.

Avoiding Potential Pitfalls

Certain problems are encountered by application developers again and again. To avoid them, ask yourself these questions:

• Do you have a Creator ID for your application?
  

  Each application (not just each company) has to have a Creator ID. Note that the Creator ID is only needed for the application (database of type APPL) not for all other databases.

  
  
• Did you use C library calls in your application? If you did, change them to corresponding Palm OS calls.
  

User Interface Guidelines

The Palm OS device is designed for rapid entry and quick retrieval of information. To maximize performance, the UI should minimize navigation between windows, opening of dialog boxes, and so on. The layout of application screens needs to be simple so that the user can pick up the product and use it effectively after a short time. It's especially helpful if the UI of your application is consistent with other applications on the device so users work with familiar patterns.

This section helps you design a user interface that's intuitive, easy to use, and consistent with other applications on the device. You learn about these issues:

• Understanding the Palm OS UI Design Philosophy
  
  
• Creating a Palm OS User Interface
  
  
• Palm OS Resource Selection: List or Table?
  

  ---

  NOTE:  

  Guidelines for implementing specific user-interface objects, such as information on the size of buttons or the font for labels, is provided in "Palm OS Resources" in the Palm OS SDK Reference. Also see the chapter "User Interface" in this book.

  ---

  
  

Understanding the Palm OS UI Design Philosophy

This section considers some issues that underlie the design of a user interface for the Palm OS device. It discusses these topics:

• Creating Fast Applications
  
  
• Matching Use Frequency and Accessibility
  
  
• Creating Easy-to-Use Applications
  

Creating Fast Applications

On a PC, users don't mind waiting a few seconds while an application loads because they plan to use the application for a certain amount of time.

The Palm OS paradigm, in contrast, resembles that of a watch: People want instant access to information. Speed is therefore a critical design objective for hand-held organizers and is not limited to execution speed of the code. The total time needed to navigate, select, and execute commands can have a big impact on overall efficiency.

The user should be able to keep up with someone on the telephone when setting up appointments, looking up phone numbers, and so on. Priorities include the ability to:

• Execute key commands quickly
  
  
• Navigate to key screens quickly
  
  
• Find key data quickly (for example, phone numbers)
  

Matching Use Frequency and Accessibility

PC user interfaces are typically designed to display commands as if they were used equally. In reality, some commands are used very frequently while most are used only rarely. Similarly, some settings are more likely to be used than others. For example, a 3 p.m.- 4 p.m. meeting occurs much more frequently than a 3:25 to 4:15 meeting.

More frequently used commands and settings should be easier to find and faster to execute.

• Frequently executed software commands should be accessible by one tap.
  
  
• Infrequently used commands may require more user action.
  

  Frequency	Example	Accessibility
  Several times per hour.	Checking today's schedule or to-do items.	One tap.
  Several times per day.	One hour meeting starting at the top of the hour.	One tap, write in place.
  Several times per week.	Setting a weekly meeting (repeating event).	Several taps, second dialog box.

To make your application easily accessible, follow these guidelines:

• Minimize the number of taps to execute a function or change a setting.
  
  
• Provide command buttons for commonly executed multistep operations. Command buttons streamline execution.
  
  
• Minimize the need to change screens.
  
  
• Minimize the number of dialogs users have to open and close.
  
  
• Avoid dialogs within dialogs unless it's an infrequently used feature.
  

Choose the appropriate UI object when making a speed versus screen layout decision:

• Buttons on the screen provide instant access but take up valuable screen space.
  
  
• Push buttons are faster than popup lists and should be used if they fit on the screen reasonably.
  
  
• Popup lists are faster than manual input or increment/decrement buttons
  
  
• Popup lists can be cumbersome if there are too many items on the list or if the list needs to scroll.
  

Creating Easy-to-Use Applications

Users must be able to pick up a Palm device and, with no training or instruction, navigate between applications (without getting stuck) and execute basic commands within five minutes. Advanced commands should be easily accessible but should not be in the way.

The design must therefore fit the following criteria:

• Indicate clearly where in an application the user is. The PIM applications and modal dialog boxes have black title bars that usually indicate the application name and view.
  
  
• Make it obvious to the user how to get to different views. The command buttons provide the best example of achieving this.
  
  
• Use buttons for important commands.
  
  
• Accomplishing common tasks should be fast and easy. Minimizing steps helps not only speed but ease of use.
  

Ease of use amounts to a series of trade-offs. Striking the best balance for the most people is the biggest challenge of UI design. For example:

• Consistency reduces the time needed to learn an application by limiting the number of things that people need to keep in their heads at once. The user should not have to memorize an entire set of rules to use the device easily, for example, the up arrow key should not do different things on different screens.
  
  
• Choose the number of buttons on the screen diligently:
  
  • The fewer buttons on the screen, the less time it takes to learn how to use the product.
  • However, keeping a few frequently used buttons on screen helps reduce the time spent learning basic functionality.
  
  
• Advanced features should not be in the way for beginners, but should not require multiple-step searching.
  
  
• If possible, make your application consistent with the Palm OS device's native applications; users are used to interacting with them and will easily get used to your application if you follow these rules.
  

Creating a Palm OS User Interface

The small screen and pen-based user interaction require a different UI paradigm than a desktop computer. Here are some guidelines for making your application's interface consistent with other applications, including the PIM applications.

• Provide an application icon for the Launcher. To launch an application, users navigate to the launcher screen and tap on an icon. Choose a short icon name and an easy to recognize icon.
  

  Specify the Application Icon Name and Application Icon using the Project Settings panel in Constructor.

  
  
• Provide a base screen that offers an overview of all available information. This screen is typically a list view. Not all applications need a base screen.
  
  
• Allow users to view most record information by pressing the navigation keys. Each event, to-do item, address, memo page, and so on is called a record.
  
  
• Organize records into user-defined categories if that makes sense. Categories usually result in more efficient screen use. Users can switch between categories using a popup menu or can display all records at once.
  
  
• Detailed information and advanced navigation require the use of a stylus. See Data Entry Guidelines for different data entry modes.
  
  
• Don't require double taps.
  
  
• Don't gray out menu commands or other UI elements; instead, remove an element when it's not available.
  
  
• If you can, allow finger navigation. For finger navigation, buttons need to be big enough for the system to recognize which button has been pushed. This is done by the Palm OS system software.
  
  
• Consider overloading the buttons. If you do overload, release the buttons at every possible opportunity. This is useful only for certain applications, such as games.
  

This section provides information on a variety of UI design issues:

• Navigation Guidelines
  
  
• Preferences Guidelines
  
  
• Data Entry Guidelines
  
  
• Command Execution Guidelines
  
  
• Guidelines for Screen Layout
  
  
• Guidelines for Dialog Box Layout
  

Navigation Guidelines

Users can move through applications by the following methods:

• Switching applications. Users press the physical buttons representing the PIM applications or access a launcher to switch applications.
  

  On Palm OS 2.0 or later devices, users can assign each button to the application of their choice using a Preferences panel.

  When switching to an application, the user is either presented with a standard first screen or returned to the last place in that application.

  
  
• Switching views. Each PIM application has two or more views (or modes) typically
  
  • a list view (or view mode)
  • an edit view (or edit mode)

    The user taps on records or uses command buttons to toggle between these views.

    Edit mode gives users access to the Details button for settings that affect the entire record. They can also access specific menu commands for records. In many applications, tapping on a record switches the application to edit mode and displays an input cursor.

  
  
• Switching categories of records. A popup menu in the top right corner lets users switch between categories. The popup menu is found in the list view of applications that support categories.
  
  
• Switching records in applications. Depending on the application, the user can scroll through lists of records, then tap on a record or a Details button for further information.
  
  
• Graffiti navigation. Support Graffiti navigation:
  
  • Left-right-forward-backward movement as part of a field's behavior.
  • Getting to next and previous screen using the down/up and up/down keystrokes.
  
  
• Cycling through categories. Holding the button on the hard case cycles through all categories.
  
  
• Scrolling. Records too long to display in one screen are scrollable. On-screen scroll buttons allow users to move up or down one line at a time. The physical arrow buttons allow users to move up and down one page at a time.
  

  Scrollbars were introduced in OS 2.0. Scrollbars are optional. Developers have to consider the trade-off between taking up 7 pixels of horizontal space (the width of the scroll bar) vs. providing convenient scrolling for long lists of records.

Preferences Guidelines

Palm OS 2.0 and later has improved preferences facilities. They are available through launch codes, discussed in the chapter "Application Launch Codes" in the Palm OS SDK Reference.

The system now offers application-specific panels, sticky panels, and quick switch, as follows:

• Application-specific panels. Applications can add application-specific preferences panels to follow the system panels when the user cycles though the preferences. To do so, use the common code provided in the Formats example application to make the pull-down menu available. If the application uses the common code, a Done button inserts itself if the panel was called from the application, not sequentially following another panel.
  
  
• Sticky panels. When users bring up a preference panel from the launcher, exit the panel, then bring it up again, the system returns to the last panel used.
  
  
• Quick switch. Applications can now use the launch codes sysAppLaunchCmdPanelCalledFromApp and sysAppLaunchCmdReturnFromPanel, which allow an application to let users change preferences without first selecting the launcher, then selecting the application again.
  

Data Entry Guidelines

Users can enter data by the following methods:

• Graffiti. Graffiti characters are written in the text area on the digitizer and appear on the screen at the cursor location. The user specifies the cursor location by tapping directly on the screen with the stylus.
  

  Some controls accept input from Graffiti: For example, in the time selector dialog, you can write the time into the Graffiti area and it appears as start time or end time. The "next field" stroke switches between start and end time. The "Return" stroke dismisses the dialog.

  For 2.0 and later applications, users expect that your application includes the Graffiti Reference option. You can include this option by calling SysGraffitiReferenceDialog.

  
  
• On-screen keyboard. In place of using Graffiti, the user can tap an on-screen keyboard with the stylus. Any text is entered into a temporary window. When the user dismisses the keyboard, the system inserts that text at the cursor location.
  
  
• Controls. Buttons, check boxes, and popup lists provide a quick way to enter settings and select options.
  
  
• HotSync. The user can type data on the PC and download it to the Palm OS device.
  
  
• Auto-creation. Many applications, such as the DateBook or the Memo Pad provide an auto-create feature. If the user starts to write in a list view with no record selected, a new record is created with no additional interaction.
  

To provide a consistent interface, follow these guidelines when designing the data entry interface for your application:

• Let users perform basic data entry in place.
  
  
• Have the cursor ready and visible if there's only one field for text entry (saves one tap).
  
  
• Provide a Details dialog for more elaborate data entry.
  
  
• Use the following format in the Details dialog:
  

Item (right-justified): Value(left-justified)

for example:

Set Date:	4-1-96
Auto-off after:	2 minutes

• Don't nest dialog boxes too deeply.
  
  
• Provide only one interface per function, that is, allow users to interact with an application through either a button, menu, or popup list. Don't provide both a button and a menu for the same actions.
  

  ---

  NOTE:  

  All developers are urged to include the rules listed below in their test plan. Applications that don't follow these rules may cause problems for other applications on the device.

  ---

  
  

  
  
• Whenever a field for user input is available, make sure that:
  
  • System keyboard is available via shortcut
  • System keyboard is available via menu
  • Graffiti input is possible (regular strokes and shortcuts)
  • Cut, copy, paste, and undo are possible
  
  
• Be sure to handle the clipboard correctly. If you use it, allow users to copy and paste between applications; if you don't, make sure it's intact when you exit.
  

Command Execution Guidelines

Users can execute commands by the following methods:

• Command buttons. Users execute common commands by tapping on command buttons at the bottom of the screen.
  
  
• Menus. Commands not represented by command buttons can be accessed via a simple menu system. The user taps on a menu hard icon in the digitizer area to invoke a menu bar. Beginning in Palm OS 3.5, the user may also invoke a menu bar by tapping the form's title. Provide menu shortcuts if possible.
  

  ---

  NOTE:  

  If you provide shortcuts, make sure that each shortcut is unique among all commands available at that time.

  ---

  
  

  
  
• Graffiti menu command shortcuts. Users can write a special Graffiti stroke and a command keystroke to execute a menu command. This is analogous to keyboard shortcuts on a personal computer. For example, writing the command stroke symbol (a bottom-left to top-right line) and "C" allows the user to copy the selected text.
  
  
• Buttons on command toolbar. Beginning in Palm OS 3.5, entering the Graffiti command stroke symbol displays a command toolbar containing buttons for the commands that are possible in the current user context. For example, if text is selected in a field, the toolbar may display buttons for cut, copy, paste, and undo. Users may either complete the menu command shortcut as described above, or they may tap one of the buttons on the command toolbar.
  

Guidelines for Screen Layout

The illustration below provides some interface guidelines. Each guideline is numbered and explained in more detail below.

Guidelines for Dialog Box Layout

The illustration below provides some guidelines for dialog box interfaces. Each guideline is numbered and explained in more detail below under the same number.

Palm OS Resource Selection: List or Table?

Many developers find it difficult to decide whether to choose a list or a table for certain components of their application.

Use tables when you need quality text handling (including editing in place). Be careful if you work with non-text items in some of the columns, the selection region may be smaller than you need.

Use lists when users select from a predefined list (e.g. categories) or if the application determines the information to be displayed on the fly (based on previous user selections). Remember that you are responsible for scroll button handling and that editing can be non-trivial.

Localization Guidelines

If you're planning to localize the Palm OS software that you're developing, start by looking at the localized versions of the four PIM applications on the device. Then plan your application's interface, keeping in mind localization issues listed below. Also see the chapter "Localized Applications", which describes guidelines for writing code in a localized application.

• If you use the English language version of the software as a guide when designing the layout of the screen, try to allow:
  
  • extra space for strings
  • larger dialogs than the English version requires
  
  
• Abbreviations may be the best way to accommodate the particularly scarce screen real estate on the Palm OS device.
  
  
• Don't put language-dependent strings in code. If you have to display text directly on the screen, remember that a one-line warning or message in one language may need more than one line in another language.
  
  
• Don't depend on the physical characteristics of a string, such as the number of characters, the fact that it contains a particular substring, or any other attribute that might disappear in translation.
  
  
• Consider using string templates. For example, the MemoPad application uses the template: Memo # of %. The application can replace # and % to change the text. Use as many parameters as possible to give localizers greater flexibility. Avoid building sentences by concatenating substrings together, as this often causes translation problems.
  
  
• Remember that user interface elements such as lists, fields, and tips scroll if you need more space.
  

Making Your Application Run on Different Devices

There are many different devices that run Palm OS, and each may have a different version of the OS installed on it (see Table 2.1). Users are not expected to upgrade the Palm OS as frequently as they would an OS on a desktop computer. This fact makes backward compatibility more crucial for Palm applications.

Table 2.1 Some Palm Computing platform devices 

Name	Palm OS Version
Pilot 10001	1.0
Pilot 5000a	1.0
PalmPilota	2.0
PalmPilot Professionala	2.0
Palm III™	3.0
IBM Workpad	2.0 or 3.0
Symbol SPT 1500	3.0
Qualcomm pdQ	3.0
Palm IIIe™	3.1
Palm IIIx™	3.1
Palm V™	3.1
Palm VII™	3.2
Palm IIIc™	3.5

1 No longer available.

This section describes how to make sure your application runs on as many devices as possible by discussing:

• Running New Applications on an Older Device
  
  
• Compiling Older Applications With The Latest SDK
  

Running New Applications on an Older Device

Releases of the Palm OS are binary compatible with each other. If you write a brand new application today, it can run on all versions of the operating system provided the application doesn't use any new features. In other words, if you write your application using only features available in Palm OS 1.0, then your application runs on all devices. If you use 2.0 features, your application won't run on the earliest Palm Computing platform devices, but it will run on all others, and so on.

How can you tell which features are available in each version of the operating system? There are a couple of way to do so:

• The Palm OS SDK Reference has a "Compatibility Guide" appendix. This guide lists the feature and functions introduced in each operating system version greater than 1.0.
  
  
• The header file SysTraps.h (or CoreTraps.h on Palm OS 3.5 and higher) lists all of the system traps available. Traps are listed in the order in which they were introduced to the system, and comments in the file clearly mark where each operating system version begins.
  

Programmatically, you can use the feature manager to determine which features are available on the system the application is running on. Note that you can't always rely on the operating system version number to guarantee that a feature exists. For example, Palm OS version 3.2 introduces wireless support, but not all Palm OS devices have that capability. Thus, checking that the system version is 3.2 does not guarantee that wireless support exists. Consult the "Compatibility Guide" in the Palm OS SDK Reference to learn how to check for the existence of each specific feature.

Compiling Older Applications With The Latest SDK

As a rule, all Palm OS applications developed with an earlier version of the Palm Computing platform SDK should run error-free on the latest release.

If you want to compile your older application under the latest release, you need to look out for functions with a changed API. For any of these functions, the old function still exists with an extension noting the release that supports it, such as V10 or V20.

You can choose one of two options:

• Change the function name to keep using the old API. Your application will then run error free on the newer devices.
  
  
• Update your application to use the new API. The application will then run error free and have access to some new functionality; however, it will no longer run on older devices that use prior releases of the OS.
  

  ---

  NOTE:  

  If you want to compile an existing application with the Palm OS 3.5 SDK, note that some header file names have changed, and the names used for basic types have changed. For example, parameters previously declared as Word are now UInt16 or Int16. To compile existing applications, you'll need to make these changes in your code or include the header file PalmOSCompatibility.h. See the "Compatibility Guide" in the Palm OS SDK Reference for further details.

  ---