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

8    Hard Keys Reference

Input Services

Exploring Palm OS®

This chapter provides reference material for manipulating the hard keys. This chapter covers:

Hard Key Constants
Hard Key Functions and Macros

For more information on working with the hard keys, see "Customizing Hardware Input."

Hard Key Constants ^TOP^

Key State Values ^TOP^

Purpose

Used by KeyCurrentState() and KeySetMask() to specify the hardware keys.

Declared In

CmnKeyTypes.h

Constants

#define keyBitsAll 0xFFFFFFFF
A bit mask representing all hard keys.
#define keyBitAntenna 0x00000100
The antenna "key" on wireless devices that allow a user to go on or off line.
#define keyBitContrast 0x00000200
Contract key.
#define keyBitCradle 0x00000080
HotSync® button on the cradle.
#define keyBitHard1 0x00000008
The leftmost application key. This key often brings up the Datebook application.
#define keyBitHard2 0x00000010
The second application key from the left. This key often brings up the Address Book application.
#define keyBitHard3 0x00000020
The third application key from the left. This key often brings up the ToDo application.
#define keyBitHard4 0x00000040
The fourth application key from the left. This key often brings up a NotePad or Memo application.
#define keyBitPageDown 0x00000004
The scroll down button.
#define keyBitPageUp 0x00000002
The scroll up button.
#define keyBitPower 0x00000001
The power key.
#define keyBitRockerCenter 0x00100000
The center button within a five-way rocker.
#define keyBitRockerDown 0x00020000
The down button within a five-way rocker.
#define keyBitRockerLeft 0x00040000
The left button within a five-way rocker.
#define keyBitRockerRight 0x00080000
The right button within a five-way rocker.
#define keyBitRockerUp 0x00010000
The up button within a five-way rocker.
#define keyBitThumbWheelBack 0x00008000
On devices with a thumb wheel, the back button below the wheel.
#define keyBitThumbWheelDown 0x00002000
On devices with a thumb wheel, the thumb wheel has been turned downward.
#define keyBitThumbWheelPush 0x00004000
On devices with a thumb wheel, the thumb wheel has been pressed.
#define keyBitThumbWheelUp 0x00001000
On devices with a thumb wheel, the thumb wheel has been turned upward.

Comments

Not all devices support all of these keys.

Key Rate Constants ^TOP^

Purpose

Specify special values for the key rate set by KeyRates().

Declared In

CmnKeyTypes.h

Constants

#define slowestKeyDelayRate 0xff
Represents the slowest possible delay before the key is recognized as being pressed or before a double-tap is recognized.
#define slowestKeyPeriodRate 0xff
Represents the slowest possible auto-repeat rate.

Hard Key Functions and Macros ^TOP^

KeyCurrentState Function ^TOP^

Purpose

Returns a bit field with bits set for each key that is currently depressed.

Declared In

KeyMgr.h

Prototype

uint32_t KeyCurrentState (
   void
)

Parameters

None.

Returns

A bit mask with bits set for keys that are depressed. See Key State Values.

Comments

Called by applications that need to poll the hardware keys.

If you want to remap the hardware keys, one way to do so is using this function and KeySetMask(). First use KeySetMask() to disable the hardware buttons that you want to remap. Then, periodically poll the keys, possibly in response to the nilEvent in your event loop, by using KeyCurrentState() to see if a hard key has been pressed. Then respond accordingly.


NOTE: This function has high overhead because it performs interprocess-communication. Use it sparingly.

Example

To see if the first application hard key has been pressed, do the following:


if (KeyCurrentState() & keyBitHard1)
  ... 

KeyRates Function ^TOP^

Purpose

Gets or sets the key repeat rates.

Declared In

KeyMgr.h

Prototype

status_t KeyRates (
   Boolean set,
   uint16_t *initDelayP,
   uint16_t *periodP,
   uint16_t *doubleTapDelayP,
   Boolean *queueAheadP
)

Parameters

set
If true, settings are changed; if false, current settings are returned.
initDelayP
Initial delay in ticks for an auto-repeat event.
periodP
Auto-repeat rate specified as period in ticks.
doubleTapDelayP
Maximum double-tap delay, in ticks.
queueAheadP
If true, auto-repeating keeps queueing up key events if the queue has keys in it. If false, auto-repeat doesn't enqueue keys unless the queue is already empty.

Returns

Always returns errNone.

Comments

This function changes the auto-repeat rate of the hardware buttons. This might be useful to game applications that want to use the hardware buttons for control. The current key repeat rates should be restored before the application exits.


NOTE: This function has high overhead because it performs interprocess-communication. Use it sparingly.

Example

The following code shows retrieving the default values, setting the key rates to the slowest possible values for the duration of the game, and then restoring the values.


uint16_t initDelay, period, doubleTapDelay;  
Boolean queueAhead; 
 
//Retrieve old values.  
KeyRates(false, &initDelay, &period, &doubleTapDelay,  
  &queueAhead); 
// set my values 
KeyRates(true, slowestKeyDelayRate, slowestKeyPeriodRate,  
  slowestKeyPeriodRate, false); 
... 
//play game. 
... 
// game is over. Restore previous values. 
KeyRates(true, initDelay, period, doubleTapDelay,  
   queueAhead); 

KeySetMask Function ^TOP^

Purpose

Specifies which keys generate keyDownEvents.

Declared In

KeyMgr.h

Prototype

uint32_t KeySetMask (
   uint32_t keyMask
)

Parameters

keyMask
Mask with bits set for those keys to generate keyDownEvents for. See Key State Values.

Returns

The old key mask.

See Also

KeyCurrentState()