Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

10    Pen Input Manager

Input Services

Exploring Palm OS®

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 ^TOP^

Default Pinlet Constants ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 a char *.
#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 ^TOP^

Purpose

Specifies the pinlet style.

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 ^TOP^

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 ^TOP^

sysAppLaunchCmdPinletLaunch ^TOP^

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

None.

sysPinletLaunchCmdLoadProcPtrs ^TOP^

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 ^TOP^

sysNotifyAltInputSystemDisabled ^TOP^

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 ^TOP^

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 ^TOP^

PINAltInputSystemEnabled Function ^TOP^

Purpose

Indicates whether an alternative input system is currently available.

Declared In

PenInputMgr.h

Prototype

Boolean PINAltInputSystemEnabled (
   void
)

Parameters

None.

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 ^TOP^

Purpose

Tells the pinlet to clear its internal input state.

Declared In

PenInputMgr.h

Prototype

void PINClearPinletState (
   void
)

Parameters

None.

Returns

Nothing.

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 ^TOP^

Purpose

Returns the number of pinlets known to the Pen Input Manager.

Declared In

PenInputMgr.h

Prototype

uint16_t PINCountPinlets (
   void
)

Parameters

None.

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

PINGetPinletInfo()

PINGetCurrentPinletName Function ^TOP^

Purpose

Obtains the internal name of the current pinlet.

Declared In

PenInputMgr.h

Prototype

const char *PINGetCurrentPinletName (
   void
)

Parameters

None.

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 ^TOP^

Purpose

Returns a default pinlet.

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

PINSetDefaultPinlet()

PINGetInputAreaState Function ^TOP^

Purpose

Returns the current state of the dynamic input area.

Declared In

PenInputMgr.h

Prototype

uint16_t PINGetInputAreaState (
   void
)

Parameters

None.

Returns

One of the constants defined in the section "Input Area States."

See Also

PINSetInputAreaState()

PINGetInputMode Function ^TOP^

Purpose

Returns the current input mode of the pinlet.

Declared In

PenInputMgr.h

Prototype

uint16_t PINGetInputMode (
   void
)

Parameters

None.

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 ^TOP^

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 ^TOP^

Purpose

Sets a default pinlet.

Declared In

PenInputMgr.h

Prototype

status_t PINSetDefaultPinlet (
   uint16_t defaultCode,
   uint16_t index
)

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

PINGetDefaultPinlet()

PINSetInputAreaState Function ^TOP^

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 ^TOP^

Purpose

Sets the pinlet's input mode.

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

Nothing.

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 ^TOP^

Purpose

Displays the reference dialog for the current pinlet.

Declared In

PenInputMgr.h

Prototype

void PINShowReferenceDialog (
   void
)

Parameters

None.

Returns

Nothing.

Comments

Applications call this function to show the reference or help dialog for the current pinlet.

PINSwitchToPinlet Function ^TOP^

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"