API Guide Home
(Online version only)

Header Files » Incs » 68k » libraries » pmkeylib

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

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