(Online version only)
|
API Guide Home (Online version only) |
|
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 |