API Guide Home (Online version only) |

# common/system/palmOneNavigator.h

Go to the documentation of this file.

    00001 /******************************************************************************
    00002  * Copyright (c) 2005 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  *****************************************************************************/
    00005 /**
    00006  *@ingroup System
    00007  *
    00008  */
    00009
    00010 /**
    00011  * @file    palmOneNavigator.h
    00012  * @version 1.0
    00013  * @date    03/03/2004
    00014  *
    00015  * @brief Contains 5-way navigator-specific definitions.
    00016  *
    00017  *    Five-way navigation macros and values for key states are included
    00018  *    in this file.
    00019  *
    00020  * <hr>
    00021  */
    00022
    00023 #ifndef __PALMONENAVIGATOR_H__
    00024 #define __PALMONENAVIGATOR_H__
    00025
    00026 // palmOne includes:
    00027 #include <Common/System/palmOneChars.h>
    00028
    00029 // Handspring includes:
    00030 #include <HsNavCommon.h>
    00031
    00032 /**
    00033  * @name
    00034  *
    00035  */
    00036 /*@{*/
    00037 #define navFtrCreator               'fway'      /**< Creator ID for 5-Way navigator. */
    00038 #define navFtrVersion               0       /**< Feature id for 5-Way. */
    00039 #define navVersion                  0x00010000  /**< Version for 5-Way. */
    00040 /*@}*/
    00041
    00042 /**
    00043  * @name
    00044  *
    00045  */
    00046 /*@{*/
    00047 #define keyBitNavLeft           0x01000000  /**< Key state mask to check the five way navigation LEFT button. */
    00048 #define keyBitNavRight          0x02000000  /**< Key state mask to check the five way navigation RIGHT button. */
    00049 #define keyBitNavSelect         0x04000000  /**< Key state mask to check the five way navigation SELECT button. */
    00050 #define keyBitNavLRS            0x07000000  /**< Key state mask to check the five way navigation LEFT, RIGHT and SELECT buttons. */
    00051 /*@}*/
    00052
    00053 /**
    00054  * @name
    00055  *
    00056  */
    00057 /*@{*/
    00058 #define navBitUp            0x0001      /**< Key mask for the five way navigation UP button. */
    00059 #define navBitDown          0x0002      /**< Key mask for the five way navigation DOWN button. */
    00060 #define navBitLeft          0x0004      /**< Key mask for the five way navigation LEFT button. */
    00061 #define navBitRight         0x0008      /**< Key mask for the five way navigation RIGHT button. */
    00062 #define navBitSelect            0x0010      /**< Key mask for the five way navigation SELECT button. */
    00063 #define navBitsAll          0x001F      /**< Key mask for all five way navigation buttons. */
    00064 /*@}*/
    00065
    00066 /**
    00067  * @name
    00068  *
    00069  */
    00070 /*@{*/
    00071 #define navChangeUp         0x0100      /**< Key mask for the five way navigation UP button state change. */
    00072 #define navChangeDown           0x0200      /**< Key mask for the five way navigation DOWN button state change. */
    00073 #define navChangeLeft           0x0400      /**< Key mask for the five way navigation LEFT button state change. */
    00074 #define navChangeRight          0x0800      /**< Key mask for the five way navigation RIGHT button state change. */
    00075 #define navChangeSelect         0x1000      /**< Key mask for the five way navigation SELECT button state change. */
    00076 #define navChangeBitsAll        0x1F00      /**< Key mask for all five way navigation buttons state change. */
    00077 /*@}*/
    00078
    00079 /**
    00080  * @def IsFiveWayNavPalmEvent(eventP)
    00081  *
    00082  * A macro to use for apps that support navigation using the Palm style 5-way.
    00083  * This macro will let you test whether an event was generated by the 5-way.
    00084  * For applications that treat up and down hard buttons differently than up and
    00085  * down on the 5-way, this macro can be used to determine which action to take
    00086  * if NavKeyPressed returns true for Up or Down.
    00087  *
    00088  * @remark
    00089  * Our 5-way events generate lots of detail about what state changed and what
    00090  * didn't. Events are generated even when a button is released, which is a
    00091  * nice bonus. So, to figure out what happened, you have to look at the bits
    00092  * in the keyCode. Because we only use 10 of the bits in the keyCode, and
    00093  * because we may use the remaining bits at some later date, we
    00094  * mask out these 10 bits before doing the test.
    00095  *
    00096  *  ((eventP)->data.keyDown.keyCode & (navBitsAll | navChangeBitsAll)) != 0
    00097  * will be true if any of the 5 buttons is held down, pressed, or released.
    00098  *
    00099  *  ((eventP)->data.keyDown.keyCode & navChangeBitsAll) != 0
    00100  * will be true if any of the 5 buttons is pressed or released.
    00101  *
    00102  * The situation where these would differ is holding down one or more of the
    00103  * 5 buttons until it generates a repeat event. In that case, none of the
    00104  * navChangeBits will be set.
    00105  *
    00106  * Unfortunately, on the Treo 600, the vchrPageUp/Down is accompanied
    00107  * by a keyCode that has some nav bits set.  Thus, we will not be able to
    00108  * distinguish the HandSpring nav event from the Palm nav event here in such
    00109  * cases, and this macro will return true.  Then, when using NavDirectionPressed,
    00110  * via NavKeyPressed e.g., the nav direction palm and HS macros will return
    00111  * false, as this case matches neither, and the vchrPageUp/Down will incorrectly
    00112  * be returned as not a 5-way nav event for our purposes of supporting non-5-way
    00113  * devices.
    00114  * That can be avoided by ensuring the focus state on HandSpring devices is
    00115  * set to object mode for the given form, thus ensuring vchrRockerUp/Down chrs are
    00116  * sent instead of vcrhPageUp/Down chrs, while also ensuring this continues
    00117  * to work as expected on palmOne devices.
    00118  *
    00119  * @sample
    00120  * @code if (IsFiveWayNavPalmEvent(eventP)) {
    00121  *      // Handle five way events here
    00122  * } @endcode
    00123  */
    00124 #define IsFiveWayNavPalmEvent(eventP)                                                       \
    00125 (                                                                                           \
    00126     (   ((eventP)->data.keyDown.chr == vchrPageUp)                                          \
    00127      || ((eventP)->data.keyDown.chr == vchrPageDown)                                        \
    00128      || ((eventP)->data.keyDown.chr == vchrNavChange) )                                     \
    00129 &&  (((eventP)->data.keyDown.keyCode & (navBitsAll | navChangeBitsAll)) != 0)               \
    00130 )
    00131
    00132 /*
    00133 #define IsFiveWayNavPalmEvent(eventP)                                                       \
    00134 (   ((eventP)->data.keyDown.chr == vchrNavChange)                                           \
    00135 ||                                                                                          \
    00136     (   (   ((eventP)->data.keyDown.chr == vchrPageUp)                                      \
    00137          || ((eventP)->data.keyDown.chr == vchrPageDown) )                                  \
    00138      && (   (((eventP)->data.keyDown.keyCode & navChangeBitsAll) != 0)                      \
    00139          || (((eventP)->data.keyDown.modifiers & autoRepeatKeyMask) != 0)))                 \
    00140 )
    00141 */
    00142
    00143 /*
    00144 #define IsFiveWayNavPalmEvent(eventP)                                                       \
    00145 (   ((eventP)->data.keyDown.chr == vchrNavChange)                                           \
    00146 ||  (   ((eventP)->data.keyDown.chr == vchrPageUp)                                          \
    00147      && (((eventP)->data.keyDown.keyCode & (navBitUp | navChangeUp)) != 0) )                \
    00148 ||  (   ((eventP)->data.keyDown.chr == vchrPageDown)                                        \
    00149      && (((eventP)->data.keyDown.keyCode & (navBitDown | navChangeDown)) != 0) )            \
    00150 )
    00151 */
    00152
    00153 /**
    00154  * @def IsFiveWayNavEvent(eventP)
    00155  *
    00156  * A macro to use for apps that support navigation using the 5-way.
    00157  * This macro will let you test whether an event was generated by the 5-way.
    00158  * For applications that treat up and down hard buttons differently than up and
    00159  * down on the 5-way, this macro can be used to determine which action to take
    00160  * if NavKeyPressed returns true for Up or Down.
    00161  *
    00162  * @sample
    00163  * @code if (IsFiveWayNavEvent(eventP)) {
    00164  *      // Handle five way events here
    00165  * } @endcode
    00166  */
    00167 #define IsFiveWayNavEvent(eventP)                                                           \
    00168 (                                                                                           \
    00169     IsFiveWayNavPalmEvent(eventP)                                                           \
    00170 ||  TxtCharIsRockerKey((eventP)->data.keyDown.modifiers, (eventP)->data.keyDown.chr)        \
    00171 )
    00172
    00173
    00174 /**
    00175  * A macro to use for apps that support navigation using the HandSpring 5-way.
    00176  * By using this macro, we have consistent behavior in all our apps
    00177  * when it comes to how it handles multiple simultaneous button presses.
    00178  *
    00179  * @remark
    00180  * Checks if it the key down event is of the HandSpring "select" key type.
    00181  *
    00182  * @sample
    00183  * @code if (NavSelectHSPressed(eventP)) {
    00184  *      // Select was pressed
    00185  * } @endcode
    00186  *
    00187  */
    00188 #define NavSelectHSPressed(eventP)                                                      \
    00189 (                                                                                       \
    00190        (((eventP)->data.keyDown.modifiers & commandKeyMask) != 0)                       \
    00191     && ((eventP)->data.keyDown.chr == vchrRockerCenter)                                 \
    00192 )
    00193
    00194
    00195 /**
    00196  * A macro to use for apps that support navigation using the Palm 5-way.
    00197  * By using this macro, we have consistent behavior in all our apps
    00198  * when it comes to how it handles multiple simultaneous button presses.
    00199  *
    00200  * @remark
    00201  * Checks if it the key down event is of the Palm "select" key type.
    00202  * Note the redundant check of the keyDown.chr.  This is necessary to
    00203  * prevent a false positive, because the modified DAL code for the
    00204  * new 5-way still generates the same keyCodes (it was easier that way),
    00205  * but doesn't generate the same keyDown.chr (new vchrRocker instead).
    00206  * This redundancy avoids a double-press behavior.
    00207  *
    00208  * @sample
    00209  * @code if (NavSelectPalmPressed(eventP)) {
    00210  *      // Select was pressed
    00211  * } @endcode
    00212  *
    00213  */
    00214 #define NavSelectPalmPressed(eventP)                                                    \
    00215 (                                                                                       \
    00216        (((eventP)->data.keyDown.modifiers & autoRepeatKeyMask) == 0)                    \
    00217     && ((eventP)->data.keyDown.chr == vchrNavChange)                                    \
    00218     && (((eventP)->data.keyDown.keyCode & (navBitsAll | navChangeBitsAll)) ==           \
    00219                                                                      navChangeSelect)   \
    00220 )
    00221
    00222
    00223 /**
    00224  * A macro to use for apps that support navigation using the 5-way.
    00225  * By using this macro, we have consistent behavior in all our apps
    00226  * when it comes to how it handles multiple simultaneous button presses.
    00227  *
    00228  * @remark
    00229  * Only act when the select button is released, and only if none of the
    00230  * direction buttons are down (or being released) at the time, and only if the select
    00231  * button has not been held down long enough to start repeating. By ignoring repeat
    00232  * events for the select button, we ensure that the launcher will be run if the select
    00233  * button is held down. By waiting until the button is released, we ensure that the
    00234  * select action is not taken before the launcher is run.
    00235  *
    00236  * @sample
    00237  * @code if (NavSelectPressed(eventP)) {
    00238  *      // Select was pressed
    00239  * } @endcode
    00240  *
    00241  */
    00242 #define NavSelectPressed(eventP)                                                        \
    00243 (                                                                                       \
    00244     IsFiveWayNavEvent(eventP)                                                           \
    00245 &&  (   NavSelectPalmPressed(eventP)                                                    \
    00246      || NavSelectHSPressed(eventP))                                                     \
    00247 )
    00248
    00249
    00250 /**
    00251  * A macro to use for apps that support navigation using the HandSpring 5-way.
    00252  * By using this macro, we have consistent behavior in all our apps
    00253  * when it comes to how it handles multiple simultaneous button presses.
    00254  * You can use this macro even if the device does not have a 5-way controller.
    00255  *
    00256  * @remark
    00257  * Determine if the key down event indicates the HandSpring nav direction type.
    00258  *
    00259  * @sample
    00260  * @code
    00261  * if (NavDirectionHSPressed(eventP, Left))
    00262  * if (NavDirectionHSPressed(eventP, Right))
    00263  * if (NavDirectionHSPressed(eventP, Up))       - also works without 5-way
    00264  * if (NavDirectionHSPressed(eventP, Down))     - also works without 5-way @endcode
    00265  *
    00266  */
    00267 #define NavDirectionHSPressed(eventP, nav)                                              \
    00268 (                                                                                       \
    00269         ((vchrRocker ## nav) != vchrRockerCenter)                                       \
    00270      && (   (   (((eventP)->data.keyDown.modifiers & commandKeyMask) != 0)              \
    00271              && ((eventP)->data.keyDown.chr == (vchrRocker ## nav))))                   \
    00272 )
    00273
    00274
    00275 /**
    00276  * A macro to use for apps that support navigation using the Palm 5-way.
    00277  * By using this macro, we have consistent behavior in all our apps
    00278  * when it comes to how it handles multiple simultaneous button presses.
    00279  * You can use this macro even if the device does not have a 5-way controller.
    00280  *
    00281  * @remark
    00282  * Determine if the key down event indicates the palmOne nav direction type.
    00283  *
    00284  * @sample
    00285  * @code
    00286  * if (NavDirectionPalmPressed(eventP, Left))
    00287  * if (NavDirectionPalmPressed(eventP, Right))
    00288  * if (NavDirectionPalmPressed(eventP, Up))     - also works without 5-way
    00289  * if (NavDirectionPalmPressed(eventP, Down))   - also works without 5-way @endcode
    00290  *
    00291  */
    00292 #define NavDirectionPalmPressed(eventP, nav)                                            \
    00293 (                                                                                       \
    00294     ((eventP)->data.keyDown.modifiers & autoRepeatKeyMask)                              \
    00295         ? (((eventP)->data.keyDown.keyCode & (navBitsAll | navChangeBitsAll)) ==        \
    00296             (navBit ## nav))                                                            \
    00297         : (((eventP)->data.keyDown.keyCode & (navBitsAll | navChangeBitsAll)) ==        \
    00298             (navBit ## nav | navChange ## nav))                                         \
    00299 )
    00300
    00301
    00302 /**
    00303  * A macro to use for apps that support navigation using the 5-way.
    00304  * By using this macro, we have consistent behavior in all our apps
    00305  * when it comes to how it handles multiple simultaneous button presses.
    00306  * You can use this macro even if the device does not have a 5-way controller.
    00307  *
    00308  * @remark
    00309  * Act only when one direction is pressed without any other direction (or select) being
    00310  * down at the time. Repeat if the button is held down, but not if other buttons are
    00311  * pressed.
    00312  *
    00313  * @sample
    00314  * @code
    00315  * if (NavDirectionPressed(eventP, Left))
    00316  * if (NavDirectionPressed(eventP, Right))
    00317  * if (NavDirectionPressed(eventP, Up))     - also works without 5-way
    00318  * if (NavDirectionPressed(eventP, Down))   - also works without 5-way @endcode
    00319  *
    00320  */
    00321 #define NavDirectionPressed(eventP, nav)                                                \
    00322 (                                                                                       \
    00323     IsFiveWayNavEvent(eventP)                                                           \
    00324         ? (   NavDirectionPalmPressed(eventP, nav)                                      \
    00325            || NavDirectionHSPressed(eventP, nav))                                       \
    00326         : (   ((eventP)->data.keyDown.chr == vchrPageUp && (navBit ## nav) == navBitUp)      \
    00327            || ((eventP)->data.keyDown.chr == vchrPageDown && (navBit ## nav) == navBitDown)) \
    00328 )
    00329
    00330
    00331 /**
    00332  * A macro to use for apps that support navigation using the 5-way.
    00333  * By using this macro, we have consistent behavior in all our apps
    00334  * when it comes to how it handles multiple simultaneous button presses.
    00335  * You can use this macro even if the device does not have a 5-way controller.
    00336  *
    00337  * @sample
    00338  * @code
    00339  * if (NavKeyPressed(eventP, Select))
    00340  * if (NavKeyPressed(eventP, Left))
    00341  * if (NavKeyPressed(eventP, Right))
    00342  * if (NavKeyPressed(eventP, Up))       - also works without 5-way
    00343  * if (NavKeyPressed(eventP, Down))     - also works without 5-way @endcode
    00344  */
    00345 #define NavKeyPressed(eventP, nav)                                                      \
    00346 (                                                                                       \
    00347     (navBit ## nav == navBitSelect)                                                     \
    00348         ? NavSelectPressed(eventP)                                                      \
    00349         : NavDirectionPressed(eventP, nav)                                              \
    00350 )
    00351
    00352 #endif // __PALMONENAVIGATOR_H__

Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:06:54 2008 for Palm API Guide