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 Functions
- Control Bar Functions
- Display Orientation Functions
Pen Input Manager Constants
Input Area States
Table 46.1 lists constants that define the states that the input area can have. An application can obtain the input area's current state with PINGetInputAreaState
and set it with PINSetInputAreaState
.
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 |
||
The input area is not dynamic, or there is no input area. Do not pass this value to |
||
Pass this value to |
Input Trigger States
Table 46.2 lists constants that specify the state of the input area icon in the status bar. An application can obtain this state with PINGetInputTriggerState
and set it with PINSetInputTriggerState
.
Table 46.2 Input trigger states
Orientation States
Table 46.3 lists constants that specify the display orientation. An application can obtain this state with SysGetOrientation
and set it with SysSetOrientation
.
Table 46.3 Orientation state constants
Orientation Trigger States
Table 46.4 lists constants that specify the state of the orientation icon in the status bar (the icon that allows the user to change the display orientation). An application can obtain this state with SysGetOrientationTriggerState
and set it with SysSetOrientationTriggerState
.
Table 46.4 Orientation trigger state constants
Pen Input Manager Functions
PINGetInputAreaState Function
Purpose
Returns the current state of the dynamic input area.
Declared In
PenInputMgr.h
Prototype
UInt16 PINGetInputAreaState ( void )
Parameters
Returns
One of the constants defined in the section "Input Area States."
Compatibility
Implemented only if the Pen Input Manager Feature Set is present.
See Also
PINSetInputAreaState
, PINGetInputTriggerState
PINGetInputTriggerState Function
Purpose
Returns the status of the input area icon in the status bar.
Prototype
UInt16 PINGetInputTriggerState ( void )
Parameters
Returns
One of the constants defined in the section "Input Trigger States."
Compatibility
Implemented only if the Pen Input Manager Feature Set is present.
See Also
PINSetInputAreaState Function
Purpose
Sets the state of the input area.
Declared In
PenInputMgr.h
Prototype
Err PINSetInputAreaState ( UInt16 state )
Parameters
-
→
state
- The state to which the input area should be set. See "Input Area States" for a list of possible values.
Returns
Returns one of the following error codes:
-
errNone
- Success.
-
pinErrNoSoftInputArea
- There is no dynamic input area on this device.
-
pinErrInvalidParam
- You have entered an invalid
state
parameter.
Comments
After opening or closing the input area, this function broadcasts the notification sysNotifyDisplayResizedEvent
(and in Pen Input Manager version 1.1, posts the event winDisplayChangedEvent
to the event queue). Applications register for this notification or respond to the event if they wish to resize themselves.
Compatibility
Implemented only if the Pen Input Manager Feature Set is present.
See Also
PINGetInputAreaState
, PINSetInputTriggerState
PINSetInputTriggerState Function
Purpose
Sets the state of the input area icon in the status bar.
Declared In
PenInputMgr.h
Prototype
Err PINSetInputTriggerState ( UInt16 state )
Parameters
-
→
state
- The state to which the input trigger should be set. See "Input Trigger States" for a list of possible values.
Returns
Returns one of the following error codes:
-
errNone
- Success.
-
pinErrNoSoftInputArea
- There is no dynamic input area on this device.
-
pinErrInvalidParam
- You have specified an invalid
state
parameter.
Comments
Applications or Palm OS call this function to enable the input area icon in the status bar. Normally, this trigger is enabled and should remain enabled, allowing the user the choice of displaying the input area or not. Legacy applications might disable the trigger on some devices.
Compatibility
Implemented only if the Pen Input Manager Feature Set is present.
See Also
PINGetInputTriggerState
, PINSetInputAreaState
Control Bar Functions
This section lists other functions that are implemented as part of the Pen Input Manager in Palm OS Garnet.
StatBarGetIcon Function
Purpose
Obtain the identifier for the status bar icon currently displayed in a specified slot.
Declared In
PenInputMgr.h
Prototype
Boolean StatBarGetIcon ( UInt16slotID
, UInt16 *iconIDPtr
)
Parameters
-
→ slotID
- Unique identifier of the status bar slot containing the desired icon.
-
← iconIDPtr
- The ID of the bitmap image displayed in the specified slot. This identifier represents one of the bitmap images in the device resources database.
Returns
true
if the slot was found, false
if it is not one of the slots currently being kept track of.
StatBarSetIcon Function
Purpose
Changes the icon state of a specified status bar icon.
Declared In
PenInputMgr.h
Prototype
Err StatBarSetIcon ( UInt16 slotID, UInt16 iconID )
Parameters
-
→ slotID
- Unique identifier of the status bar slot containing the icon to be changed.
-
→ iconID
- Identifier of one of the bitmap images in the device resources database. The specified image will be displayed in the slot indicated by
slotID
.
Returns
Returns errNone
if the status bar icon was updated successfully, or an error otherwise. The most common error returned from this function arises when you attempt to add an icon to a status bar that already contains the maximum number of icons.
StatGetAttribute Function
Purpose
Returns the control bar state.
Declared In
PenInputMgr.h
Prototype
Err StatGetAttribute ( UInt16 selector, UInt32 *dataP )
Parameters
-
→
selector
- Attribute selector, as described in the Comments section below.
-
→
dataP
- Pointer to the returned data, as described in the Comments section below.
Returns
Returns one of the following error codes:
Comments
The following values are supported for the selector parameter:
-
statAttrBarVisible
- Checks if the control bar is visible. The return data is set to 0 if the control bar is hidden, or is set to 1 if the control bar is visible or the input area is open.
-
statAttrDimension
- Gets the control bar bounds. The return data is two
UInt16
values, where the first is the width of the control bar and the second is the height. The dimensions use the active coordinate system.
Compatibility
Implemented only if the Pen Input Manager Feature Set is present and returns version 1.1.
See Also
StatHide Function
Purpose
Declared In
PenInputMgr.h
Prototype
Err StatHide ( void )
Returns
Returns one of the following error codes:
-
errNone
- Success.
-
sysErrNotAllowed
- The device does not support a dynamic input area.
-
sysErrInputWindowOpen
- The input area is open (so the control bar is not currently visible).
Comments
The input area must be closed before you call this function.
This function can be called by applications that want to draw to the entire display area and thus need to hide the control bar. However, hiding the control bar is discouraged since it prevents users from exiting to the Launcher or opening the input area via buttons that appear on the control bar. If the control bar is hidden, you must provide a mechanism for the user to exit the application.
Compatibility
Implemented only if the Pen Input Manager Feature Set is present and returns version 1.1.
See Also
StatShow Function
Purpose
Declared In
PenInputMgr.h
Prototype
Err StatShow ( void )
Returns
Returns one of the following error codes:
Comments
If the input area is open when this function is called, it has no effect and errNone
is returned.
Compatibility
Implemented only if the Pen Input Manager Feature Set is present and returns version 1.1.
See Also
Display Orientation Functions
SysGetOrientation Function
Purpose
Returns the display orientation.
Declared In
SystemMgr.h
Prototype
UInt16 SysGetOrientation ( void )
Parameters
Returns
Returns one of the constants listed in "Orientation States."
Comments
Not all devices support changing the display orientation. For devices that don't support changing the display orientation, this function always returns sysOrientationPortrait
.
Compatibility
Implemented only if Pen Input Manager Feature Set is present and returns version 1.1. Some licensees may have implemented this function in an earlier OS version. To check if this function is implemented in an earlier OS version, use this test:
if (SysGlueTrapExists(pinSysGetOrientation)) { // SysGetOrientation exists }
See Also
SysGetOrientationTriggerState Function
Purpose
Returns the display orientation trigger state.
Declared In
SystemMgr.h
Prototype
UInt16 SysGetOrientationTriggerState ( void )
Returns
Returns one of the constants listed in "Orientation Trigger States."
Comments
Not all devices support changing the display orientation. For devices that don't support changing the display orientation, this function always returns sysOrientationTriggerDisabled
.
Compatibility
Implemented only if the Pen Input Manager Feature Set is present and returns version 1.1. Some licensees may have implemented this function in an earlier OS version. To check if this function is implemented in an earlier OS version, use this test:
if (SysGlueTrapExists (pinSysGetOrientationTriggerState)) { // SysGetOrientationTriggerState exists }
See Also
SysSetOrientation Function
Purpose
Declared In
SystemMgr.h
Prototype
Err SysSetOrientation ( UInt16 orientation )
Parameters
-
→ orientation
- The orientation to which the display should be set. See "Orientation States" for a list of possible values.
Returns
Returns one of the following error codes:
Comments
Not all devices support changing the display orientation.
Compatibility
Implemented only if the Pen Input Manager Feature Set is present and returns version 1.1. Some licensees may have implemented this function in an earlier OS version. To check if this function is implemented in an earlier OS version, use this test:
if (SysGlueTrapExists(pinSysSetOrientation)) { // SysSetOrientation exists }
See Also
SysSetOrientationTriggerState Function
Purpose
Sets the display orientation trigger state.
Declared In
SystemMgr.h
Prototype
Err SysSetOrientationTriggerState ( UInt16 triggerState )
Parameters
-
→ triggerState
- One of the constants listed in "Orientation Trigger States".
Returns
Returns one of the following error codes:
Comments
Not all devices support changing the display orientation.
Compatibility
Implemented only if the Pen Input Manager Feature Set is present and returns version 1.1. Some licensees may have implemented this function in an earlier OS version. To check if this function is implemented in an earlier OS version, use this test:
if (SysGlueTrapExists(pinSysSetOrientationTriggerState)) { // SysSetOrientationTriggerState exists }