Tech Note XX: Using the NSBPinMgr Shared Library

June 8, 2004

 

Copyright 2004 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).

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".

Function Index and Quick Reference:


Version Information
    Version                   version = Version()
    CompileInfo               compileDateTime = CompileInfo()
    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

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

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