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

46    Pen Input Manager Reference

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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

Input Area States ^TOP^

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.

Table 46.1  Input area states

Constant

Value

Description

pinInputAreaOpen

0

The dynamic input area is being displayed.

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.

pinInputAreaNone

2

The input area is not dynamic, or there is no input area. Do not pass this value to PINSetInputAreaState.

pinInputAreaUser

5

Pass this value to PINSetInputAreaState to tell the Pen Input Manager to activate the last user-selected input area state.

Input Trigger States ^TOP^

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

Constant

Value

Description

pinInputTriggerEnabled

0

The input trigger is enabled, meaning that the user is allowed to open and close the dynamic input area.

pinInputTriggerDisabled

1

The input trigger is disabled, meaning that the user is not allowed to close the dynamic input area.

pinInputTriggerNone

2

There is no dynamic input area.

Orientation States ^TOP^

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

Constant

Value

Description

sysOrientationUser

0

Pass this value to SysSetOrientation to tell the system to activate the last user-selected orientation.

sysOrientationPortrait

1

The display is in portrait orientation.

sysOrientationLandscape

2

The display is in landscape orientation.

sysOrientationReversePortrait

3

The display is in reverse portrait orientation (upside-down from the normal portrait orientation).

sysOrientationReverseLandscape

4

The display is in reverse landscape orientation (upside-down from the normal landscape orientation).

Orientation Trigger States ^TOP^

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

Constant

Value

Description

sysOrientationTriggerDisabled

0

The orientation trigger is disabled, meaning that the user is not allowed to change the display orientation.

sysOrientationTriggerEnabled

1

The orientation trigger is enabled, meaning that the user is allowed to change the display orientation.

Pen Input Manager Functions ^TOP^

PINGetInputAreaState Function ^TOP^

Purpose

Returns the current state of the dynamic input area.

Declared In

PenInputMgr.h

Prototype

UInt16 PINGetInputAreaState (
   void
)

Parameters

None.

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

Purpose

Returns the status of the input area icon in the status bar.

Prototype

UInt16 PINGetInputTriggerState (
   void
)

Parameters

None.

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

PINGetInputAreaState

PINSetInputAreaState Function ^TOP^

Purpose

Sets the state of the input area.

Declared In

PenInputMgr.h

Prototype

Err PINSetInputAreaState (
   UInt16state
)

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

Purpose

Sets the state of the input area icon in the status bar.

Declared In

PenInputMgr.h

Prototype

Err PINSetInputTriggerState (
   UInt16state
)

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

This section lists other functions that are implemented as part of the Pen Input Manager in Palm OS Garnet.

StatBarGetIcon Function ^TOP^

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

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

Purpose

Returns the control bar state.

Declared In

PenInputMgr.h

Prototype

Err StatGetAttribute (
   UInt16selector,
   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:

errNone
Success.
sysErrParamErr
You have specified an invalid selector parameter.

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

StatHide Function ^TOP^

Purpose

Hides the control bar.

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

StatGetAttribute, StatShow

StatShow Function ^TOP^

Purpose

Shows the control bar.

Declared In

PenInputMgr.h

Prototype

Err StatShow (
   void
)

Returns

Returns one of the following error codes:

errNone
Success.
sysErrNotAllowed
The device does not support a dynamic input area.

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

StatGetAttribute, StatHide

Display Orientation Functions ^TOP^

SysGetOrientation Function ^TOP^

Purpose

Returns the display orientation.

Declared In

SystemMgr.h

Prototype

UInt16 SysGetOrientation (
   void
)

Parameters

None.

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

SysSetOrientation

SysGetOrientationTriggerState Function ^TOP^

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

SysSetOrientationTriggerState

SysSetOrientation Function ^TOP^

Purpose

Sets the display orientation.

Declared In

SystemMgr.h

Prototype

Err SysSetOrientation (
   UInt16orientation
)

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:

errNone
Success.
sysErrNotAllowed
Setting the display orientation is not supported on the device.

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

SysGetOrientation

SysSetOrientationTriggerState Function ^TOP^

Purpose

Sets the display orientation trigger state.

Declared In

SystemMgr.h

Prototype

Err SysSetOrientationTriggerState (
   UInt16triggerState
)

Parameters

triggerState
One of the constants listed in "Orientation Trigger States".

Returns

Returns one of the following error codes:

errNone
Success.
sysErrNotAllowed
Setting the display orientation is not supported on the device.

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 
} 

See Also

SysGetOrientationTriggerState