This chapter provides reference material for the Pen Input Manager API as declared in the header file PenInputMgr.h
. It discusses the following topics:
Pen Input Manager Constants
Pen Input Manager Launch Codes
Pen Input Manager Notifications
Pen Input Manager Functions and Macros
For more information on using the Pen Input Manager, see Chapter 2, "Working with the Dynamic Input Area."
Pen Input Manager Constants
Default Pinlet Constants
Purpose
Used in PINGetDefaultPinlet()
and PINSetDefaultPinlet()
to specify which default should be retrieved or set.
Declared In
PenInputMgr.h
Constants
-
#define pinDefaultPinletHWR 0
- The default handwriting recognition pinlet.
-
#define pinDefaultPinletKeyboard 1
- The default keyboard pinlet.
Input Area States
Purpose
The states that an input area can have.
Declared In
PenInputMgr.h
Constants
-
#define pinInputAreaOpen 0
- The dynamic input area is being displayed.
- The dynamic input area is in this state after the user taps the input trigger to open it. An application might also request that the dynamic input area be opened by calling
PINSetInputAreaState()
with this state. -
#define pinInputAreaClosed 1
- The dynamic input area is not being displayed.
- The dynamic input area is in this state after the user taps the input trigger to close it. An application also might request that the dynamic input area be closed by calling
PINSetInputAreaState()
with this state. -
#define pinInputAreaNone 2
- The input area is not dynamic, or there is no input area.
See Also
PINGetInputAreaState()
, PINSetInputAreaState()
Error Codes
Purpose
Error codes returned by Pen Input Manager.
Declared In
PenInputMgr.h
Constants
-
#define pinErrInvalidParam (pinsErrorClass | 0x01)
- An invalid parameter was specified.
-
#define pinErrNoSoftInputArea (pinsErrorClass | 0x00)
- This device does not have a dynamic input area.
-
#define pinErrPinletNotFound (pinsErrorClass | 0x02)
- The specified pinlet does not exist on this device.
Feature and Version Constants
Purpose
Specifies version and creator information.
Declared In
PenInputMgr.h
Constants
-
#define pinAPIVersion pinAPIVersion2_0
- The current version of the Pen Input Manager API.
-
#define pinAPIVersion1_0 0x01000000
- The first version of the Pen Input Manager API. This version of the API is used on Palm OS® 5.2 devices that have dynamic input areas.
-
#define pinAPIVersion1_1 0x01103000
- Version 1.1 of the Pen Input Manager API. This version is used on Palm OS Garnet version 5.3 devices that have dynamic input areas.
-
#define pinAPIVersion2_0 0x02003000
- Version 2.0 of the Pen Input Manager API, which is supported on Palm OS Cobalt version 6.0.
-
#define pinCreator 'pins'
- The creator code with which a system feature is defined specifying the current Pen Input Manager API version.
-
#define pinFtrAPIVersion 1
- The feature constant that stores the Pen Input Manager version number.
Input Area Flags Constants
Purpose
Flags set in the sysFtrNumInputAreaFlags
feature constant to specify the capabilities of a device's input area.
Declared In
PenInputMgr.h
Constants
-
#define grfFtrInputAreaFlagDynamic 0x00000001
- The device has a dynamic input area.
-
#define grfFtrInputAreaFlagLiveInk 0x00000002
- The device supports live ink.
-
#define grfFtrInputAreaFlagCollapsible 0x00000004
- The dynamic input area is collapsible. Some devices have an input area that is implement in software but that does not collapse.
-
#define grfFtrInputAreaFlagLandscape 0x00000008
- The device supports landscape mode.
-
#define grfFtrInputAreaFlagReversePortrait 0x00000010
- The device supports reverse portrait mode.
-
#define grfFtrInputAreaFlagReverseLandscape 0x00000020
- The device supports reverse landscape mode.
-
#define grfFtrInputAreaFlagLefthanded 0x00000040
- The device supports a special left-handed operation mode.
Comments
Palm OS Cobalt version 6.0 currently does not support landscape, reverse portrait, left-handed, or reverse landscape modes. These constants are defined now to support future releases.
Pinlet Input Modes
Purpose
Input modes a pinlet might have.
Declared In
PenInputMgr.h
Constants
-
#define pinInputModeNormal 0
- The default mode. For the ISO-Latin character encoding, the normal mode translates strokes into lowercase letters.
-
#define pinInputModeShift 1
- The next stroke will be translated into an uppercase character rather than the normal lowercase characters.
-
#define pinInputModeCapsLock 2
- All of the characters will be uppercase until the mode is set to something else.
-
#define pinInputModePunctuation 3
- The next stroke will be interpreted as a punctuation mark or symbol, and then the mode is reset to normal.
-
#define pinInputModeNumeric 4
- The stroke will be interpreted as a numeric character.
-
#define pinInputModeExtended 5
- The next stroke is a special symbol or part of the extended character set. The Graffiti® 2 handwriting recognition engine uses this mode for special symbols such as the trademark symbol.
-
#define pinInputModeHiragana 6
- A Japanese pinlet is active and creates Hiragana characters.
-
#define pinInputModeKatakana 7
- A Japanese pinlet is active and creates Katakana characters.
-
#define pinInputModeCustomBase 128
- The first value available for custom input modes specific to a pinlet.
-
#define pinInputModeCustomMax 255
- The last value available for custom input modes specific to a pinlet.
-
#define pinInputModeUnShift 256
- Cancels a shift state. This mode is sent in the UI Library's text field code to set the pinlet back to normal mode after an auto-shift. The pinlet may receive this state when it is already in normal mode.
Comments
The input mode is different from the FEP mode. The Graffiti 2 handwriting recognition engine does not use Hiragana or Katakana input modes; however, on some Japanese devices writing Graffiti 2 strokes generates Hiragana or Katakana characters, but that is dependent on the FEP mode, not the pinlet input mode. The same devices might have a Japanese keyboard pinlet that does use the Hiragana and Katakana input modes.
See Also
PINGetInputMode()
, PINSetInputMode()
Pinlet Information Constants
Purpose
Values you pass to PINGetPinletInfo()
to obtain information about a pinlet.
Declared In
PenInputMgr.h
Constants
-
#define pinPinletInfoName 0
- The pinlet's name as it appears in the status bar pop-up menu is returned in the
info
parameter as achar *
. -
#define pinPinletInfoStyle 1
- The kind of pinlet is returned in the
info
parameter as an integer constant. See "Pinlet Styles" for the exact constants that could be returned. -
#define pinPinletInfoFEPAssoc 2
- The creator ID of the FEP associated with this pinlet as an integer constant.
-
#define pinPinletInfoIcon 3
- System use only. Identifies the icon that displays in the status bar pop-up menu.
-
#define pinPinletInfoComponentName 4
- The name used internally for the pinlet is returned as a
char *
.
Pinlet Styles
Purpose
Declared In
PenInputMgr.h
Constants
-
#define pinPinletStyleHandwriting 0
- The pinlet is a handwriting recognition pinlet.
-
#define pinPinletStyleKeyboard 1
- The pinlet is a keyboard pinlet.
-
#define pinPinletStyleOther 2
- The pinlet is some other style of pinlet.
Virtual Character Flag
Purpose
Flag used to specify that a character is a virtual character.
Declared In
PenInputMgr.h
Constants
-
#define pinCharFlagVirtual 0x00000001
- Used to indicate a virtual character when a character is fed to the Pen Input Manager.
Pen Input Manager Launch Codes
sysAppLaunchCmdPinletLaunch
Purpose
Sent when a pinlet has become the active pinlet. The pinlet should respond by initializing itself.
Declared In
CmnLaunchCodes.h
Prototype
#define sysAppLaunchCmdPinletLaunch 83
Parameters
sysPinletLaunchCmdLoadProcPtrs
Purpose
Sent to a pinlet before the pinlet is displayed on the screen, requesting pointers to the functions used by the Pen Input Manager when interacting with this pinlet.
Declared In
CmnLaunchCodes.h
Prototype
#define sysPinletLaunchCmdLoadProcPtrs 85
Parameters
The launch code's parameter block pointer references an empty PinletAPIType
structure. Pinlets should fill in the contents of this structure upon receipt of this launch code.
Pen Input Manager Notifications
sysNotifyAltInputSystemDisabled
Purpose
Broadcast when an alternative input device has been disabled. For example, if the user detaches an external keyboard from the device, this notification is broadcast.
Declared In
NotifyMgr.h
Prototype
#define sysNotifyAltInputSystemDisabled 'aisd'
See Also
"Notification Manager" in Exploring Palm OS: Programming Basics, PINAltInputSystemEnabled()
sysNotifyAltInputSystemEnabled
Purpose
Broadcast when an alternative input device has been enabled. For example, if the user attaches an external keyboard to the device, this notification is broadcast.
Declared In
NotifyMgr.h
Prototype
#define sysNotifyAltInputSystemEnabled 'aise'
See Also
"Notification Manager" in Exploring Palm OS: Programming Basics, PINAltInputSystemEnabled()
Pen Input Manager Functions and Macros
PINAltInputSystemEnabled Function
Purpose
Indicates whether an alternative input system is currently available.
Declared In
PenInputMgr.h
Prototype
Boolean PINAltInputSystemEnabled ( void )
Parameters
Returns
true
if an alternative input system is attached and the dynamic input area is available, or false
if no alternative input system is attached or the dynamic input area is not available.
Comments
Applications call this function in rare situations to determine whether an alternative input system is currently available. An alternative input system is a text input device or program that is not controlled using the Pen Input Manager. Applications may want to close the dynamic input area if the user has an alternate way of entering data.
The primary example of an alternative input system is a detachable keyboard that is sold separately from the device, like the keyboards available for many Palm handhelds. The alternative input system is not required to be a keyboard. In the future, it may be some other sort of device such as a speech recognizer. The requirement for an input system to be considered an "alternative input system" is that it must be a way for the user to enter textual data. A jog dial is not an alternative input system.
See Also
sysNotifyAltInputSystemEnabled
, sysNotifyAltInputSystemDisabled
PINClearPinletState Function
Purpose
Tells the pinlet to clear its internal input state.
Declared In
PenInputMgr.h
Prototype
void PINClearPinletState ( void )
Parameters
Returns
Comments
Applications and pinlets rarely need to make this call. Palm OS makes this call when the internal state of the pinlet should be cleared, such as when the insertion point is moved to a different text field in the application. The internal state can include temporary shift states, intermediate character results, and so on.
For example, suppose the user has entered the first stroke required to make the "x" character. Now, instead of completing the character, the user taps a new text field. This should be interpreted as the cancellation of the current input mode, so PINClearPinletState()
is called.
PINCountPinlets Function
Purpose
Returns the number of pinlets known to the Pen Input Manager.
Declared In
PenInputMgr.h
Prototype
uint16_t PINCountPinlets ( void )
Parameters
Returns
The number of pinlets registered with the Pen Input Manager. Returns 0 if there are no registered pinlets.
Comments
In rare cases, a pinlet might be closely associated with a front-end processor (FEP). If the FEP is not active, the Pen Input Manager does not advertise the pinlet as being available in the status bar's menu.
This function, however, returns the count of all pinlets, whether they can be activated or not. Use the PINGetPinletInfo()
to determine if the pinlet relies on an inactive FEP.
See Also
PINGetCurrentPinletName Function
Purpose
Obtains the internal name of the current pinlet.
Declared In
PenInputMgr.h
Prototype
const char *PINGetCurrentPinletName ( void )
Parameters
Returns
An ASCII string containing the name of the current pinlet.
Comments
The current pinlet is the one in charge of displaying a user interface in the dynamic input area, receiving any pen strokes or pen taps made in that area, and translating those into textual input from the user.
This identifier is used in PINSwitchToPinlet()
to change the input system. Do not confuse this identifier with the external pinlet name displayed in the status bar.
PINGetDefaultPinlet Function
Purpose
Declared In
PenInputMgr.h
Prototype
uint16_t PINGetDefaultPinlet (
uint16_t defaultCode
)
Parameters
-
→ defaultCode
- One of the Default Pinlet Constants.
Returns
The index of the pinlet used as the specified default. You can pass this index to PINGetPinletInfo()
to obtain more information about the pinlet.
See Also
PINGetInputAreaState Function
Purpose
Returns the current state of the dynamic input area.
Declared In
PenInputMgr.h
Prototype
uint16_t PINGetInputAreaState ( void )
Parameters
Returns
One of the constants defined in the section "Input Area States."
See Also
PINGetInputMode Function
Purpose
Returns the current input mode of the pinlet.
Declared In
PenInputMgr.h
Prototype
uint16_t PINGetInputMode ( void )
Parameters
Returns
One of the input mode constants listed in the "Pinlet Input Modes" section.
Comments
Applications call this function to determine the current pinlet input mode. The pinlet input mode determines how the pinlet translates the next set of input from the user. The modes that a pinlet uses or accepts are up to the pinlet. Typically, in the default input mode, the pinlet translates user input into lowercase letters. Translation into any other type of character or symbol requires a different input mode.
The input mode should be considered a hint that the pinlet can use to coordinate with the application. The pinlet should have a visible indication of what its current input mode is.
See Also
PINSetInputMode()
, "Setting the Pinlet Input Mode"
PINGetPinletInfo Function
Purpose
Returns the requested information about the pinlet.
Declared In
PenInputMgr.h
Prototype
status_t PINGetPinletInfo ( uint16_t index, uint16_t infoSelector, uint32_t *info )
Parameters
-
→ index
- The index number of the pinlet about which you are requesting information. Valid values are from 0 to
PINCountPinlets()
– 1. -
→ infoSelector
- One of the values described in "Pinlet Information Constants."
-
← info
- Upon return, contains the information requested by the
infoSelector
parameter.
Returns
errNone
upon success or one of the following error codes:
-
pinErrInvalidParam
- An invalid
infoSelector
parameter was specified. -
pinErrPinletNotFound
- An invalid
index
parameter was specified.
PINSetDefaultPinlet Function
Purpose
Declared In
PenInputMgr.h
Prototype
status_t PINSetDefaultPinlet ( uint16_tdefaultCode
, uint16_tindex
)
Parameters
-
→ defaultCode
- One of the Default Pinlet Constants.
-
→ index
- The index number of the pinlet that you want to make the default. Valid values are from 0 to
PINCountPinlets()
– 1.
Returns
errNone
upon success or one of the following values:
-
pinErrInvalidParam
- The
defaultCode
parameter is invalid. -
pinErrPinletNotFound
- The index is out of range, or the internal pinlet list has not been created yet.
-
sysErrNoInit
- The Pen Input Manager has not been initialized.
Comments
This function allows you to set the default handwriting recognition pinlet and the default keyboard pinlet to something other than the system-supplied defaults. The default controls which pinlet is selected when the user taps a button on the system-supplied handwriting recognition and keyboard pinlets.
Before calling this function, you must obtain the index of the pinlet you want o make the default. To do so, you can iterate through the pinlet list from 0 to PINCountPinlets()
– 1, calling PINGetPinletInfo()
to obtain the pinlet's name or other identifying information.
See Also
PINSetInputAreaState Function
Purpose
Sets the state of the input area.
Declared In
PenInputMgr.h
Prototype
status_t PINSetInputAreaState ( uint16_t state )
Parameters
-
→ state
- The state to which the input area should be set. See "Input Area States" for a list of possible values.
Returns
errNone
upon success or one of the following error codes:
-
pinErrNoSoftInputArea
- There is no dynamic input area on this device.
-
pinErrInvalidParam
- You have entered an invalid
state
parameter.
Comments
Applications call this function to open or close the input area.
After opening or closing the input area, all on-screen transitional and update-based windows receive the winResizedEvent
.
See Also
PINGetInputAreaState()
, "Programmatically Opening and Closing the Input Area"
PINSetInputMode Function
Purpose
Declared In
PenInputMgr.h
Prototype
void PINSetInputMode ( uint16_t inputMode )
Parameters
-
→ inputMode
- The mode to which the pinlet should be set. This is one of the constants listed in the "Pinlet Input Modes" section.
Returns
Comments
Applications call this function to set the pinlet input mode.
The pinlet input mode determines how the pinlet translates the next set of input from the user. The modes that a pinlet uses or accepts are up to the pinlet. Typically, in the default input mode, the pinlet translates user input into lowercase letters. Translation into any other type of character or symbol requires a different input mode.
Not all input modes apply to all pinlets. If the application specifies a mode that the pinlet does not support, the pinlet chooses the closest equivalent that is supported, which could be normal mode.
See Also
PINGetInputMode()
, "Setting the Pinlet Input Mode"
PINShowReferenceDialog Function
Purpose
Displays the reference dialog for the current pinlet.
Declared In
PenInputMgr.h
Prototype
void PINShowReferenceDialog ( void )
Parameters
Returns
Comments
Applications call this function to show the reference or help dialog for the current pinlet.
PINSwitchToPinlet Function
Purpose
Changes the currently active pinlet.
Declared In
PenInputMgr.h
Prototype
status_t PINSwitchToPinlet ( const char *pinletName, uint16_t initialInputMode )
Parameters
-
→ pinletName
- The name of the pinlet that you want to make active. You can also specify one of the following strings instead:
-
"default:hwr"
- Make the default handwriting recognition pinlet active.
-
"default:keyboard"
- Make the default keyboard pinlet active.
-
→ initialInputMode
- The mode to which the pinlet should initially be set. See "Pinlet Input Modes."
Returns
errNone
upon success or one of the following error codes:
-
pinErrPinletNotFound
- There is no pinlet with the specified name.
-
pinErrNoSoftInputArea
- There is no dynamic input area on the device.
Comments
A user can choose a new pinlet by selecting it from a menu that pops up when the user holds the pen down on the input area icon in the status bar. The active pinlet itself might have a button that switches to another pinlet. For example, if the traditional silkscreen area were a pinlet, the on-screen keyboard would be another pinlet. The "abc" button in the silkscreen area switches from the handwriting pinlet to the on-screen keyboard pinlet.
If a pinlet is associated with a FEP, the pinlet will not be activated unless the FEP itself is active.
See Also
PINGetCurrentPinletName()
, "Changing the Active Pinlet"