API Guide Home (Online version only) |

# PmKeyLib.h

Go to the documentation of this file.

    00001 /******************************************************************************
    00002  * Copyright (c) 2004 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  *****************************************************************************/
    00005 /**
    00006  * @ingroup PmKeyLib
    00007  */
    00008
    00009 /**
    00010  * @file  PmKeyLib.h
    00011  * @brief System Library that exports key-related APIs.
    00012  *
    00013  * This library is based on key APIs from HsExtensions and was broken apart from HsExtensions
    00014  * so the APIs could be ported to other platforms.
    00015  *
    00016  */
    00017
    00018 /*
    00019  * $Id$
    00020  *
    00021  *****************************************************************************/
    00022
    00023 #ifndef __PMKEYLIB_H__
    00024 #define __PMKEYLIB_H__
    00025
    00026
    00027 #include <PmKeyLibCommon.h>
    00028
    00029 /********************************************************************
    00030  * Prototypes
    00031  ********************************************************************/
    00032
    00033 #ifdef __cplusplus
    00034 extern "C" {
    00035 #endif
    00036
    00037 /// Standard open library function
    00038 ///
    00039 /// @param refNum: IN: library reference number (returned by SysLibFind() / SysLibLoad() )
    00040 /// @retval Err error code.
    00041 Err
    00042 PmKeyLibOpen (UInt16 refNum)
    00043             SYS_TRAP (kPmKeyLibTrapOpen);
    00044
    00045 /// Standard close library function
    00046 ///
    00047 /// @param refNum: IN: library reference number (returned by SysLibFind() / SysLibLoad() )
    00048 /// @retval Err error code.
    00049 Err
    00050 PmKeyLibClose (UInt16 refNum)
    00051             SYS_TRAP (kPmKeyLibTrapClose);
    00052
    00053 /// Get the current state of specified keys
    00054 ///
    00055 /// @param refNum:      IN:  library reference number (returned by SysLibFind() / SysLibLoad() )
    00056 /// @param count:       IN:  number of elements in keyCodes[] and pressed[]
    00057 /// @param keyCodes:    IN:  array of keyCodes to test
    00058 /// @param pressed:     OUT: Each element is set to true if the key specified by the
    00059 ///                          corresponding element in keyCodes[] is pressed, and set
    00060 ///                          to false if it is not pressed.
    00061 ///                          It is acceptable to pass NULL if only the return value is of interest.
    00062 /// @retval UInt16 count of keys that are pressed.
    00063 UInt16
    00064 PmKeyKeysPressed (UInt16 refNum, UInt16 count, const UInt16 keyCodes[], Boolean pressed[])
    00065             SYS_TRAP (kPmKeyLibTrapKeysPressed);
    00066
    00067 /// Stop a key from sending any more auto repeat events until
    00068 /// it is released.
    00069 ///
    00070 /// @param refNum:      IN: library reference number (returned by SysLibFind() / SysLibLoad() )
    00071 /// @param keyCode:     IN: key to stop
    00072 /// @retval Err errNone if the keyCode is the last key pressed and it is still held.
    00073 Err
    00074 PmKeyStop (UInt16 refNum, UInt16 keyCode)
    00075             SYS_TRAP (kPmKeyLibTrapStop);
    00076
    00077 /// Enable/disable a key from generating key events.
    00078 /// This extends HALKeySetMask().
    00079 ///
    00080 /// @param refNum:  IN: library reference number (returned by SysLibFind() / SysLibLoad() )
    00081 /// @param keyCode: IN: the key to enable/disable
    00082 /// @param enabled: IN: true to enable, false to disable
    00083 /// @retval Boolean true if previously enabled
    00084 Boolean
    00085 PmKeyEnableKey (UInt16 refNum, UInt16 keyCode, Boolean enabled)
    00086             SYS_TRAP (kPmKeyLibTrapEnableKey);
    00087
    00088 /// Determine which key generates a certain character
    00089 /// This is the complement of HALKeyKeyCodeToChrCode()
    00090 ///
    00091 /// @param refNum:  IN: library reference number (returned by SysLibFind() / SysLibLoad() )
    00092 /// @param chrCode: IN: the character to search for
    00093 /// @retval UInt16 the keycode returned.
    00094 UInt16
    00095 PmKeyChrCodeToKeyCode (UInt16 refNum, UInt16 chrCode)
    00096             SYS_TRAP (kPmKeyLibTrapChrCodeToKeyCode);
    00097
    00098 /// Translate a key code to the character generated by that key.
    00099 /// Each key can generate several different characters, depending
    00100 /// on which modifier keys are held when it is pressed. The caller
    00101 /// needs to specify which modified state of the key should be used
    00102 /// to select the appropriate character.
    00103 /// This is the complement of HALKeyChrCodeToKeyCode().
    00104 ///
    00105 /// @param refNum:          IN:  library reference number (returned by SysLibFind() / SysLibLoad() )
    00106 /// @param keyCode:         IN:  the key to lookup
    00107 /// @param modifiersIn:     IN:  Modifier mask indicating which character
    00108 ///                              should be returned
    00109 /// @param chrP:            OUT: The character produced by the key
    00110 /// @param modifiersOutP:   OUT: The keyMask bits that must be set if a keyDown event is
    00111 ///                              formed with the character. (Not including the bits
    00112 ///                              set in modifiersIn)
    00113 /// @retval None.
    00114 void
    00115 PmKeyKeyCodeToChrCode (UInt16 refNum, UInt16 keyCode, UInt16 modifiersIn,
    00116                        UInt16* chrP, UInt16* modifiersOutP)
    00117             SYS_TRAP (kPmKeyLibTrapKeyCodeToChrCode);
    00118
    00119 /// Determine if an event came from the physical keyboard
    00120 ///
    00121 /// @param refNum: IN: library reference number (returned by SysLibFind() / SysLibLoad() )
    00122 /// @param eventP: IN: the event to check
    00123 /// @retval Boolean true if the event came from the keyboard
    00124 Boolean
    00125 PmKeyEventIsFromKeyboard (UInt16 refNum, EventPtr eventP)
    00126             SYS_TRAP (kPmKeyLibTrapEventIsFromKeyboard);
    00127
    00128 /// Get any palmOne specific key attributes that aren't
    00129 /// appropriate to be accessed through a feature. (e.g.
    00130 /// dynamic information about device state)
    00131 ///
    00132 /// The following code sample retrieves the keyguard state (active or
    00133 /// inactive) and disables it accordingly.
    00134 /// @code
    00135 ///     UInt32 keyguard;
    00136 ///     PmKeyAttrGet (pmKeyAttrKeyboardLocked, 0, &keyguard);
    00137 ///     if (keyguard)
    00138 ///     {
    00139 ///         keyguard = 0;
    00140 ///         PmKeyAttrSet (pmKeyAttrKeyboardLocked, 0, &keyguard);
    00141 ///     }
    00142 /// @endcode
    00143 ///
    00144 /// Note that there are new attributes added for version 3 of the
    00145 /// PmKeyAttrGet() function, so it is highly recommended that any
    00146 /// application that calls this function does one or both of the
    00147 /// following:
    00148 ///
    00149 /// Check the return code.  If its hsErrNotSupported, then the attribute
    00150 /// that the function is looking for is NOT SUPPORTED using that particular
    00151 /// version of the library!
    00152 ///
    00153 ///  - OR -
    00154 ///
    00155 /// Check the version number of the PmKeyLib. To do this, load the PmKeyLib
    00156 /// and then get the feature with creator = kPmKeyLibCreator and featureNum =
    00157 /// kPmKeyLibFtrValAPIVersion.  Note that if the feature does not exist (and
    00158 /// the library successfully loaded), they can assume that it's version 1.0
    00159 /// of PmKeyLib.  If the feature does exist, then perform a check similar to
    00160 /// the following:
    00161 ///
    00162 /// @code
    00163 ///   if (sysGetLibAPIVersionMajor(pmKeyLibVersion) >= 3)
    00164 ///   {
    00165 ///     PmKeyAttrGet ( Version3Attribute, 0 , &value );
    00166 ///   }
    00167 ///    else
    00168 ///    {
    00169 ///      // PmKeyLib is version 2, use ONLY version 2 attributes for PmKeyAttrGet
    00170 ///     PmKeyAttrGet ( Version2Attribute, 0 , &value );
    00171 ///    }
    00172 /// @endcode
    00173 ///
    00174 /// @param refNum:  IN:  library reference number (returned by SysLibFind() / SysLibLoad() )
    00175 /// @param attr:    IN:  the attribute being retrieved @see PmKeyAttrEnum
    00176 /// @param flags:   IN:  depends on attr (currently implemented attributes only take 0 for this argument)
    00177 /// @param valueP:  OUT: cast depending on attr (refer to PmKeyAttrEnum for data type this argument should point to)
    00178 /// @retval Err error code. 0 if no error, hsErrNotSupported otherwise.
    00179 Err
    00180 PmKeyAttrGet (UInt16 refNum, UInt16 attr /*PmKeyAttrEnum*/, UInt32 flags, UInt32* valueP)
    00181             SYS_TRAP (kPmKeyLibTrapAttrGet);
    00182
    00183 /// Set palmOne specific attributes
    00184 ///
    00185 /// @param attr:    IN: the attribute being set
    00186 /// @param flags:   IN: depends on attr (currently implemented attributes only take 0 for this argument)
    00187 /// @param value:   IN: cast depending on attr (refert to PmKeyAttrEnum for data type this argument should point to)
    00188 /// @retval Err error code. 0 if no error, hsErrNotSupported otherwise.
    00189 Err
    00190 PmKeyAttrSet (UInt16 refNum, UInt16 attr /*PmKeyAttrEnum*/, UInt32 flags, UInt32 value)
    00191             SYS_TRAP (kPmKeyLibTrapAttrSet);
    00192
    00193 #ifdef __cplusplus
    00194 }
    00195 #endif
    00196
    00197 #endif  // __PMKEYLIB_H__

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