Tech Note 11: Using Handera Devices

Tech Note 11: Using HandEra Devices

Jun 12, 2001

© NSB Corporation. All rights reserved.

(Special thanks to Ron Glowka)

Starting with NS Basic/Palm 1.12, the NSBHandEra Shared Library provides support for the HandEra's high resolution screen, virtual silkscreen, and audio features. This document describes the functions in this library. The HandEra 330 Programmer's Companion and Programmer's Reference Manual should also be referenced in order to fully understand the purpose and use of this shared library's functions. These manuals are part of the HandEra SDK which can be downloaded from:

http://www.Handera.com/support/developsupport.asp

The NSBHandEra Shared Library provides a subset of the HandEra SDK functions. For the most part, the functions of this library are simply "wrappers" that allow the HandEra API functions to be called from NSBasic. The functions that have not yet been implemented, include the functions which support the customization of the HandEra's virtual silkscreen bitmaps and the audio record and play features.

To test your programs, it is not necessary to have an actual HandEra 330. Most of the functions (except for some the audio ones) will work using a specially modified version of POSE that is available from HandEra, along with the HandEra ROM image. Both files are available from the HandEra Developer Support page.

Using the HandEra functions in your program

1. The HandEra.INF file is put into \NSBasic\Lib by the NS Basic Palm installer. HandEra.prc is put into \NSBasic\download and should be downloaded to your device or POSE.

2. 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 "NSBH" for this reference name. Example:

Program's Startup code:

Sub main() 
	LoadLibrary "NSBHandera", "NSBH" 
End Sub

3. If your application is using High-Res mode, turn on the checkbox in Build...Options.

4. If you have High-res icons, use PalmRI to add them to your .prc file after you compile it. Instructions on using PalmRI are contained in Tech Note 04. PalmRI is located in \program files\nsbasic.

The new ResType and Res IDs you need to create are as follows:

ResType Res ID Notes

2000 tAIB large Icons: 32x32 images

2001 tAIB small icons: 24x14 image

2002 tAIB Inverse large icons: 32x32

5. Additional HandEra Events: The HandEra 330 has 4 additional button functions: the Jog dial and the Aux button. According to the UI guidelines, pushing in the Jog button is the same as hitting the return key on keyboard. The Aux button is the escape key. It is used to exit the current form.

In addition, the HandEra sends an event to your program if the arrows are used to mimimize or maximize the Silkscreen.

HandEra Button GetEventType() GetKey()

Aux 1 27 (escape)

Jog Right 1 13 (return)

Jog Up 5 12

Jog Down 5 3

Silkscreen Changed 24574

NSBHandEra Shared Library Function Reference

Except for the Version() function, all the parameter and return data types are either "Integer" or "String". A return value of -1 indicates that the device is not a HandEra device. All functions check to ensure that the HandEra features are available before a HandEra API is used. This should allow you to use the NSBHandEra Shared Library on any device - even if it is not a HandEra device. Of course, the library function will not perform as desired, but it should not crash.

Version

VersionNbr = NSBHandEra.Version()

Returns the version number of the NSBHandEra Shared Library.

Parameters: None

Returns: VersionNbr as Double

Example

	Dim VersionNbr as Double
	VersionNbr = NSBH.Version()

CompileInfo

NSBHandEra.CompileInfo CompileDate, CompileTime

Returns the date and time that the NSBHandEra Shared Library was compiled. The CompileDate and CompileTime string variables must be initialized prior to calling CompileInfo.

Parameters: CompileDate as String CompileTime as String

Returns: None

Example

	Dim CompileDate as String
	Dim CompileTime as String

	CompileDate = "mmm dd yyyy"	'11 characters
	CompileTime = "hh:mm:ss"	'8 characters

	NSBH.CompileInfo CompileDate, CompileTime

AudioAdjVolumeSupported

AdjVolumeSupported = NSBHandEra.AudioAdjVolumeSupported()

Returns 1 if the HandEra device supports the Adjust Volume feature. If it doesn't, it returns 0.

Parameters: None

Returns: Answer as Integer.

Example

	Dim Answer as Integer
	Answer = NSBH.AudioAdjVolumeSupported()

AudioDTMFSupported

DTMFSupported = NSBHandEra.AudioDTMFSupported()

Returns 1 if the HandEra device supports the DTMF Play features. If it doesn't, it returns 0.

Parameters: None

Returns: Answer as Integer

Example

	Dim Answer as Integer
	Answer = NSBH.AudioDTMFSupported()

AudioGetMasterVolume

Volume = NSBHandEra.AudioGetMasterVolume()

Returns the HandEra volume setting.

Parameters: None

Returns: Volume as Integer(0 to 255)

Example

	Dim Volume as Integer
	Volume = NSBH.AudioGetMasterVolume()

AudioGetMute

Muted = NSBHandEra.AudioGetMute()

Returns the mute setting of the HandEra device.

Parameters: None

Returns: Muted as Integer

Example

	Dim Muted as Integer
	Muted = NSBH.AudioGetMute()

AudioPlayDTMFChar

NSBHandEra.AudioPlayDTMFChar DTMFString, ToneLength

Plays a 1 character DTMF (Dual Tone Multi Frequency) sound. Telephone "Touch Tones" are DTMF sounds. This function can be used to implement a phone dialer. The HandEra POSE currently does not properly support the DTMF functions.

Parameters:
DTMFString as String (Only the first character is used)
ToneLength as Integer (presumably in "ticks")

Returns: None

Example

	Dim ToneLength as Integer
	Dim DTMFString as String

	DTMFString = "*"
	ToneLength = 25

	NSBH.AudioPlayDTMFChar DTMFString, ToneLength

AudioPlayDTMFStr

NSBHandEra.AudioPlayDTMFStr DTMFString, ToneLength, GapLength

Plays a string of DTMF (Dual Tone Multi Frequency) sounds. Telephone "Touch Tones" are DTMF sounds. This function can be used to implement a phone dialer. The HandEra POSE currently does not properly support the DTMF functions. In fact, this particular function seems to cause the HandEra POSE to enter an infinite loop.

Parameters:
DTMFString as String
ToneLength as Integer (presumably in "ticks")
GapLength as Integer (presumably in "ticks")

Returns: None

Example

	Dim ToneLength as Integer
	Dim GapLength as Integer
	Dim DTMFString as String

	DTMFString = "555-2121"
	ToneLength = 25
	GapLength = 10

	NSBH.AudioPlayDTMFStr DTMFString, ToneLength, GapLength

AudioPlayWaveSupported

PlayWaveSupported = NSBHandEra.AudioPlayWaveSupported()

Returns 1 if the HandEra device supports the Play Wave features. If it doesn't, it returns 0.

Parameters: None

Returns: Answer as Integer (1 = True) (0 = False) (-1 = Not a HandEra device)

Example

	Dim Answer as Integer
	Answer = NSBH.AudioPlayWaveSupported()

AudioRecordWaveSupported

RecordWaveSupported = NSBHandEra.AudioRecordWaveSupported()

Returns 1 if the HandEra device supports the Record Wave features. If it doesn't, it returns 0.

Parameters: None

Returns: Answer as Integer

Example

	Dim Answer as Integer
	Answer = NSBH.AudioRecordWaveSupported()

AudioSetMasterVolume

NSBHandEra.AudioSetMasterVolume Volume

Sets the master volume level of the HandEra device.

Parameters: Volume as Integer (0 to 255)

Returns: None

Example

	Dim Volume as Integer
	Volume = 127
	NSBH.AudioSetMasterVolume Volume

AudioSetMute

NSBHandEra.AudioSetMute Muted

Sets the muted setting of the HandEra device.

Parameters: Mute as Integer (1 = True, 0 = False)

Returns: None

Example

	Dim Muted as Integer
	Muted = 1
	NSBH.AudioSetMute Muted

AudioVolumeDlg

NSBHandEra.AudioVolumeDlg TitleString

Displays a dialog that allows the user to select the volume and muting settings.

Parameters: TitleString as String

Returns: None

Example

	Dim TitleString as String
	TitleString = "Adjust the Volume"
	NSBH.AudioVolumeDlg TitleString

SilkGetGraffitiPersistence

Persistence = NSBHandEra.SilkGetGraffitiPersistence()

Returns the GraffitiPersistence setting in ticks. Graffiti Persistence is the amount of time that a graffiti stroke is displayed in the HandEra virtual silkscreen area.

Parameters: None

Returns: Persistence as Integer (as ticks)

Example

	Dim Persistence as Integer	
	Persistence = NSBH.SilkGetGraffitiPersistence

SilkMaximizeWindow

NSBHandEra.SilkMaximizeWindow()

Maximize the HandEra virtual silkscreen.

Parameters: None

Returns: None

Example

	NSBH.SilkMaximizeWindow()

SilkMinimizeWindow

NSBHandEra.SilkMinimizeWindow()

Minimize the HandEra virtual silkscreen.

Parameters: None

Returns: None

Example

	NSBH.SilkMinimizeWindow()

SilkSetGraffitiPersistence

NSBHandEra.SilkSetGraffitiPersistence Persistence

Sets the GraffitiPersistence setting in ticks. Graffiti Persistence is the amount of time that a graffiti stroke is displayed in the HandEra virtual silkscreen area.

Parameters: Persistence as Integer (in ticks)

Returns: None

Example

	Dim Persistence as Integer
	Persistence = 100
	NSBH.SilkSetGraffitiPersistence Persistence

SilkWindowMinimized

Minimized = NSBHandEra.SilkWindowMinimized()

Return 1 if the HandEra virtual silkscreen window is minimized. It returns 0, if it is not.

Parameters: None

Returns: Answer as Integer

SizeForm

NSBHandEra.SizeForm()

This function resets the form's window bounds using the current window display extent. It is used after calling a function that changes the screen mode. This function erases the screen, so a "Redraw" is required after calling SizeForm().

Parameters: None

Returns: None

Example

	NSBH.SizeForm()
	Redraw

VgaBaseToVgaFont

VGAFontID = NSBHandEra.VgaBaseToVgaFont(BaseFontID)

Returns the High Resolution (VGA) font id that is equivalent to the supplied Base (Palm) font id.

Parameters: BaseFontID as Integer

Returns: VGAFontID as Integer

Example

	Dim BaseFontID as Integer
	Dim VGAFontID as Integer

	BaseFontId = 0
	VGAFontId = NSBH.VgaBaseToVgaFont(BaseFontID)

VgaFontSelect

FontID = NSBHandEra.VgaFontSelect(FontType, DefaultFontID)

Display a dialog to allow the user to select a font. The FontType parameter specifies whether to display only the Base (Palm) fonts or the Base and VGA (High Resolution) fonts.

Parameters: FontType as Integer

0 = Base fonts only
1 = Base and VGA fonts
DefaultFontID as Integer - FontID to highlight as default

Returns: FontID as Integer

Example

	Dim FontID as Integer
	Dim FontType as Integer
	Dim DefaultFontID as Integer

	FontType = 1
	DefaultFontId = 224
	FontID = NSBH.VgaFontSelect(FontType, DefaultFontID)

VgaFrmModify

Error = NSBHandEra.VgaFrmModify()

Changes the screen mode to "1 to 1", if necessary, and modifies the form's objects by expanding their size by 1.5 times. This allows a 160x160 pixel form to display normally, in "1 to 1" mode, on a 240x240 pixel screen. Each time this function is called, the forms objects are expanded, so this function should be called only once. The form's screen is also erased so a "Redraw" is necessary.

Parameters: None

Returns: Error as Integer (-1 = Not a HandEra Device) (-2 = No form is active)

Example

	Dim Error as Integer
	Error = NSBH.VgaFrmModify()
	Redraw

VgaFrmGetTitleHeight

TitleHeight = NSBHandEra.VgaFrmGetTitleHeight()

Returns the form's title height in pixels.

Parameters: None

Returns: TitleHeight as Integer

Example

	Dim TitleHeight as Integer
	TitleHeight = NSBH.VgaFrmGetTitleHeight()

VgaGetScreenMode

Mode = NSBHandEra.VgaGetScreenMode()

Returns the current screen mode. This function also retrieves the current screen rotation. The rotation value can be returned by calling VgaGetScreenRotation().

Parameters: None

Returns: Mode as Integer

0 = Scale to Fit
1 = 1 to 1
-1 = Not a HandEra device

Example

	Dim Mode as Integer
	Mode = NSBH.VgaGetScreenMode()

VgaGetScreenOffset

Offset = NSBHandEra.VgaGetScreenOffset()

Returns the screen offset that was retrieved by a previous VgaGetScreenState() function call.

Parameters: None

Returns: Offset as Integer

0 = offsetModeTopLeft
1 = offsetModeTopCenter
2 = offsetModeTopRight
3 = offsetModeCenterLeft
4 = offsetModeCenterCenter
5 = offsetModeCenterRight
6 = offsetModeBottomLeft
7 = offsetModeBottomCenter
8 = offsetModeBottomRight
-1 = Not a HandEra device

Example

	Dim Mode as Integer
	Dim Offset as Integer

	Mode = NSBH.VgaGetScreenState()
	Offset = NSBH.VgaGetScreenOffset()

VgaGetScreenRotation

Rotation = NSBHandEra.VgaGetScreenRotation()

Returns the screen rotation that was retrieved by a previous VgaGetScreenMode() or VgaGetScreenState() function call.

Parameters: None

Returns: Rotation as Integer

0 = rotateModeNone
1 = rotateMode90
2 = rotateMode180
3 = rotateMode270
-1 = Not a HandEra device

Example

	Dim Mode as Integer
	Dim Rotation as Integer

	Mode = NSBH.VgaGetScreenMode()
	Rotation = NSBH.VgaGetScreenRotation()

VgaGetScreenState

Mode = NSBHandEra.VgaGetScreenState()

Returns the current screen mode. This function also retrieves the current screen rotation and offset. The rotation value can be returned by calling VgaGetScreenRotation(). The offset value can be returned by calling VgaGetScreenOffset().

Parameters: None

Returns: Mode as Integer

0 = Scale to Fit
1 = 1 to 1
-1 = Not a HandEra device

Example

	Dim Mode as Integer
	Mode = NSBH.VgaGetScreenState()

VgaIsVgaFont

Answer = NSBHandEra.VgaIsVgaFont(FontID)

Returns 1 if the specified FontID is a High Resolution (VGA) Font. It returns 0, if it is not.

Parameters: FontID as Integer

Returns: Answer as Integer (1 = True) (0 = False) (-1 = Not a HandEra device)

Example

	Dim FontID as Integer
	Dim Answer as Integer

	FontID = 224
	Answer = NSBH.VgaIsVgaFont(FontID)

VgaRestoreScreenState

Error = NSBHandEra.VgaRestoreScreenState()

Restores the screen state that was saved by a previous call to VgaSaveScreenState(). This function erases the form's screen, and as such, should be followed with a Redraw statement.

Parameters: None

Returns: Error as Integer

Example

	Dim Error as Integer

	Error = NSBH.VgaRestoreScreenState()
	Redraw

VgaRotateSelect

Rotation = NSBHandEra.VgaRotateSelect(DefaultRotation)

Displays a dialog to allow the user to select a screen rotation. The DefaultRotation parameter specifies a rotation to highlight as the default. This function does not actually rotate the screen. You must call the VgaSetScreenMode() or VgaSetScreenState() function with the returned Rotation to actually rotate the screen.

Parameters: DefaultRotation as Integer

0 = rotateModeNone
1 = rotateMode90
2 = rotateMode180
3 = rotateMode270

Returns: Rotation as Integer

0 = rotateModeNone
1 = rotateMode90
2 = rotateMode180
3 = rotateMode270
-1 = Not a HandEra device

Example

	Dim DefaultRotation as Integer
	Dim Rotation as Integer

	DefaultRotation = 2
	Rotation = NSBH.VgaRotateSelect(DefaultRotation)

VgaSaveScreenState

NSBHandEra.VgaSaveScreenState()

Saves the current screen state. The saved screen state may be restored by calling VgaRestoreScreenState().

Parameters: None

Returns: None

Example

	NSBH.VgaSaveScreenState()

VgaSetScreenMode

Error = NSBHandEra.VgaSetScreenMode(Mode, Rotation)

Sets the screen mode and rotation. This function erases the form's screen, and as such, should be followed with a Redraw statement.

Parameters: Mode as Integer

0 = Scale to Fit
1 = 1 to 1

Rotation as Integer

0 = rotateModeNone
1 = rotateMode90
2 = rotateMode180
3 = rotateMode270

Returns: Error as Integer

Example

	Dim Mode as Integer
	Dim Rotation as Integer
	Dim Error as Integer

	Mode = 1
	Rotation = 0
	Error = NSBH.VgaSetScreenMode(Mode, Rotation)
	Redraw

VgaSetScreenState

Error = NSBHandEra.VgaSetScreenState(Mode, Rotation, Offset)

Sets the screen mode, rotation, and (presumably) offset. This function erases the form's screen, and as such, should be followed with a Redraw statement.

Parameters: Mode as Integer

0 = Scale to Fit
1 = 1 to 1

Rotation as Integer

0 = rotateModeNone
1 = rotateMode90
2 = rotateMode180
3 = rotateMode270

Offset as Integer

0 = offsetModeTopLeft
1 = offsetModeTopCenter
2 = offsetModeTopRight
3 = offsetModeCenterLeft
4 = offsetModeCenterCenter
5 = offsetModeCenterRight
6 = offsetModeBottomLeft
7 = offsetModeBottomCenter
8 = offsetModeBottomRight

Returns: Error as Integer

Example

	Dim Mode as Integer
	Dim Rotation as Integer
	Dim Offset as Integer
	Dim Error as Integer

	Mode = 1
	Rotation = 0
	Offset = 0
	Error = NSBH.VgaSetScreenState(Mode, Rotation, Offset)
	Redraw

VgaVgaToBaseFont

BaseFontID = NSBHandEra.VgaVgaToBaseFont(VGAFontID)

Returns the Base (Palm) font id that is equivalent to the supplied High Resolution (VGA) font id.

Parameters: VGAFontID as Integer

Returns: BaseFontID as Integer

Example

	Dim VGAFontID as Integer
	Dim BaseFontID as Integer

	VGAFontId = 224
	BaseFontId = NSBH.VgaVgaToBaseFont(VGAFontID)

VgaWinDrawBitmapExpanded

NSBHandEra.VgaWinDrawBitmapExpanded ObjectID, X, Y

Expands a bitmap by 1.5 times and draws it at the specified X and Y coordinates. The bitmap is specified by it's object id. This object id is the same id that appears when you look at a bitmap's properties in the NSBasic IDE.

Parameters:
ObjectID as Integer
X as Integer
Y as Integer

Returns: None

Example

	Dim ObjectID as Integer
	Dim X as Integer
	Dim Y as Integer

	ObjectID = 1155
	X = 120
	Y = 105
	NSBH.VgaWinDrawBitmapExpanded ObjectID, X, Y

ResType	Res ID	Notes
2000	tAIB	large Icons: 32x32 images
2001	tAIB	small icons: 24x14 image
2002	tAIB	Inverse large icons: 32x32

HandEra Button	GetEventType()	GetKey()
Aux	1	27 (escape)
Jog Right	1	13 (return)
Jog Up	5	12
Jog Down	5	3
Silkscreen Changed	24574