Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

4    Customizing Hardware Input

Input Services

Exploring Palm OS®

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 ^TOP^

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 ^TOP^

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 keyDownEvents. 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 

Character

Hard Key

vchrHard1

Usually launch Datebook

vchrHard2

Usually launches Address Book

vchrHard3

Usually launches ToDo

vchrHard4

Usually launches Memo

vchrHardPower

Power button

vchrHardCradle

Button on cradle

vchrHardCradle2

Button on cradle

vchrHardContrast

Contrast button

vchrHardAntenna

Antenna switch

vchrHardBrightness

Brightness button

vchrHard5

Licensee-specific

vchrHard6

Licensee-specific

vchrHard7

Licensee-specific

vchrHard8

Licensee-specific

vchrHard9

Licensee-specific

vchrHard10

Licensee-specific

vchrRockerUp

5-way rocker up

vchrRockerDown

5-way rocker down

vchrRockerLeft

5-way rocker left

vchrRockerRight

5-way rocker right

vchrRockerCenter

5-way rocker center

vchrThumbWheelUp

Thumb-wheel scroll up

vchrThumbWheelDown

Thumb-wheel scroll down

vchrThumbWheelPush

Thumb-wheel push center

vchrThumbWheelBack

Thumb-wheel back button

Disabling the Hard Keys ^TOP^

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 keyDownEvents containing the virtual characters of the keys that you want to disable and ensure that they are never passed to SysHandleEvent(). 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 the appStopEvent 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.

Summary ^TOP^