Palm API Guide, Palm OS Platform

#define IsFiveWayNavEvent ( eventP )

Value:

(                                                                                           \
    IsFiveWayNavPalmEvent(eventP)                                                           \
||  TxtCharIsRockerKey((eventP)->data.keyDown.modifiers, (eventP)->data.keyDown.chr)        \
)

A macro to use for apps that support navigation using the 5-way. This macro will let you test whether an event was generated by the 5-way. For applications that treat up and down hard buttons differently than up and down on the 5-way, this macro can be used to determine which action to take if NavKeyPressed returns true for Up or Down.

 if (IsFiveWayNavEvent(eventP)) {
        // Handle five way events here
 }

Definition at line 167 of file common/system/palmOneNavigator.h.

#define IsFiveWayNavPalmEvent ( eventP )

Value:

(                                                                                           \
    (   ((eventP)->data.keyDown.chr == vchrPageUp)                                          \
     || ((eventP)->data.keyDown.chr == vchrPageDown)                                        \
     || ((eventP)->data.keyDown.chr == vchrNavChange) )                                     \
&&  (((eventP)->data.keyDown.keyCode & (navBitsAll | navChangeBitsAll)) != 0)               \
)

A macro to use for apps that support navigation using the Palm style 5-way. This macro will let you test whether an event was generated by the 5-way. For applications that treat up and down hard buttons differently than up and down on the 5-way, this macro can be used to determine which action to take if NavKeyPressed returns true for Up or Down.

Remarks:: Our 5-way events generate lots of detail about what state changed and what didn't. Events are generated even when a button is released, which is a nice bonus. So, to figure out what happened, you have to look at the bits in the keyCode. Because we only use 10 of the bits in the keyCode, and because we may use the remaining bits at some later date, we mask out these 10 bits before doing the test.

((eventP)->data.keyDown.keyCode & (navBitsAll | navChangeBitsAll)) != 0 will be true if any of the 5 buttons is held down, pressed, or released.

((eventP)->data.keyDown.keyCode & navChangeBitsAll) != 0 will be true if any of the 5 buttons is pressed or released.

The situation where these would differ is holding down one or more of the 5 buttons until it generates a repeat event. In that case, none of the navChangeBits will be set.

Unfortunately, on the Treo 600, the vchrPageUp/Down is accompanied by a keyCode that has some nav bits set. Thus, we will not be able to distinguish the HandSpring nav event from the Palm nav event here in such cases, and this macro will return true. Then, when using NavDirectionPressed, via NavKeyPressed e.g., the nav direction palm and HS macros will return false, as this case matches neither, and the vchrPageUp/Down will incorrectly be returned as not a 5-way nav event for our purposes of supporting non-5-way devices. That can be avoided by ensuring the focus state on HandSpring devices is set to object mode for the given form, thus ensuring vchrRockerUp/Down chrs are sent instead of vcrhPageUp/Down chrs, while also ensuring this continues to work as expected on palmOne devices.

 if (IsFiveWayNavPalmEvent(eventP)) {
        // Handle five way events here
 }

Definition at line 124 of file common/system/palmOneNavigator.h.

#define keyBitNavLeft 0x01000000

Key state mask to check the five way navigation LEFT button.

Definition at line 47 of file common/system/palmOneNavigator.h.

#define keyBitNavLRS 0x07000000

Key state mask to check the five way navigation LEFT, RIGHT and SELECT buttons.

Definition at line 50 of file common/system/palmOneNavigator.h.

#define keyBitNavRight 0x02000000

Key state mask to check the five way navigation RIGHT button.

Definition at line 48 of file common/system/palmOneNavigator.h.

#define keyBitNavSelect 0x04000000

Key state mask to check the five way navigation SELECT button.

Definition at line 49 of file common/system/palmOneNavigator.h.

#define navBitDown 0x0002

Key mask for the five way navigation DOWN button.

Definition at line 59 of file common/system/palmOneNavigator.h.

#define navBitLeft 0x0004

Key mask for the five way navigation LEFT button.

Definition at line 60 of file common/system/palmOneNavigator.h.

#define navBitRight 0x0008

Key mask for the five way navigation RIGHT button.

Definition at line 61 of file common/system/palmOneNavigator.h.

#define navBitsAll 0x001F

Key mask for all five way navigation buttons.

Definition at line 63 of file common/system/palmOneNavigator.h.

#define navBitSelect 0x0010

Key mask for the five way navigation SELECT button.

Definition at line 62 of file common/system/palmOneNavigator.h.

#define navBitUp 0x0001

Key mask for the five way navigation UP button.

Definition at line 58 of file common/system/palmOneNavigator.h.

#define navChangeBitsAll 0x1F00

Key mask for all five way navigation buttons state change.

Definition at line 76 of file common/system/palmOneNavigator.h.

#define navChangeDown 0x0200

Key mask for the five way navigation DOWN button state change.

Definition at line 72 of file common/system/palmOneNavigator.h.

#define navChangeLeft 0x0400

Key mask for the five way navigation LEFT button state change.

Definition at line 73 of file common/system/palmOneNavigator.h.

#define navChangeRight 0x0800

Key mask for the five way navigation RIGHT button state change.

Definition at line 74 of file common/system/palmOneNavigator.h.

#define navChangeSelect 0x1000

Key mask for the five way navigation SELECT button state change.

Definition at line 75 of file common/system/palmOneNavigator.h.

#define navChangeUp 0x0100

Key mask for the five way navigation UP button state change.

Definition at line 71 of file common/system/palmOneNavigator.h.

#define NavDirectionHSPressed	(	eventP,
		nav		)

Value:

(                                                                                       \
        ((vchrRocker ## nav) != vchrRockerCenter)                                       \
     && (   (   (((eventP)->data.keyDown.modifiers & commandKeyMask) != 0)              \
             && ((eventP)->data.keyDown.chr == (vchrRocker ## nav))))                   \
)

A macro to use for apps that support navigation using the HandSpring 5-way. By using this macro, we have consistent behavior in all our apps when it comes to how it handles multiple simultaneous button presses. You can use this macro even if the device does not have a 5-way controller.

Remarks:: Determine if the key down event indicates the HandSpring nav direction type.

 if (NavDirectionHSPressed(eventP, Left))
 if (NavDirectionHSPressed(eventP, Right))
 if (NavDirectionHSPressed(eventP, Up))       - also works without 5-way
 if (NavDirectionHSPressed(eventP, Down))     - also works without 5-way

Definition at line 267 of file common/system/palmOneNavigator.h.

#define NavDirectionPalmPressed	(	eventP,
		nav		)

Value:

(                                                                                       \
    ((eventP)->data.keyDown.modifiers & autoRepeatKeyMask)                              \
        ? (((eventP)->data.keyDown.keyCode & (navBitsAll | navChangeBitsAll)) ==        \
            (navBit ## nav))                                                            \
        : (((eventP)->data.keyDown.keyCode & (navBitsAll | navChangeBitsAll)) ==        \
            (navBit ## nav | navChange ## nav))                                         \
)

A macro to use for apps that support navigation using the Palm 5-way. By using this macro, we have consistent behavior in all our apps when it comes to how it handles multiple simultaneous button presses. You can use this macro even if the device does not have a 5-way controller.

Remarks:: Determine if the key down event indicates the palmOne nav direction type.

 if (NavDirectionPalmPressed(eventP, Left))
 if (NavDirectionPalmPressed(eventP, Right))
 if (NavDirectionPalmPressed(eventP, Up))     - also works without 5-way
 if (NavDirectionPalmPressed(eventP, Down))   - also works without 5-way

Definition at line 292 of file common/system/palmOneNavigator.h.

#define NavDirectionPressed	(	eventP,
		nav		)

Value:

(                                                                                       \
    IsFiveWayNavEvent(eventP)                                                           \
        ? (   NavDirectionPalmPressed(eventP, nav)                                      \
           || NavDirectionHSPressed(eventP, nav))                                       \
        : (   ((eventP)->data.keyDown.chr == vchrPageUp && (navBit ## nav) == navBitUp)      \
           || ((eventP)->data.keyDown.chr == vchrPageDown && (navBit ## nav) == navBitDown)) \
)

A macro to use for apps that support navigation using the 5-way. By using this macro, we have consistent behavior in all our apps when it comes to how it handles multiple simultaneous button presses. You can use this macro even if the device does not have a 5-way controller.

Remarks:: Act only when one direction is pressed without any other direction (or select) being down at the time. Repeat if the button is held down, but not if other buttons are pressed.

 if (NavDirectionPressed(eventP, Left))
 if (NavDirectionPressed(eventP, Right))
 if (NavDirectionPressed(eventP, Up))       - also works without 5-way
 if (NavDirectionPressed(eventP, Down)) - also works without 5-way

Definition at line 321 of file common/system/palmOneNavigator.h.

#define navFtrCreator 'fway'

Creator ID for 5-Way navigator.

Definition at line 37 of file common/system/palmOneNavigator.h.

#define navFtrVersion 0

Feature id for 5-Way.

Definition at line 38 of file common/system/palmOneNavigator.h.

#define NavKeyPressed	(	eventP,
		nav		)

Value:

(                                                                                       \
    (navBit ## nav == navBitSelect)                                                     \
        ? NavSelectPressed(eventP)                                                      \
        : NavDirectionPressed(eventP, nav)                                              \
)

A macro to use for apps that support navigation using the 5-way. By using this macro, we have consistent behavior in all our apps when it comes to how it handles multiple simultaneous button presses. You can use this macro even if the device does not have a 5-way controller.

 if (NavKeyPressed(eventP, Select))
 if (NavKeyPressed(eventP, Left))
 if (NavKeyPressed(eventP, Right))
 if (NavKeyPressed(eventP, Up))     - also works without 5-way
 if (NavKeyPressed(eventP, Down))       - also works without 5-way

Definition at line 345 of file common/system/palmOneNavigator.h.

#define NavSelectHSPressed ( eventP )

Value:

(                                                                                       \
       (((eventP)->data.keyDown.modifiers & commandKeyMask) != 0)                       \
    && ((eventP)->data.keyDown.chr == vchrRockerCenter)                                 \
)

A macro to use for apps that support navigation using the HandSpring 5-way. By using this macro, we have consistent behavior in all our apps when it comes to how it handles multiple simultaneous button presses.

Remarks:: Checks if it the key down event is of the HandSpring "select" key type.

 if (NavSelectHSPressed(eventP)) {
        // Select was pressed
 }

Definition at line 188 of file common/system/palmOneNavigator.h.

#define NavSelectPalmPressed ( eventP )

Value:

(                                                                                       \
       (((eventP)->data.keyDown.modifiers & autoRepeatKeyMask) == 0)                    \
    && ((eventP)->data.keyDown.chr == vchrNavChange)                                    \
    && (((eventP)->data.keyDown.keyCode & (navBitsAll | navChangeBitsAll)) ==           \
                                                                     navChangeSelect)   \
)

A macro to use for apps that support navigation using the Palm 5-way. By using this macro, we have consistent behavior in all our apps when it comes to how it handles multiple simultaneous button presses.

Remarks:: Checks if it the key down event is of the Palm "select" key type. Note the redundant check of the keyDown.chr. This is necessary to prevent a false positive, because the modified DAL code for the new 5-way still generates the same keyCodes (it was easier that way), but doesn't generate the same keyDown.chr (new vchrRocker instead). This redundancy avoids a double-press behavior.

 if (NavSelectPalmPressed(eventP)) {
        // Select was pressed
 }

Definition at line 214 of file common/system/palmOneNavigator.h.

#define NavSelectPressed ( eventP )

Value:

(                                                                                       \
    IsFiveWayNavEvent(eventP)                                                           \
&&  (   NavSelectPalmPressed(eventP)                                                    \
     || NavSelectHSPressed(eventP))                                                     \
)

A macro to use for apps that support navigation using the 5-way. By using this macro, we have consistent behavior in all our apps when it comes to how it handles multiple simultaneous button presses.

Remarks:: Only act when the select button is released, and only if none of the direction buttons are down (or being released) at the time, and only if the select button has not been held down long enough to start repeating. By ignoring repeat events for the select button, we ensure that the launcher will be run if the select button is held down. By waiting until the button is released, we ensure that the select action is not taken before the launcher is run.

 if (NavSelectPressed(eventP)) {
        // Select was pressed
 }

Definition at line 242 of file common/system/palmOneNavigator.h.

#define navVersion 0x00010000

Version for 5-Way.

Definition at line 39 of file common/system/palmOneNavigator.h.

common/system/palmOneNavigator.h File Reference

Defines

Define Documentation