This chapter describes how to work with the hard keys on the device. As described in Chapter 1, "Receiving Input," you typically let the system handle all hard keys. However, some applications may want to perform the following tasks:
Replacing a Built-in Application
Remapping the Hard Keys
Disabling the Hard Keys
Replacing a Built-in Application
Palm OS® contains system-wide preferences that the user sets to have the system work they way he or she likes. There are system preferences to remap the application hard keys and have them launch something other than the default applications. You should respect the user's preferences, but you are allowed to set the preference after asking the user if you may do so.
Suppose you are writing a replacement for the built-in Address Book application. You want to make it more convenient for your users to remap the Address Book button, so you might display an alert that asks first-time users if they want the button remapped. If they tap OK, then you should call PrefSetPreference()
with the new value. See Listing 4.1.
Listing 4.1 Remapping the hard key to launch your application
if (PrefGetPreference(prefHard2CharAppCreator != myAppCreatorId)) { if (FrmAlert(MakeMeTheDefaultAlert) == 0) { /* user said OK to change */ PrefSetPreference(prefHard2CharAppCreator, myAppCreatorId); } }
See Exploring Palm OS: System Management for more information about setting and getting user preferences.
Remapping the Hard Keys
Sometimes, you want to remap the hard key only while your application is running. A game might want to remap the hard keys to perform some special action such as launching missiles or moving pieces around a board.
As explained previously, when the user presses a hard key, Palm OS creates a keyDownEvent
containing a virtual character that specifies which key was pressed. The SysHandleEvent()
function handles most of these keyDownEvent
s. If you want to remap the hard keys, you must intercept them before SysHandleEvent()
. See Listing 4.2.
Listing 4.2 Intercepting hard key events
void EventLoop (void) { uint16_t error; EventType event; boolean handled = false; do { EvtGetEvent(&event, evtWaitForever); //If user pressed first hard key, do something special. if ((event.eType == keyDownEvent) && (event.data.keyDown.chr == vchrHard1) && (event.data.keyDown.modifiers & commandKeyMask)) { handled = HardKeyHandleEvent(&event); } //Proceed with normal event loop. if (!handled) { if (!SysHandleEvent(&event)) if (!MenuHandleEvent(NULL, &event, &error) if (!ApplicationHandleEvent(&event)) FrmDispatchEvent(&event); } while (event.eType != appStopEvent); }
In general, only games should remap the hard keys. Users expect the hard keys to behave as they have set them up to behave in the system preferences.
Table 4.1 lists the virtual characters that map to hardware controls on many devices. Remember that not all devices support all of these controls. See Chars.h
for a complete list of virtual characters.
Table 4.1 Hard key virtual characters
Disabling the Hard Keys
In very rare circumstances, you may want to disable the hard keys entirely.
WARNING! Do not disable the hard keys unless you have a very good reason. If you are writing a general-purpose, third-party consumer application, never disable the hard keys. Do so only if you are writing an enterprise-level application and your client insists that the device must never be used as a personal digital assistant.
There are two approaches to disabling the hard keys:
- Intercept the
keyDownEvent
s containing the virtual characters of the keys that you want to disable and ensure that they are never passed toSysHandleEvent()
. This approach is similar to that shown in Listing 4.2.Keep in mind that modal dialogs and alerts run their own event loops. If the user presses a hard key while an alert is being displayed, the alert calls
SysHandleEvent()
, and allows your application to exit. If you do not want this behavior, look for and discard theappStopEvent
after your application returns from a dialog or alert handler. - Use the function
KeySetMask()
to disable the hard keys while your application is active. Listing 4.3 shows an example that disables the four application hard keys while an application is running.
Listing 4.3 Using KeySetMask()
void StartApplication(void) { uint32_t disableKeyMask = keyBitHard1 | keyBitHard2 | keyBitHard3 | keyBitHard4; KeySetMask(~disableKeyMask); ... } void StopApplication(void) { KeySetMask(keyBitsAll); }
Keep in mind that KeySetMask()
only disables hardware buttons. You won't be able to disable the Application Launcher icon in the status bar, for example.