TextMenu » ForDeveloper
Plugin の開発に関する情報です。
対応バージョンは、v0.2b です。
機能の概要
TextMenu は、ユーザーがテキストを選択したときに、テキストの内容に応じてコマンドをポップアップリストする機能です。
TextMenu は、本体内のプラグインを検索し、テキストを問い合わせて、動的にポップアップリストを表示します。
サンプル
サンプルを用意しました。CodeWarrior のプロジェクトです。
TextMenu02bSamplePlugin.zipプラグインの処理
プラグインは、少なくとも２つの処理を実装する必要があります。
1. 問い合わせ
ユーザーが文字列を選択すると、TextMenu はすべてのプラグインを呼び出します。プラグインから返ってきた文字列をポップアップリストで表示します。
プラグインは、渡されたテキストの内容に応じて、ポップアップリストに表示するラベルを返します。
2. 実行
ユーザーがリストを選択すると、TextMenu は 1. の処理で選ばれたプラグインを呼び出します。選択された文字列を、プラグインから返ってきた文字列で置き換えます。
プラグインは、渡されたテキストを処理し、置き換えるテキストを返します。
実装例
たとえば、選択文字列を英字の大文字に変換する機能を実装する場合は、下記のように実装します。
1. 問い合わせ
渡された文字列が小文字を含むか判定し、含む場合には、「大文字に変換」という文字列を返します。このときに、大文字に変換する処理は行いません。
もし、大文字に変換できる文字が含まれない場合には、「""」を返すことで、メニューに表示させないようさせます。
2. 実行
渡された文字列を大文字に変換処理して返します。
実装
ファイルタイプとクリエータタイプ
プラグインは、一般的な Palm アプリケーションと同じ方法で開発します。違うのは、ファイルタイプが、'CtMn' である点です。
クリエータは一つの機能（プラグイン）に対して、一つ取得してください（要登録）。
起動コード
PilotMain() の第１引数に渡されるコードです。
appTextMenuCommandQuery
メニューに項目を表示するかの問い合わせです。渡されたパラメータブロックには、ユーザーが選択した文字列が渡されています。この文字列を解析して、メニューに項目を追加する場合には、メニューに表示するラベルをパラメータブロックにコピーします。
このとき、空の文字列が渡される可能性があります。
appTextMenuCommandExecute
ユーザーがメニューで選択した時に呼び出されます。渡されたパラメータブロックには、ユーザーが選択した文字列が渡されています。この文字列に対して処理を行ってください。パラメータブロックに文字列をコピーすると、選択文字列をその文字列で置き換えます。
appTextMenuCommandAbout
ユーザーがプラグインの情報を見るときに呼び出されます。パラメータブロックには、何も渡されません。プラグインに関する情報のダイアログを表示してください。
パラメータブロック
PilotMain() の第２引数に渡されるメモリブロック（へのポインタ）です。
ここには、TextMenu から文字列が渡されます。また、このメモリブロックに文字列をコピーして、TextMenu に結果を返します。
このメモリブロックのサイズは、TEXT_BUF_LEN のサイズで TextMenu 側で確保されています。したがって、このサイズを超えるコピーや、メモリの開放などは行わないでください。
ユーザーインタフェースの観点でも、メニューに表示する文字列は、短めが好ましいです。
渡す文字列の内容によって、動作が変わります。
appTextMenuCommandQuery（メニューに表示する文字列）
- ""（空文字）
- メニューに表示しません。
- 上記以外
- メニューに表示します。
NULL は指定しないでください（予約）
appTextMenuCommandExecute（選択文字列を置き換える文字列）
- ""（空文字）
- 選択文字列を消去します。
- 上記以外
- 選択文字列を置き換えます。
NULL は指定しないでください（予約）
戻り値
PilotMain() の戻り値によって、プラグイン実行後の状態を指定できます。
appTextMenuPluginResultNormal
通常この値を返します。このとき、選択されたテキストは、パラメータブロックで渡される文字列に置き換わります。選択状態は解除されます。
appTextMenuPluginResultNoPaste
この値を返すと、文字列の置き換えを行いません。 テキストフィールドは選択状態のままです。
プラグイン情報
プラグイン名
プラグイン名は、リソースの tAIN（アプリケーション名と同じ）を参照します。tAIN リソースが存在しない場合は、データベース名をプラグイン名とします。
プラグイン名は、設定画面のリストに表示されます。
情報（About）ダイアログ
起動コード appTextMenuCommandAbout で、そのプラグインの情報を表示してください。１つのダイアログを表示する程度の処理を推奨します。
その他注意事項
- サブルーチンコールなので、その制約が適用されます。
- 第１セグメントを越えるコードは記述できません。
- スタティック変数、グローバル変数は使用できません。
- 各起動コード内の処理は、他と依存しないようにしてください。
- 起動コードの呼び出し順序やタイミングは保証していません。
- 処理はなるべく軽くしてください。特に、問い合わせに対する応答は早くしてください。
ヘッダファイルの内容
正しくは、サンプルに含まれているヘッダファイルを参照してください。
///
/// プラグインのタイプ
/// プラグインは、このタイプを指定してください。
///
#define PLUGIN_TYPE ('CtMn')
///
/// 選択文字列を保持するバッファの大きさ
///
/// PilotMain の第２引数に渡されるメモリブロックの
/// 大きさです。このサイズ以上の書き込みはしないでください。
///
#define TEXT_BUF_LEN (256)
///
/// v0.2b から使用禁止にしました。
///
/// #define PLUGIN_HELP_STRING_ID (1000)
///
/// 起動コード
///
/// プラグインはここで指定される起動コードで呼び出されます。
///
typedef enum {
appTextMenuCommandQuery = sysAppLaunchCmdCustomBase+1,
appTextMenuCommandExecute,
appTextMenuCommandAbout
} TextMenuCommandType;
///
/// 戻り値
///
/// PilotMain の戻り値です。
///
typedef enum {
appTextMenuPluginResultNormal = 0,
appTextMenuPluginResultNoPaste
} TextMenuPluginResultType;
