Tech Note 09: Using Handera Devices

Tech Note 11: HandEraデバイスを使う

June 12, 2001

(Special thanks to Ron Glowka)

NS Basic/Palm バージョン1.12より、NSBHandEra共有ライブラリ（Shared Library）がHandEraの高画質スクリーン、バーチャル・シルクスクリーン、オーディオ機能のサポートを提供します。このドキュメントは、このライブラリのファンクションを解説します。この共有ライブラリの目的と用途を完全に理解するには、HandEra 330 Programmer's Companion および Programmer's Reference Manualを参照することをお勧めします。これらのマニュアルはHandEra SDKの一部として、次のサイトからダウンロードすることが可能です。

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

NSBHandEra共有ライブラリは、HandEra SDKファンクションの部分集合を提供します。このライブラリのファンクションの大部分は"wrapper（カバー）"であり、NSBasicからHandEra APIを呼べるようにしています。 HandEraのバーチャル・シルクスクリーン・ビットマップのカスタマイズ、およびオーディオ録音／再生機能のファンクションは、まだインプリメントされていません。

貴方のプログラムをテストするには、実際のHandEra 330を手に入れる必要はありません。ほとんどのファンクション（いくつかのオーディオファンクションは除く）は、HandEra ROMイメージと共に、HandEraから入手可能なPOSEの修正バージョンを使うことによって動作します。どちらのファイルもHandEraのDeveloper Supportページから入手可能です。

HandEraファンクションを使う

1. NS Basic/Palmインストーラによって、HandEra.INFファイルが \NSBasic\Lib に入れられます。さらにHandEra.prcが \NSBasic\download へ入れられますので、お使いのデバイスかPOSEにダウンロードして下さい。

2. このライブラリはNSBasicのLoadLibraryステートメントを使用して、読込まれなければなりません。ファンクションががプログラムの全体にわたって利用可能になるように、このステートメントはプログラムのStartup Codeに入れて下さい。ライブラリのファンクションに略した参照名を指定できるように、LoadLibraryステートメントはオプションである２つ目のパラメータを持っています。この参照名のために「NSBH」を、このドキュメントでは使用しています。例：

プログラムのStartup code:

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

3. アプリケーションがHi-Resモードを使用する場合、Build...Optionsのチェックボックスをチェックして下さい。

4. High-resアイコンを持っている場合は、コンパイルの後にPalmRIを使ってそれらを.prcファイルに追加して下さい。PalmRIの手引きはTech Note 04aに含まれています。PalmRIは \program files\nsbasic に位置しています。

新しく作成しなければならないResTypeおよびRes IDは以下の表に示します。

ResType Res ID Notes

2000 Tbmp 大アイコン: 32x32 イメージ

2001 Tbmp 小アイコン: 24x14 イメージ

2002 Tbmp 大アイコンの反転: 32x32

5. Additional HandEra Events: HandEra 330は４つの追加ボタンファンクションを持っています。（JogダイアルおよびAuxボタン）UIガイドラインによると、Jogボタンを押すことはキーボードのreturnキーを押すのと同じです。Auxボタンはescapeキーで、現フォームを終了する時に使用します。

さらにHandEraは、シルクスクリーンを最大化または最小化するために矢印が使われると、貴方のプログラムに一つのイベントを送ります。

HandEraボタン GetEventType() GetKey()

Aux 1 27 (escape)

Jog Right 1 13 (return)

Jog Up 5 12

Jog Down 5 3

Silkscreen Changed 24574

NSBHandEra共有ライブラリのファンクションリファレンス

Version()ファンクションを除いて、全てのパラメーターおよび戻り値のデータタイプは整数（Integer）あるいは文字列（String）のいずれかです。-1の戻り値は、HandEraデバイスではないことを示します。全てのファンクションは、HandEra APIが使用される前にHandEra機能が利用可能であることを確認します。これは、HandEraデバイスを使用してなくても、任意のデバイス上でNSBHandEra共有ライブラリーの使用を可能にしています。もちろん、ライブラリのファンクションは意図しているようには実行されませんが、プログラムが止まることはないでしょう。

Version

VersionNbr = NSBHandEra.Version()

NSBHandEra共有ライブラリのバージョン番号を戻します。

パラメータ: 無

戻り値: VersionNbr as Double

例

	Dim VersionNbr as Double
	VersionNbr = NSBH.Version()

CompileInfo

NSBHandEra.CompileInfo CompileDate, CompileTime

NSBHandEra共有ライブラリがコンパイルされた日時を戻します。CompileInfoを呼ぶ前にCompileDateとCompileTime文字列変数を初期化しなければなりません。

パラメータ: CompileDate as String CompileTime as String

戻り値: 無

例

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

HandEraデバイスがAdjust Volume機能をサポートしている場合は１を、していない場合は０を戻します。

パラメータ: 無

戻り値: Answer as Integer.

例

	Dim Answer as Integer
	Answer = NSBH.AudioAdjVolumeSupported()

AudioDTMFSupported

DTMFSupported = NSBHandEra.AudioDTMFSupported()

HandEraデバイスがDTMF Play機能をサポートしている場合は１を、していない場合は０を戻します。

パラメータ: 無

戻り値: Answer as Integer

例

	Dim Answer as Integer
	Answer = NSBH.AudioDTMFSupported()

AudioGetMasterVolume

Volume = NSBHandEra.AudioGetMasterVolume()

HandEraのボリューム設定を戻します。

パラメータ: 無

戻り値: Volume as Integer(0 to 255)

例

	Dim Volume as Integer
	Volume = NSBH.AudioGetMasterVolume()

AudioGetMute

Muted = NSBHandEra.AudioGetMute()

HandEraデバイスのミュート（消音）設定を戻します。

パラメータ: 無

戻り値: Muted as Integer

例

	Dim Muted as Integer
	Muted = NSBH.AudioGetMute()

AudioPlayDTMFChar

NSBHandEra.AudioPlayDTMFChar DTMFString, ToneLength

１文字のDTMF (Dual Tone Multi Frequency)サウンドを再生します。電話の「タッチトーン」はDTMFサウンドです。このファンクションは電話のダイアル機能として使うことが出来ます。現在HandEra POSEはDTMFファンクションを正しくサポートしていません。

パラメータ:
DTMFString as String (Only the first character is used)
ToneLength as Integer (presumably in "ticks")

戻り値: 無

例

	Dim ToneLength as Integer
	Dim DTMFString as String

	DTMFString = "*"
	ToneLength = 25

	NSBH.AudioPlayDTMFChar DTMFString, ToneLength

AudioPlayDTMFStr

NSBHandEra.AudioPlayDTMFStr DTMFString, ToneLength, GapLength

DTMF (Dual Tone Multi Frequency)サウンドの文字列を再生します。電話の「タッチトーン」はDTMFサウンドです。このファンクションは電話のダイアル機能として使うことが出来ます。現在HandEra POSEはDTMFファンクションを正しくサポートしていません。特にこのファンクションは、HandEra POSE上では永久ループへの突入を引き起こします。

パラメータ:
DTMFString as String
ToneLength as Integer (presumably in "ticks")
GapLength as Integer (presumably in "ticks")

戻り値: 無

例

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

HandEraデバイスがPlay Wave機能をサポートしている場合は１を、していない場合は０を戻します。

パラメータ: 無

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

例

	Dim Answer as Integer
	Answer = NSBH.AudioPlayWaveSupported()

AudioRecordWaveSupported

RecordWaveSupported = NSBHandEra.AudioRecordWaveSupported()

HandEraデバイスがRecord Wave機能をサポートしている場合は１を、していない場合は０を戻します。

パラメータ: 無

戻り値: Answer as Integer

例

	Dim Answer as Integer
	Answer = NSBH.AudioRecordWaveSupported()

AudioSetMasterVolume

NSBHandEra.AudioSetMasterVolume Volume

HandEraデバイスのマスターボリュームレベルをセットします。

パラメータ: Volume as Integer (0 to 255)

戻り値: 無

例

	Dim Volume as Integer
	Volume = 127
	NSBH.AudioSetMasterVolume Volume

AudioSetMute

NSBHandEra.AudioSetMute Muted

Sets the muted setting of the HandEra device.

パラメータ: Mute as Integer (1 = True, 0 = False)

戻り値: 無

例

	Dim Muted as Integer
	Muted = 1
	NSBH.AudioSetMute Muted

AudioVolumeDlg

NSBHandEra.AudioVolumeDlg TitleString

ダイアログを表示し、ユーザがボリュームとミュート（消音）の設定を選ぶことが出来るようにします。

パラメータ: TitleString as String

戻り値: 無

例

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

SilkGetGraffitiPersistence

Persistence = NSBHandEra.SilkGetGraffitiPersistence()

GraffitiPersistence設定を刻み数で戻します。 Graffiti PersistenceはHandEra バーチャル・スクリーン領域内にグラフィティストロークが表示される時間です。

パラメータ: 無

戻り値: Persistence as Integer (as ticks)

例

	Dim Persistence as Integer	
	Persistence = NSBH.SilkGetGraffitiPersistence

SilkMaximizeWindow

NSBHandEra.SilkMaximizeWindow()

HandEraバーチャル・スクリーンを最大化します。

パラメータ: 無

戻り値: 無

例

	NSBH.SilkMaximizeWindow()

SilkMinimizeWindow

NSBHandEra.SilkMinimizeWindow()

HandEraバーチャル・スクリーンを最小化します。

パラメータ: 無

戻り値: 無

例

	NSBH.SilkMinimizeWindow()

SilkSetGraffitiPersistence

NSBHandEra.SilkSetGraffitiPersistence Persistence

GraffitiPersistence設定を刻み数でセットします。 Graffiti PersistenceはHandEraバーチャル・スクリーン領域内にグラフィティストロークが表示される時間です。

パラメータ: Persistence as Integer (in ticks)

戻り値: 無

例

	Dim Persistence as Integer
	Persistence = 100
	NSBH.SilkSetGraffitiPersistence Persistence

SilkWindowMinimized

Minimized = NSBHandEra.SilkWindowMinimized()

HandEraバーチャル・シルクスクリーンが最小化されている場合は１を、そうでない場合は０を戻します。

パラメータ: 無

戻り値: Answer as Integer

SizeForm

NSBHandEra.SizeForm()

ウインドウのディスプレイ範囲を使って、フォームのウィンドウ境界をリセットします。これは、スクリーンモードを変更するファンクションを呼んだ後に使用します。このファンクションはスクリーンを消すため、SizeForm()を呼んだ後には"Redraw"が必要になります。

パラメータ: 無

戻り値: 無

例

	NSBH.SizeForm()
	Redraw

VgaBaseToVgaFont

VGAFontID = NSBHandEra.VgaBaseToVgaFont(BaseFontID)

渡されるBase (Palm) フォントIDと同等なHigh Resolution (VGA) フォントIDを戻します。

パラメータ: BaseFontID as Integer

戻り値: VGAFontID as Integer

例

	Dim BaseFontID as Integer
	Dim VGAFontID as Integer

	BaseFontId = 0
	VGAFontId = NSBH.VgaBaseToVgaFont(BaseFontID)

VgaFontSelect

FontID = NSBHandEra.VgaFontSelect(FontType, DefaultFontID)

ユーザにフォントを選ばせる為のダイアログを表示します。FontTypeパラメータは、 Base(Palm)フォントだけを表示するか、BaseとVGA(High Resolution)を表示するかを指定します。

パラメータ: FontType as Integer

0 = Baseフォントのみ
1 = BaseとVGAフォント
DefaultFontID as Integer - デフォルトとしてハイライトする為のFontID

戻り値: FontID as Integer

例

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

スクリーンモードを"1 to 1"に変更し、必要であれば、フォームのオブジェクトサイズを 1.5倍に拡大します。これは通常160x160ピクセルのフォームを、"1 to 1"モードでは、 240x240ピクセルで表示するようにします。このファンクションが呼ばれる度にフォームオブジェクトは拡大されるため、ファンクションは１回だけ呼ぶようにします。これもフォームのスクリーンは消されますので、"Redraw"が必要になります。

パラメータ: None

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

例

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

VgaFrmGetTitleHeight

TitleHeight = NSBHandEra.VgaFrmGetTitleHeight()

フォームのタイトルの高さをピクセルで戻します。

パラメータ: 無

戻り値: TitleHeight as Integer

例

	Dim TitleHeight as Integer
	TitleHeight = NSBH.VgaFrmGetTitleHeight()

VgaGetScreenMode

Mode = NSBHandEra.VgaGetScreenMode()

現スクリーンモードを戻します。このファンクションはさらに、現スクリーンローテーションも検索します。ローテーション値はVgaGetScreenRotation()を呼ぶことによって得ることが出来ます。

パラメータ: 無

戻り値: Mode as Integer

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

例

	Dim Mode as Integer
	Mode = NSBH.VgaGetScreenMode()

VgaGetScreenOffset

Offset = NSBHandEra.VgaGetScreenOffset()

先に呼ぶVgaGetScreenState()ファンクションによって検索した、スクリーンのオフセットを戻します。

パラメータ: 無

戻り値: 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

例

	Dim Mode as Integer
	Dim Offset as Integer

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

VgaGetScreenRotation

Rotation = NSBHandEra.VgaGetScreenRotation()

先に呼ぶVgaGetScreenMode()またはVgaGetScreenState()ファンクションによって検索した、スクリーンローテーションを戻します。

パラメータ: 無

戻り値: Rotation as Integer

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

例

	Dim Mode as Integer
	Dim Rotation as Integer

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

VgaGetScreenState

Mode = NSBHandEra.VgaGetScreenState()

現スクリーンモードを戻します。このファンクションはさらに、現スクリーンのローテーションとオフセットも検索します。ローテーション値はVgaGetScreenRotation()を呼ぶことによって得ることが出来ます。オフセット値はVgaGetScreenOffset()を呼ぶことによって得ることが出来ます。

パラメータ: 無

戻り値: Mode as Integer

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

例

	Dim Mode as Integer
	Mode = NSBH.VgaGetScreenState()

VgaIsVgaFont

Answer = NSBHandEra.VgaIsVgaFont(FontID)

指定のFontIDがHigh Resolution (VGA)フォントなら１を、そうでなければ０を戻します。

パラメータ: FontID as Integer

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

例

	Dim FontID as Integer
	Dim Answer as Integer

	FontID = 224
	Answer = NSBH.VgaIsVgaFont(FontID)

VgaRestoreScreenState

Error = NSBHandEra.VgaRestoreScreenState()

先に呼ぶVgaSaveScreenState()によって保管されるスクリーン状態を戻します。このファンクションはフォームのスクリーンを消しますので、"Redraw"ステートメントが続かなければなりません。

パラメータ: 無

戻り値: Error as Integer

例

	Dim Error as Integer

	Error = NSBH.VgaRestoreScreenState()
	Redraw

VgaRotateSelect

Rotation = NSBHandEra.VgaRotateSelect(DefaultRotation)

ユーザにスクリーンローテーションを選ばせる為のダイアログを表示します。DefaultRotationパラメータは、デフォルトとしてのhighlightにローテーションを指定します。このファンクションは、実際にはスクリーンを回転させません。実際にスクリーンを回転させるためには、戻されたRotationと共にgaSetScreenMode()かVgaSetScreenState() ファンクションを呼ばなくてはなりません。

パラメータ: DefaultRotation as Integer

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

戻り値: Rotation as Integer

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

例

	Dim DefaultRotation as Integer
	Dim Rotation as Integer

	DefaultRotation = 2
	Rotation = NSBH.VgaRotateSelect(DefaultRotation)

VgaSaveScreenState

NSBHandEra.VgaSaveScreenState()

現スクリーン状態を保存します。保存されたスクリーン状態は、VgaRestoreScreenState()を呼ぶことによって受け取れるでしょう。

パラメータ: 無

戻り値: 無

例

	NSBH.VgaSaveScreenState()

VgaSetScreenMode

Error = NSBHandEra.VgaSetScreenMode(Mode, Rotation)

スクリーンのモードとローテーションをセットします。このファンクションはフォームのスクリーンを消しますので、"Redraw"ステートメントが続かなければなりません。

パラメータ: Mode as Integer

0 = Scale to Fit
1 = 1 to 1

Rotation as Integer

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

戻り値: Error as Integer

例

	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)

このファンクションはスクリーンのモード、ローテーション、オフセットをセットします。このファンクションはフォームのスクリーンを消しますので、"Redraw"ステートメントが続かなければなりません。

パラメータ: 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

戻り値: Error as Integer

例

	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)

渡されるHigh Resolution (VGA) フォントIDと同等なBase (Palm) フォントIDを戻します。

パラメータ: VGAFontID as Integer

戻り値: BaseFontID as Integer

例

	Dim VGAFontID as Integer
	Dim BaseFontID as Integer

	VGAFontId = 224
	BaseFontId = NSBH.VgaVgaToBaseFont(VGAFontID)

VgaWinDrawBitmapExpanded

NSBHandEra.VgaWinDrawBitmapExpanded ObjectID, X, Y

ビットマップを1.5倍し、指定するＸ軸とＹ軸に描きます。ビットマップはそのオブジェクトIDによって指定されます。このオブジェクトIDは、NSBasic IDE内のビットマップのプロパティ(properties)にあるIDと同じです。

パラメータ:
ObjectID as Integer
X as Integer
Y as Integer

戻り値: 無

例

	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	Tbmp	大アイコン: 32x32 イメージ
2001	Tbmp	小アイコン: 24x14 イメージ
2002	Tbmp	大アイコンの反転: 32x32

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

HandEraファンクションを使う

NSBHandEra共有ライブラリのファンクション リファレンス

Version

CompileInfo

AudioAdjVolumeSupported

AudioDTMFSupported

AudioGetMasterVolume

AudioGetMute

AudioPlayDTMFChar

AudioPlayDTMFStr

AudioPlayWaveSupported

AudioRecordWaveSupported

AudioSetMasterVolume

AudioSetMute

AudioVolumeDlg

SilkGetGraffitiPersistence

SilkMaximizeWindow

SilkMinimizeWindow

SilkSetGraffitiPersistence

SilkWindowMinimized

SizeForm

VgaBaseToVgaFont

VgaFontSelect

VgaFrmModify

VgaFrmGetTitleHeight

VgaGetScreenMode

VgaGetScreenOffset

VgaGetScreenRotation

VgaGetScreenState

VgaIsVgaFont

VgaRestoreScreenState

VgaRotateSelect

VgaSaveScreenState

VgaSetScreenMode

VgaSetScreenState

VgaVgaToBaseFont

VgaWinDrawBitmapExpanded

NSBHandEra共有ライブラリのファンクションリファレンス