|
|
Tech Note XX: Using the NSBPinMgr Shared Library June 8, 2004
Copyright 2004 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).
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()
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)