Tech Note 31: Hiding the Keyboard: The PinLib Shared Library

April 17, 2006

 

Copyright 2006 Ron Glowka


Contents:

    Introduction
    Function Index and Quick Reference
    Function Reference

Introduction:

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

Function Index and Quick Reference:


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)

NSBPinMgr Function Reference:

Version Information

The version information functions provide information about the version of the NSBPinMgr Shared Library.

Version

	version = NSBPinMgr.Version()
Returns the version number of the NSBPinMgr Shared Library.
Returns:
	version as Double
Example:
	Dim version as Double

	version = NPM.Version()

CompileInfo

	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()

PINMgrAPIVersion

	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()

PINMgrAPIMajorMinor

	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

RegisterNotifyEvents

	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

WinGetDisplayExtent

	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

WinSetDisplayExtent

	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

FrmGetDIAPolicy

	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()

FrmSetDIAPolicy

	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

PINGetDIAState

	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()

PINSetDIAState

	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

PINGetInputTriggerState

	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()

PINSetInputTriggerState

	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

SysGetOrientation

	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()

SysSetOrientation

	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)

SysGetOrientationTriggerState

	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()

SysSetOrientationTriggerState

	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)