API Guide Home (Online version only) |

# PmKeyLib.h File Reference

## Detailed Description

System Library that exports key-related APIs.

This library is based on key APIs from HsExtensions and was broken apart from HsExtensions so the APIs could be ported to other platforms.

Definition in file PmKeyLib.h.

Include dependency graph for PmKeyLib.h:

Go to the source code of this file.

## Functions

- Err PmKeyLibOpen (UInt16 refNum)
- Err PmKeyLibClose (UInt16 refNum)
- UInt16 PmKeyKeysPressed (UInt16 refNum, UInt16 count, const UInt16 keyCodes[], Boolean pressed[])
- Err PmKeyStop (UInt16 refNum, UInt16 keyCode)
- Boolean PmKeyEnableKey (UInt16 refNum, UInt16 keyCode, Boolean enabled)
- UInt16 PmKeyChrCodeToKeyCode (UInt16 refNum, UInt16 chrCode)
- void PmKeyKeyCodeToChrCode (UInt16 refNum, UInt16 keyCode, UInt16 modifiersIn, UInt16 *chrP, UInt16 *modifiersOutP)
- Boolean PmKeyEventIsFromKeyboard (UInt16 refNum, EventPtr eventP)
- Err PmKeyAttrGet (UInt16 refNum, UInt16 attr, UInt32 flags, UInt32 *valueP)
- Err PmKeyAttrSet (UInt16 refNum, UInt16 attr, UInt32 flags, UInt32 value)

## Function Documentation

Err PmKeyAttrGet | ( | UInt16 | refNum,
|  | UInt16 | attr,
|  | UInt32 | flags,
|  | UInt32 * | valueP |
| ) |  |  |

Get any palmOne specific key attributes that aren't appropriate to be accessed through a feature. (e.g. dynamic information about device state)

The following code sample retrieves the keyguard state (active or inactive) and disables it accordingly.

         UInt32 keyguard;
         PmKeyAttrGet (pmKeyAttrKeyboardLocked, 0, &keyguard);
         if (keyguard)
         {
             keyguard = 0;
             PmKeyAttrSet (pmKeyAttrKeyboardLocked, 0, &keyguard);
         }

Note that there are new attributes added for version 3 of the PmKeyAttrGet() function, so it is highly recommended that any application that calls this function does one or both of the following:

Check the return code. If its hsErrNotSupported, then the attribute that the function is looking for is NOT SUPPORTED using that particular version of the library!

- OR -

Check the version number of the PmKeyLib. To do this, load the PmKeyLib and then get the feature with creator = kPmKeyLibCreator and featureNum = kPmKeyLibFtrValAPIVersion. Note that if the feature does not exist (and the library successfully loaded), they can assume that it's version 1.0 of PmKeyLib. If the feature does exist, then perform a check similar to the following:

       if (sysGetLibAPIVersionMajor(pmKeyLibVersion) >= 3)
       {
        PmKeyAttrGet ( Version3Attribute, 0 , &value );
       }
        else
        {
          // PmKeyLib is version 2, use ONLY version 2 attributes for PmKeyAttrGet
        PmKeyAttrGet ( Version2Attribute, 0 , &value );
        }

Parameters:

  | refNum,: | IN: library reference number (returned by SysLibFind() / SysLibLoad() )
  | attr,: | IN: the attribute being retrieved

See also:
  PmKeyAttrEnum

Parameters:

  | flags,: | IN: depends on attr (currently implemented attributes only take 0 for this argument)
  | valueP,: | OUT: cast depending on attr (refer to PmKeyAttrEnum for data type this argument should point to)

Return values:

  | Err | error code. 0 if no error, hsErrNotSupported otherwise.

Err PmKeyAttrSet | ( | UInt16 | refNum,
|  | UInt16 | attr,
|  | UInt32 | flags,
|  | UInt32 | value |
| ) |  |  |

Set palmOne specific attributes

Parameters:

  | attr,: | IN: the attribute being set
  | flags,: | IN: depends on attr (currently implemented attributes only take 0 for this argument)
  | value,: | IN: cast depending on attr (refert to PmKeyAttrEnum for data type this argument should point to)

Return values:

  | Err | error code. 0 if no error, hsErrNotSupported otherwise.

UInt16 PmKeyChrCodeToKeyCode | ( | UInt16 | refNum,
|  | UInt16 | chrCode |
| ) |  |  |

Determine which key generates a certain character This is the complement of HALKeyKeyCodeToChrCode()

Parameters:

  | refNum,: | IN: library reference number (returned by SysLibFind() / SysLibLoad() )
  | chrCode,: | IN: the character to search for

Return values:

  | UInt16 | the keycode returned.

Boolean PmKeyEnableKey | ( | UInt16 | refNum,
|  | UInt16 | keyCode,
|  | Boolean | enabled |
| ) |  |  |

Enable/disable a key from generating key events. This extends HALKeySetMask().

Parameters:

  | refNum,: | IN: library reference number (returned by SysLibFind() / SysLibLoad() )
  | keyCode,: | IN: the key to enable/disable
  | enabled,: | IN: true to enable, false to disable

Return values:

  | Boolean | true if previously enabled

Boolean PmKeyEventIsFromKeyboard | ( | UInt16 | refNum,
|  | EventPtr | eventP |
| ) |  |  |

Determine if an event came from the physical keyboard

Parameters:

  | refNum,: | IN: library reference number (returned by SysLibFind() / SysLibLoad() )
  | eventP,: | IN: the event to check

Return values:

  | Boolean | true if the event came from the keyboard

void PmKeyKeyCodeToChrCode | ( | UInt16 | refNum,
|  | UInt16 | keyCode,
|  | UInt16 | modifiersIn,
|  | UInt16 * | chrP,
|  | UInt16 * | modifiersOutP |
| ) |  |  |

Translate a key code to the character generated by that key. Each key can generate several different characters, depending on which modifier keys are held when it is pressed. The caller needs to specify which modified state of the key should be used to select the appropriate character. This is the complement of HALKeyChrCodeToKeyCode().

Parameters:

  | refNum,: | IN: library reference number (returned by SysLibFind() / SysLibLoad() )
  | keyCode,: | IN: the key to lookup
  | modifiersIn,: | IN: Modifier mask indicating which character should be returned
  | chrP,: | OUT: The character produced by the key
  | modifiersOutP,: | OUT: The keyMask bits that must be set if a keyDown event is formed with the character. (Not including the bits set in modifiersIn)

Return values:

  | None. |

UInt16 PmKeyKeysPressed | ( | UInt16 | refNum,
|  | UInt16 | count,
|  | const UInt16 | keyCodes[],
|  | Boolean | pressed[] |
| ) |  |  |

Get the current state of specified keys

Parameters:

  | refNum,: | IN: library reference number (returned by SysLibFind() / SysLibLoad() )
  | count,: | IN: number of elements in keyCodes[] and pressed[]
  | keyCodes,: | IN: array of keyCodes to test
  | pressed,: | OUT: Each element is set to true if the key specified by the corresponding element in keyCodes[] is pressed, and set to false if it is not pressed. It is acceptable to pass NULL if only the return value is of interest.

Return values:

  | UInt16 | count of keys that are pressed.

Err PmKeyLibClose | ( | UInt16 | refNum | ) |

Standard close library function

Parameters:

  | refNum,: | IN: library reference number (returned by SysLibFind() / SysLibLoad() )

Return values:

  | Err | error code.

Err PmKeyLibOpen | ( | UInt16 | refNum | ) |

Standard open library function

Parameters:

  | refNum,: | IN: library reference number (returned by SysLibFind() / SysLibLoad() )

Return values:

  | Err | error code.

Err PmKeyStop | ( | UInt16 | refNum,
|  | UInt16 | keyCode |
| ) |  |  |

Stop a key from sending any more auto repeat events until it is released.

Parameters:

  | refNum,: | IN: library reference number (returned by SysLibFind() / SysLibLoad() )
  | keyCode,: | IN: key to stop

Return values:

  | Err | errNone if the keyCode is the last key pressed and it is still held.

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