Ｘ作成講座 on ＦＢ[01]　Glue ファイルの修正


　HyperXcmd Glue.INCL （以下 "Glueファイル" ）はＦＢに付属しているファイルです。 HyperCard の持っているグルールーチン（コールバック）をＦＢから呼び出せるようにするためのインクルードファイルで、これがないと XCMD を作れません。


　最初 FutureBASIC II 日本語版に付いていた Glueファイルは作成日が９５年１１月２４日のものでした。これはバグだらけでほとんど使いものにならないシロモノです。その後ＦＢII が 2.3 にアップデートされた時に Glueファイルもアップデートされ、現在のＦＢII 日本語版には作成日９６年８月７日のものが付属していると思います。（ファイル中に何カ所も '･･･ 7/8/96 ･･･ というコメントが入っていて、修正した跡が見られます）

　ところがこの新版の Glueファイルもバグだらけだったのです。オリジナルに手を加えるのはどうも気持ちが悪いのですが、このまま使うとものによっては爆弾の憂き目に会いますので、ここはひとつ思い切ってインクルードファイルの書き換えをしてしまいましょう。


　　　　　　　　　　　　　−・−・−


　今回変更を加えるのは日本語版ＦＢII の中の "(FB) Examples" フォルダの、"Extending Appls" の中の "HyperCard" フォルダにある "XCMD Templates" フォルダです。ここにある "HyperXcmd Glue.INCL" ファイルの作成日が９６年８月７日（月）であることを確認して下さい。もし作成日が違っていたら ModE のサイトから最新版を落として来て下さい。

　ファイルを確認したら、この "XCMD Templates" フォルダを丸ごとコピーします。名前は "XCMD テンプレート" とでも変えてオリジナルと区別できるようにしておいて下さい。以下の説明ではこの新しく作ったフォルダの中のファイルを書き換えます。

　同じ HyperCard フォルダに "XCMD projects" フォルダがありますが、この中のファイルは触らないで下さい。サンプル XCMD は古い Glueファイルを使ってコンパイルするように出来ているので、ここの Glueファイルを変更してしまうとサンプルがコンパイル出来なくなってしまいます。また同梱されている英語版のファイルもそのままにしておいて下さい。

　ここではグルールーチンを規定している HyperXcmd Glue.INCL を修正し、それに伴って変更が必要になる HyperXcmd.MAIN も一部修正します。


　　　　　　　　　　　　　−・−・−


　まず HyperXcmd Glue.INCL を修正しましょう。

　以下私の分かる範囲でチェックして、修正が必要な部分について変更法方を書いてあります。また各ルーチンの簡単な説明も添えてありますので、グルールーチンの使い方の参考にして下さい。変更した部分は全て実際にコンパイルして HyperCard 上でテストしてあります。


　凡例：
　○　＝　動作確認済み
　●　＝　ソース書き換えが必要
　−　＝　使用不可
　Θ　＝　未確認

　theStr$.....　ＦＢ文字列。
　cStrPtr&....　Ｃ文字列ポインタ。　例：[cStrHandl&]
　cStrHandl&..　Ｃ文字列ハンドル。　例：[xCmdPtr& + _params + 0 * 4]


　注意１：ハンドルについて
　　関数の返値としてハンドルを返すものがあります。
　　このハンドルはＨＣに渡すか、使用後に破棄する必要があります。

　注意２：真偽値について
　　関数の返値として真偽値を返すものがあります。
　　偽は常に０ですが、真は「０以外の数字」と思っていた方がいいでしょう。
　　従ってＩＦ文では IF bool% <> _false THEN のように使うのが確実です。


　　　　　　　　　　　　　−・−・−


' ･････････････････････････････････････････････
' hypertalk utilities
' ･････････････････････････････････････････････

●cStrHandl& = FN EvalExpr (xCmdPtr&, theStr$)
　ＦＢ文字列をＨＣに「評価」させる。
　例えば "5 > 3" という文字列を与えると "true" という
　文字列のハンドルが返ってくる。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN EvalExpr (xCmdPtr&, @strPtr&)

●FN SendCardMessage (xCmdPtr&, theStr$)
　ＦＢ文字列をメッセージとしてカードに送る。
　例えば "go next" という文字列を渡すと次のカードに移動する。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN SendCardMessage (xCmdPtr&, @strPtr&)

●FN SendHCMessage (xCmdPtr&, theStr$)
　ＦＢ文字列をメッセージとしてハイパーカード本体に直接送る。
　カード等を経由しないぶん速い。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN SendHCMessage (xCmdPtr&, @strPtr&)


' ･････････････････････････････････････････････
' memory utilities
' ･････････････････････････････････････････････

●cStrHandl& = FN GetGlobal (xCmdPtr&, glblName$)
　ＨＣのグローバル変数の名前を渡すと、その変数の値を文字列として収めた
　ハンドルが返ってくる。一般にスクリプト中で使われる it はローカル変数で
　あるので、使用中の it の値を得るには別の方法が必要。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN GetGlobal (xCmdPtr&, @glblNamePtr&)

●FN SetGlobal (xCmdPtr&, glblName$, glblHndl&)
　ＨＣのグローバル変数を指定してそこに値（文字列）を書き込む。
　変数 it については GetGlobal と同じ注意が必要です。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN SetGlobal (xCmdPtr&, @glblNamePtr&, glblHndl&)
　：また、最後の行も以下のように書き換えて下さい。
　：DEF DISPOSEH(glbHndl&)　→　DEF DISPOSEH(glblHndl&)

○FN ZeroBytes (xCmdPtr&, dstPtr&, count&)
　与えたアドレスから count& バイトだけ０で埋める。


' ･････････････････････････････････････････････
' string utilities
' ･････････････････････････････････････････････

●FN ScanToReturn (xCmdPtr&, cStrPtr&)
　Ｃ文字列ポインタを渡すとリターンか最後までポインタを進める。
　関数実行後は cStrPtr& は０か１３を指している。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN ScanToReturn (xCmdPtr&, @scanPtr&)

●FN ScanToZero (xCmdPtr&, cStrPtr&)
　Ｃ文字列ポインタを渡すと文字列の最後までポインタを進める。
　関数実行後は cStrPtr& は０を指している。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN ScanToReturn (xCmdPtr&, @scanPtr&)

●bool% = FN StringEqual (xCmdPtr&, theStr1$, theStr2$)
　二つのＦＢ文字列を比較して真偽値を返す。
　大文字小文字は区別しません。日本語の文字列では正しく動作しません。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN StringEqual (xCmdPtr&, @str1Ptr&, @str2Ptr&)
　：また、最後の行も以下のように書き換えて下さい。
　：END FN = [xCmdPtr& + _outArgs]

○length& = FN StringLength (xCmdPtr&, cStrPtr&)
　Ｃ文字列ポインタを渡すとその文字長を返す。

●pos& = FN StringMatch (xCmdPtr&, theStr$, cStrPtr&)
　Ｃ文字列（第３パラメタ）の中にＦＢ文字列（第２パラメタ）が含まれるかを
　調べる。含まれていればその文字列のポインタを、含まれていなければ０を返す。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN StringMatch (xCmdPtr&, @matchStrPtr&, strPtr&)


' ･････････････････････････････････････････････
' string conversions
' ･････････････････････････････････････････････

●FN BooltoStr (xCmdPtr&, bool%, theStr$)
　真偽値を文字列に変換する。
　bool% が０なら "false"、０以外なら "true" がＦＢ文字列に入れられます。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN BoolToStr (xCmdPtr&, bool&, @strPtr&)

−FN ExtToStr (xCmdPtr&, extNum, @theStr$)
　浮動小数点を文字列に変換する。
　...はずだけど、ＦＢのＸでは浮動小数点を扱えません。

○FN LongToStr (xCmdPtr&, longInt&, theStr$)
　符号なしの longInt（倍精度整数）をＦＢ文字列に変換。
　扱う範囲は 0 から 4,294,967,298 まで。

○FN NumToHex (xCmdPtr&, longInt&, numDig%, theStr$)
　符号なしの longInt（倍精度整数）を１６進文字列に変換。
　第２パラメータは元になる数。第３パラメータは１６進文字列の桁数を指定。

○FN NumToStr (xCmdPtr&, longInt&, theStr$)
　符号付きの longInt（倍精度整数）を文字列に変換。
　扱う範囲は -2,147,483,647 から 2,147,483,647 まで。
　マイナスの返ってくる可能性のある関数を呼んだ時は、LongToStr ではなく
　NumToStr を使うようにしましょう。

○num& = FN StrToNum (xCmdPtr&, theStr$)
　文字列を符号付きの longInt（倍精度整数）に変換して返す。

○FN ReturnToPas (xCmdPtr&, cStrPtr&, theStr$)
　Ｃ文字列の先頭からリターン（もしくは文字列の終わり）までを
　ＦＢ文字列に入れて返す。

○bool% = FN StrToBool (xCmdPtr&, theStr$)
　真偽の文字列（"true" または "false"）を真偽値に変換。
　"true"（大文字小文字は問わない）以外の文字列は全て偽（0）が返ってきます。

−Var# = FN StrToExt (xCmdPtr&, theStr$, extNum)
　文字列を浮動小数点に変換する。
　...はずだけど、ＦＢのＸでは浮動小数点を扱えません。

●num& = FN StrToLong (xCmdPtr&, theStr$)
　文字列を符号なし longInt（倍精度整数）に変換。
　マイナスを含む文字列を渡してもマイナスを無視して変換します。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN StrToLong& (xCmdPtr&, @strPtr&)

○cStrHandl& = FN PasToZero (xCmdPtr&, theStr$)
　ＦＢ文字列をＣ文字列に変換してそのハンドルを返す。

○FN ZeroToPas (xCmdPtr&, cStrPtr&, theStr$)
　Ｃ文字列をＦＢ文字列に変換する。


' ･････････････････････････････････････････････
' field utilities
' ･････････････････････････････････････････････

○cStrHandl& = FN GetFieldByID (xCmdPtr&, cdFlag%, fieldID%)
　フィールドの文字列をコピーして、そのハンドルを返す。
　第２パラメタはカードフィールドなら１、ＢＧフィールドなら０を渡す。
　第３パラメタはフィールドＩＤを指定。

●cStrHandl& = FN GetFieldByName (xCmdPtr&, cdFlag%, fieldName$)
　フィールドの文字列をコピーして、そのハンドルを返す。
　第３パラメタはフィールド名を入れたＦＢ文字列。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN GetFieldByName(xCmdPtr&, cdFlag%, @fieldNamePtr&)

○cStrHandl& = FN GetFieldByNum (xCmdPtr&, cdFlag%, fieldNum%)
　フィールドの文字列をコピーして、そのハンドルを返す。
　第３パラメタはフィールド番号。

○FN SetFieldByID (xCmdPtr&, cdFlag%, fieldID%, cStrHandl&)
　フィールドにＣ文字列ハンドルの内容をコピーする。
　第２パラメタはカードフィールドなら１、ＢＧフィールドなら０を渡す。
　第３パラメタはフィールドＩＤ。
　第４パラメタはフィールドに入れるＣ文字列のハンドル。

●FN SetFieldByName (xCmdPtr&, cdFlag%, fieldName$, cStrHandl&)
　フィールドにＣ文字列ハンドルの内容をコピーする。
　第３パラメタはフィールド名を入れたＦＢ文字列。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN SetFieldByName (xCmdPtr&, cdFlag%, @fieldNamePtr&, dataHndl&)

○FN SetFieldByNum (xCmdPtr&, cdFlag%, fieldNum%, cStrHandl&)
　フィールドにＣ文字列ハンドルの内容をコピーする。
　第３パラメタはフィールドナンバー。


' ･････････････････････････････････････････････
' script routines
' ･････････････････････････････････････････････

○FN FormatScript (xCmdPtr&, scrptHndl&, insertPt&, quickFormat&)
　Ｃ文字列をスクリプトとみなして段落を付ける。
　insertPt& はカーソルの位置。quickFormat& は 0 で良い。

○FN ZeroTermHandle (xCmdPtr&, hndl&)
　ハンドルを１バイト拡張して最後に０を書き込む。
　Ｃ文字列としての終端処理。

ΘFN PrintTEHandle (xCmdPtr&, handleTE&, header&)
　テキストエディットの文字列をプリントする。
　header& はヘッダ文字列（Ｃ文字列）へのポインタ。

ΘFN SendHCEvent (xCmdPtr&, hcEvent&)
　ハイパーカードにイベントを送るらしい。

ΘProcPtr& = FN HCWordBreakProc (xCmdPtr&)
　テキストエディットのワードラップルーチンアドレスを返すらしい。


' ･････････････････････････････････････････････
' sound routines
' ･････････････････････････････････････････････

ΘFN BeginXSound (xCmdPtr&, wndPtr&)
　Ｘがサウンドマネージャを使うことを宣言するらしい。
　THINK C でもコンパイル出来ませんでした。使い方よくわからん。

ΘFN EndXSound (xCmdPtr&)
　サウンドの使用が終了したことを宣言するらしい。

○FN RunHandler (xCmdPtr&, cStrHandl&)
　Ｃ文字列ハンドルの文字列をスクリプトとしてハイパーカードに実行させる。
　改行を含んだ（＝複数行からなる）長いスクリプトを実行させることも出来る。
　ループや条件分岐なども含めて良い。


' ･････････････････････････････････････････････
' general utility routines
' ･････････････････････････････････････････････

●FN GetXResInfo (xCmdPtr&, refNum&, xID%, rType&, rName$)
　現在呼び出されているＸ自身の情報を得る。
　refNum& にはＸの入っているファイルのリファレンスナンバー、
　xID% にはＸのリソースＩＤ、
　rType& にはＸのタイプ（ _"XCMD" または _"XFCN"）、
　rName$ にはリソース名が返ってきます。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN GetXResInfo (xCmdPtr&, @resFilePtr& , @resID&, @rType&, @resNamePtr&)

●bool% = FN GetFilePath (xCmdPtr&, fileName$, numTypes%, typeList&, askUser&, fileType&, fullName$)
　ファイル名 fileName$が、ホームにあるファイル検索パスにあるかどうかを返す。
　askUser& に１を入れておくと見つからなかった場合にファイルダイアログを
　出してユーザーに確認を求める。０なら単に _false を返す。
　fileType& にはファイルタイプ（ _"APPL"、_"STAK" など）を指定するが、
　ファイルが見つからずにユーザーがダイアログからファイルを指定した場合は
　関数側からの返値を収める変数として働く。
　numTypes% にはファイルのタイプ数、typeList& にはタイプリストのポインタ、
　fullName$ にはファイルのフルパスが返ってきます。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN GetFilePath (xCmdPtr&, @fileNamePtr&, @numTypes&, @typeList&, askUser&, @fileType&, @fullNamePtr&)

ΘdocPtr& = FrontDocWindow( xCmdPtr& )
　一番上のドキュメントレイヤーウィンドウ（カードウィンドウ）のポインタを
　返す。フローティングパレットレイヤーのものは除外される。

●FN PointToStr (xCmdPtr&, thePoint, theStr$)
　座標を渡すとそれを "50,100" などのＦＢ文字列に変換する。
　：関数定義の２行目を以下のように書き換えて下さい。
　：xCmdPtr&.inArgs0& = ptPtr&

○FN RectToStr (xCmdPtr&, theRect, theStr$)
　レクトを渡すとそれを "50,100,200,300" などのＦＢ文字列に変換する。

○FN StrToPoint (xCmdPtr&, theStr$, thePoint)
　座標を表すＦＢ文字列（"50,100" など）をポイント型に変換。

●FN StrToRect (xCmdPtr&, theStr$, theRect)
　レクトを表すＦＢ文字列（"0,0,50,100" など）をレクト型に変換。
　構造体（レコード） theRect にレクトが入ります。
　予め DIM theRect.8 のように宣言して領域を確保しておきましょう。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN StrToRect (xCmdPtr&, @strPtr&, @rctPtr&)

●myTE& = FN GetFieldTE (xCmdPtr&, cardFldFlag&, fieldID&, fieldNum&, fieldName$)
　フィールドのＴＥハンドルのコピーを得る。
　cardFldFlag& はカードフィールドなら１、ＢＧフィールドなら０を指定。
　残りの fieldID&, fieldNum&, fieldNamePtr& はそれぞれフィールドＩＤ、
　フィールドナンバー、フィールド名を与えるが、前から順に優先順位があり、
　それぞれが０だった場合にその次のパラメータが有効になる。
　返値のＴＥハンドルは不要になったら破棄する必要があります。
　：関数定義の一行目を以下のように書き換えて下さい。
　：FN GetFieldTE (xCmdPtr&, cardFldFlag&, fieldID&, fieldNum&, @fieldNamePtr&)

●FN SetFieldTE (xCmdPtr&, cardFldFlag&, fieldID&, fieldNum&, fieldName$, fieldTE&)
　フィールドにＴＥの内容をセットする。
　cardFldFlag& から fieldName$ の各パラメータは GetFieldTE と同じ。
　fieldTE& はセットするデータの入ったテキストエディットハンドル。
　このＴＥの内容がフィールドにコピーされます。不要になったら破棄すること。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN SetFieldTE (xCmdPtr&, cardFldFlag&, fieldID&, fieldNum&, @fieldNamePtr&, fieldTE&)

ΘFN GetObjectName (xCmdPtr&, object&, @objName$)
　スクリプトエディタに関するユーティリティ。

ΘFN GetObjectScript (xCmdPtr&, object&, scriptHndl&)
　スクリプトエディタに関するユーティリティ。

ΘFN SetObjectScript (xCmdPtr&, object&, scriptHndl&)
　スクリプトエディタに関するユーティリティ。

●refNum& = FN StackNameToNum (xCmdPtr&, stackName$)
　スタックネームを与えるとそのスタックのリファレンスナンバーを返す。
　ホームの検索パスに見つからなかった場合はファイルダイアログが出ます。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN StackNameToNum (xCmdPtr&, @stackNamePtr&)

○FN Notify (xCmdPtr&)
　ハイパーカードが他のアプリの背面にある場合に、前面に出されるまで
　Ｘの動作を止めてアプリケーションメニューのミニアイコンを点滅させる。
　ハイパーカードが最前面にある時は無視されます。

●ans% = FN ShowHCAlert (xCmdPtr&, dlgID%, theStr$)
　theStr$ 文字列と共にダイアログを出す。
　dlgID% が１の場合は OK のみ、２なら OK Cancel、
　３なら Cancel Delete 、４なら Yes Cancel No のボタンが付きます。
　それぞれ一番左がデフォルトで、選んだボタン番号が返されます。
　：関数定義の一行目を以下のように書き換えて下さい。
　：LOCAL FN ShowHCAlert (xCmdPtr&, dlgID%, @promptStrPtr&)


　editing with windoids と 残りの script routines は、まず使うことは無いと思うので割愛します。external windows はＸでウィンドウを扱うときに必須なのですが、ちょっと検証作業がタイヘンだったのでこれも割愛します(^^;)
　下の２つはオマケです(^^;)

○FN HideHCPalettes (xCmdPtr&)
　ミニウィンドウ（ツール／パターンパレット、ビット表示、スクロール
　ウィンドウ、メッセージボックス）を全て隠す。Ｘを終了すると自動的に
　元に戻される。

○FN ShowHCPalettes (xCmdPtr&)
　HideHCPalettes で隠したウィンドウを元に戻す。



　HyperXcmd Glue.INCL ファイルの修正は以上です。

　次に、ここまで説明してきたグルールーチンを使う側の HyperXcmd.MAIN も修正します。
　３３行から以下のようなプログラムになっているので

 LONG IF prmCount% <> 0
   FOR j = 1 TO prmCount%                        'cycle thru parameters
     FN ZeroToPas (xCmdPtr&, j-1, @str255$(j-1)) 'converting all C-strings to
   NEXT                                          'Pascal strings
 END IF