Tech Note 31: Hiding the Keyboard: The PinLib Shared Library
April 17, 2006
Copyright 2006 Ron Glowka
|
|
Tech Note 31: Hiding the Keyboard: The PinLib Shared Library April 17, 2006
Copyright 2006 Ron Glowka |
Introduction
Function Index and Quick Reference
Function Reference
This library provides a wrapper for the PIN Manager (Pen Input Manager) for manipulating the the Dynamic Input/virtual graffiti Area (DIA). It works on devices that have a soft Grafitti area and use PalmSource's standard PIN manager. Not all functions in this library work properly on Tungsten T3 devices due to different features in ROM than later devices. Test carefully on the T3.
In order to use the NSBPinMgr Shared Library, the library must be
loaded using the NSBasic LoadLibrary statement. This statement should
be located in the program's Startup code so that the functions
will be available throughout the program. The LoadLibrary statement
has an optional second parameter to allow you to specify an abbreviated
reference name for the library's functions. The examples in this
document use "NPM" for this reference name. Example:
Program's Startup code: Sub main() LoadLibrary "NSBPinMgr", "NPM" End Sub
Also, in order to use the NSBPinMgr Shared Library, the NSBPinMgr.INF file must be present in your "nsbasic\lib" directory and the NSBPinMgr.prc file must be downloaded to your device.
Please be sure that your function return variables are dimensioned as the correct variable type. This library will return variable types of "Integer", "Double", or "String".
Using this statement before the first use of a WInSetDisplayExtent call prevents error messages:
NPM.FrmSetDIAPolicy 0
Version Information
Version version = Version()
CompileInfo compileDateTime = CompileInfo()
PINMgrAPIVersion version = PINMgrAPIVersion()
PINMgrAPIMajorMinor PINMgrAPIMajorMinor major, minor
RegisterNotifyEvents RegisterNotifyEvents displayResized, DIAOpened, DIAClosed
WinGetDisplayExtent WinGetDisplayExtent x, y
WinSetDisplayExtent WinSetDisplayExtent size
FrmGetDIAPolicy value = FrmGetDIAPolicy()
FrmSetDIAPolicy FrmSetDIAPolicy value
PINGetDIAState value = PINGetDIAState()
PINSetDIAState PINSetDIAState value
PINGetInputTriggerState value = PINGetInputTriggerState()
PINSetInputTriggerState PINSetInputTriggerState value
SysGetOrientation value = SysGetOrientation()
SysSetOrientation status = SysSetOrientation(value)
SysGetOrientationTriggerState value = SysGetOrientationTriggerState()
SysSetOrientationTriggerState status = SysSetOrientationTriggerState(value)
version = NSBPinMgr.Version()
Returns the version number of the NSBPinMgr Shared Library.
Returns:
version as Double
Example:
Dim version as Double version = NPM.Version()
compileDateTime = NSBPinMgr.CompileInfo()
Returns the date and time that the NSBPinMgr was compiled.
Returns:
compileDateTime as String
Example:
Dim compileDateTime as String compileDateTime = NPM.CompileInfo()
version = NSBPinMgr.PINMgrAPIVersion()
Returns the version number of the Pen Input Manager API.
Returns:
version as String version number - -1.0 if the Pen Input Manager is unavailable.
Example:
Dim version as String version = NPM.PINMgrAPIVersion()
NSBPinMgr.PINMgrAPIMajorMinor major, minor
Returns the version number of the Pen Input Manager API as two integers, major and minor.
Parameters:
major as Integer (output parameter) major version number - -1 if the Pen Input Manager is unavailable. minor as Integer (output parameter) minor version number - -1 if the Pen Input Manager is unavailable.
Example:
Dim major as Integer Dim minor as Integer NPM.PINMgrAPIMajorMinor major, minor
NSBPinMgr.RegisterNotifyEvents displayResized, DIAOpened, DIAClosed
Register with the Notification Manager to be notified when the sysNotifyDisplayResizedEvent notification occurs. When it does, an event for the specific type of notification will be generated. The parameters for this function specify the event number to generate. A value of 0 disables event notification for specific notification type. Parameter values should typically be in the custom event number range (24576 to 32767). These events can be "caught" with the NSBasic GetEventType() function.
Parameters:
displayResized as Integer (input parameter) event number for sysNotifyDisplayResizedEvent - The display has been resized. DIAOpened as Integer (input parameter) event number when the DIA has been opened DIAClosed as Integer (input parameter) event number when the DIA has been closed
Example:
Sub Form1223_After() 'Register to have the following events generated: ' event number 30001 - display resized ' event number 30002 - DIA has been opened ' event number 30003 - DIA has been closed NPM.RegisterNotifyEvents 30001, 30002, 30003 End Sub Sub Form1239_Event() Dim event as Integer event = GetEventType() Select Case event Case 30003 Redraw End Select End Sub
NSBPinMgr.WinGetDisplayExtent x, y
Return the current width and height of the display.
Parameters:
x as Integer (output parameter) y as Integer (output parameter)
Example:
Dim x as Integer Dim y as Integer NPM.WinGetDisplayExtent x, y
NSBPinMgr.WinSetDisplayExtent size
Sets the display width and height to either normal or large. If the size is large, the form's Dynamic Input Area (DIA) Policy, Input Trigger, and Dynamic Input Area values will be set to custom, enabled, and closed respectively.
Parameter:
size as Integer (input parameter) 0 = normal - 160 pixels wide x 160 pixels high 1 = large - 160 pixels wide x 225 pixels high
Example:
Dim size as Integer NPM.WinSetDisplayExtent size
value = NSBPinMgr.FrmGetDIAPolicy()
Returns the form's current Dynamic Input Area (DIA) Policy. The DIA Policy controls whether the graffiti input area may be collapsed or not.
Returns:
value as Integer 0 - frmDIAPolicyStayOpen. The graffiti input area is always open. It cannot be collapsed. 1 - frmDIAPolicyCustom. The graffiti input area is collapsable. -1 - error. The Pen Input Manager is not present on device.
Example:
Dim value as Integer value = NPM.FrmGetDIAPolicy()
NSBPinMgr.FrmSetDIAPolicy value
Sets the form's Dynamic Input Area (DIA) Policy. The DIA Policy controls whether the graffiti input area may be collapsed or not.
Parameter:
value as Integer (input parameter) 0 - frmDIAPolicyStayOpen. The graffiti input area is always open. It cannot be collapsed. 1 - frmDIAPolicyCustom. The graffiti input area is collapsable.
Example:
Dim value as Integer NPM.FrmSetDIAPolicy value
value = NSBPinMgr.PINGetDIAState()
Returns the current Dynamic Input Area (DIA) state.
Returns:
value as Integer 0 - pinInputAreaOpen. The Dynamic Input Area is displayed. 1 - pinInputAreaClosed. The Dynamic Input Area is not being displayed. 2 - pinInputAreaNone. There is no Dynamic Input Area. -1 - error. The Pen Input Manager is not present on device.
Example:
Dim value as Integer value = NPM.PINGetDIAState()
NSBPinMgr.PINSetDIAState value
Sets the current Dynamic Input Area (DIA) state.
Parameter:
value as Integer (input parameter) 0 - pinInputAreaOpen. The Dynamic Input Area will be displayed. 1 - pinInputAreaClosed. The Dynamic Input Area will not be displayed. 2 - pinInputAreaNone. There is no Dynamic Input Area.
Example:
Dim value as Integer NPM.PINSetDIAState value
value = NSBPinMgr.PINGetInputTriggerState()
Returns the current Input Trigger state.
Returns:
value as Integer 0 - pinInputTriggerEnabled. The status bar icon is enabled, meaning that the user is allowed to open and close the Dynamic Input Area. 1 - pinInputTriggerDisabled. The status bar icon is disabled, meaning that the user is not allowed to open and close the Dynamic Input Area. 2 - pinInputTriggerNone. There is no Dynamic Input Area. -1 - error. The Pen Input Manager is not present on device.
Example:
Dim value as Integer value = NPM.PINGetInputTriggerState()
NSBPinMgr.PINSetInputTriggerState value
Sets the current Input Trigger state.
Parameter:
value as Integer (input parameter) 0 - pinInputTriggerEnabled. Enable the status bar icon, meaning that the user is allowed to open and close the Dynamic Input Area. 1 - pinInputTriggerDisabled. Disable the status bar icon, meaning that the user is not allowed to open and close the Dynamic Input Area. 2 - pinInputTriggerNone. There is no Dynamic Input Area.
Example:
Dim value as Integer NPM.PINSetInputTriggerState value
value = NSBPinMgr.SysGetOrientation()
Returns the current display orientation.
Returns:
value as Integer 0 - sysOrientationUser. Pass this value to SysSetOrientation to tell the system to activate the last userselected orientation. 1 - sysOrientationPortrait. The display is in portrait orientation. 2 - sysOrientationLandscape. The display is in landscape orientation. orientation (upside-down from the normal portrait orientation). 4 - sysOrientationReverseLandscape. The display is in reverse landscape orientation (upsidedown from the normal landscape orientation). -1 - error. Orientation changes are not supported on this device.
Example:
Dim value as Integer value = NPM.SysGetOrientation()
status = NSBPinMgr.SysSetOrientation(value)
Sets the current display orientation.
Parameter:
value as Integer (input parameter) 0 - sysOrientationUser. Pass this value to SysSetOrientation to tell the system to activate the last userselected orientation. 1 - sysOrientationPortrait. The display is in portrait orientation. 2 - sysOrientationLandscape. The display is in landscape orientation. 3 - sysOrientationReversePortrait. The display is in reverse portrait orientation (upside-down from the normal portrait orientation). 4 - sysOrientationReverseLandscape. The display is in reverse landscape orientation (upsidedown from the normal landscape orientation).
Returns:
status as Integer 0 - success. -1 - error. Changing orientation is not supported on this device.
Example:
Dim status as Integer Dim value as Integer status = NPM.SysSetOrientation(value)
value = NSBPinMgr.SysGetOrientationTriggerState()
Returns the current Input Trigger state.
Returns:
value as Integer 0 - sysOrientationTriggerDisabled. The orientation trigger is disabled, meaning that the user is not allowed to change the display orientation. 1 - sysOrientationTriggerEnabled. The orientation trigger is enabled, meaning that the user is allowed to change the display orientation. -1 - error. Changing orientation is not supported on this device.
Example:
Dim value as Integer value = NPM.SysGetOrientationTriggerState()
status = NSBPinMgr.SysSetOrientationTriggerState(value)
Sets the current Input Trigger state.
Parameter:
value as Integer (input parameter) 0 - sysOrientationTriggerDisabled. The orientation trigger is disabled, meaning that the user is not allowed to change the display orientation. 1 - sysOrientationTriggerEnabled. The orientation trigger is enabled, meaning that the user is allowed to change the display orientation.
Returns:
status as Integer -1 - error. Changing orientation is not supported on this device.
Example:
Dim status as Integer Dim value as Integer status = NPM.SysSetOrientationTriggerState(value)