X Wheel Plug-In version 1.1 (第2版)

全プラグイン共通

X Wheel Plug-Inの拡張子はxwpiです。

全てのプラグインで GetPluginType, GetPluginVersion, GetPluginText, InitializePlugin を実装して下さい。 必要であれば InitializePlugin2 を実装して下さい。

InitializePlugin と InitializePlugin2 の関係については InitializePlugin2 の解説を参考にして下さい。

DWORD XWPLUGINAPI GetPluginType(VOID);

プラグインが実装している機能を調べるのに使われます。

パラメータ

この関数はパラメータをとりません。

戻り値

プラグインのタイプを示す DWORD 値を返します。次の値の組み合わせです。

定数	意味
PLUGIN_TYPE_LANGUAGE	言語プラグインです。これに限り単独で指定して下さい。
PLUGIN_TYPE_HASSETTING	設定ダイアログを持っています。
PLUGIN_TYPE_ACTION	アクションプラグイン機能を実装しています。

DWORD XWPLUGINAPI GetPluginVersion(VOID);

バージョン情報の取得に使われます。

パラメータ

この関数はパラメータをとりません。

戻り値

バージョン情報を含む32ビット符号無し整数を返します。 そのうち上位16ビットがそのプラグインが準拠するX Wheel Plug-In規格のバージョン、 下位16ビットがプラグイン自体のバージョン情報を表します。

戻り値の作成には MAKEVERSIONDWORD マクロを使うと便利です。

上位← 8bits	8bits	8bits	8bits →下位
X Wheel Plug-In メジャーバージョン	X Wheel Plug-In マイナーバージョン	プラグイン メジャーバージョン	プラグイン マイナーバージョン

UINT XWPLUGINAPI GetPluginText(UINT uType, LPWSTR lpString, UINT uSize, WORD wLanguageId);

プラグインに関するテキストを取得するのに使われます。 指定された言語識別子がサポート外の物であった場合はエラーを返すのではなく、言語依存しないアルファベット文字列を格納すべきです。

パラメータ

uType [in]

プラグインに関するどういったテキストを返すかを表す UINT 値が指定されます。

定数	返すべきテキスト
PLUGIN_TEXT_NAME	プラグイン名
PLUGIN_TEXT_VERSION	バージョンを表す文字列
PLUGIN_TEXT_DESCRIPTION	プラグインの説明
PLUGIN_TEXT_COPYRIGHT	著作権情報
PLUGIN_TEXT_SUPPORTURL	サポートURL
PLUGIN_TEXT_SUPPORTMAILADDRESS	サポートE-Mailアドレス

lpString [out]

指定されたテキストを格納するバッファが指定されます。

uSize [in]

lpString が指すバッファのサイズがワイド文字数の単位で指定されます。 指定されたテキストのうちこのサイズを超える部分は切り捨てます。 0 が指定された場合は、必要なバッファのサイズ(終端null文字含む)をワイド文字数で返し、lpString が指すバッファは使ってはいけません。

wLanguageId [in]

現在選択されている言語が指定されます。 この値は MAKELANGID マクロが返す値と同じ形式です。

戻り値

uSize に 0 以外の値が指定され、関数が成功した場合は、lpString が指すバッファに書き込まれたワイド文字の数(終端null文字含まず)を返します。 uSize に 0 が指定され、関数が成功した場合は、文字列を受け取るバッファに必要なサイズ(終端null文字含む)をワイド文字数で返します。 関数が失敗すると、0 を返します。

BOOL XWPLUGINAPI InitializePlugin(LPFNOUTPUTMESSAGE lpfnOutputMessage, WORD wLanguageId);

プラグインを初期化します。 DllMain で行うわけにいかない、DLLのロードやファイルアクセス等の処理を行います。

パラメータ

lpfnOutputMessage [in]

プラグインが使用するメッセージ出力関数のポインタが指定されます。 この関数はプラグインのどこからでも使用することができます。 関数の詳細は OutputMessage を参照。

wLanguageId [in]

通常のプラグインでは現在選択されている言語が指定されます。 この値は MAKELANGID マクロが返す値と同じ形式です。

言語プラグインでは常に 0 が指定されます。 これはこの関数が呼ばれた時点ではまだ使用する言語が確定していないためです。

戻り値

初期化が成功すれば TRUE、それ以外は FALSE を返します。 FALSEが返ってきた場合、再起動されるまでそのプラグインを使用しません。 これを利用して、OS 等の条件でプラグインの使用を禁止することも出来ます。

BOOL XWPLUGINAPI InitializePlugin2(LPFNOUTPUTMESSAGE lpfnOutputMessage, WORD wLanguageId, INT nCaller);

- 1.1で追加されました -

プラグインを初期化します。 DllMain で行うわけにいかない、DLLのロードやファイルアクセス等の処理を行います。

この関数は必ず実装する必要はありません。

X Wheelがプラグインバージョン1.1に対応している場合、 プラグインが GetPluginVersion でプラグイン規格1.1以上であると返し、かつ InitializePlugin2 が実装されていれば InitializePlugin2 が呼び出され、InitializePlugin は呼び出されません。 それ以外の場合はInitializePluginが呼び出されます。

パラメータ

lpfnOutputMessage [in]

プラグインが使用するメッセージ出力関数のポインタが指定されます。 この関数はプラグインのどこからでも使用することができます。 関数の詳細は OutputMessage を参照。

wLanguageId [in]

通常のプラグインでは現在選択されている言語が指定されます。 この値は MAKELANGID マクロが返す値と同じ形式です。

言語プラグインでは常に 0 が指定されます。 これはこの関数が呼ばれた時点ではまだ使用する言語が確定していないためです。

nCaller [in]

プラグインがどこから呼ばれたかを示すINT値が指定されます。 取りうる値は以下の通りです。

定数	呼び出したモジュール
CALLER_X_WHEEL	X Wheel 本体
CALLER_MOUSE_PROPERTY	マウスのプロパティ

戻り値

初期化が成功すれば TRUE、それ以外は FALSE を返します。 FALSEが返ってきた場合、再起動されるまでそのプラグインを使用しません。 これを利用して、OS 等の条件でプラグインの使用を禁止することも出来ます。

BOOL XWPLUGINAPI UninitializePlugin(WORD wLanguageId, INT nCaller);

- 1.1で追加されました -

プラグインの解放処理をします。 X Wheel が不正終了した場合は当然この関数は呼び出されないので、他プロセスと連動している場合はこの関数だけをトリガーにするのではなく、 X Wheel 自体の存在も監視するようにして下さい。

この関数は必ず実装する必要はありません。

X Wheelがプラグインバージョン1.1に対応している場合、プラグインにUninitializePluginが実装されていれば呼び出されます。 X Wheelがプラグインバージョン1.1に対応していない場合、UninitializePluginは呼び出されないので注意して下さい。

パラメータ

wLanguageId [in]

現在選択されている言語が指定されます。 この値は MAKELANGID マクロが返す値と同じ形式です。

nCaller [in]

プラグインがどこから呼ばれたかを示すINT値が指定されます。 取りうる値は以下の通りです。

定数	呼び出したモジュール
CALLER_X_WHEEL	X Wheel 本体
CALLER_MOUSE_PROPERTY	マウスのプロパティ

戻り値

プラグインバージョン 1.1 では常に TRUE を返します。

言語プラグイン

言語プラグインはX Wheel NT専用です。 また、アクションプラグイン等の他の機能を同時に実装することは出来ません。

言語プラグインでは以下の関数を実装して下さい。

WORD XWPLUGINAPI GetLanguageId(VOID);

対応している言語識別子を取得する際に呼ばれます。

パラメータ

この関数はパラメータをとりません。

戻り値

言語識別子を返します。 一般的に MAKELANGID マクロが使用されます。

DWORD XWPLUGINAPI GetLanguageVersion(VOID);

対応しているX Wheel NTのバージョンを取得する際に呼ばれます。

パラメータ

この関数はパラメータをとりません。

戻り値

バージョンを表す DWORD 値を返します。 通常は Language.h で定義されている LANGUAGE_VERSION を返します。

設定ダイアログ

設定ダイアログを持つプラグインでは以下の関数を実装して下さい。

VOID XWPLUGINAPI SettingDialog(HWND hParent, WORD wLanguageId);

プラグインの設定ダイアログを出す際に呼び出されます。 この中で設定ダイアログを出して下さい。

パラメータ

hParent [in]

ダイアログの親ウィンドウが指定されます。

wLanguageId [in]

現在選択されている言語が指定されます。 この値は MAKELANGID マクロが返す値と同じ形式です。

戻り値

この関数は戻り値を返しません。

アクションプラグイン

アクションプラグインによって、カスタムアクションをキーボード・マウスのインプット以外にも拡張することが出来ます。

アクションプラグインでは以下の関数を実装して下さい。

BOOL XWPLUGINAPI Action(DWORD dwNumberParam, LPCWSTR lpStringParam, LPCWSTR lpProgramPath, BOOL fButtonDown, WORD wLanguageId);

アクションを実行します。 この関数が制御を返すまで、X Wheelは待機し続けます。 出来る限り短い時間で制御を返すようにして下さい。

この関数内でエラーが発生した場合、メッセージボックス等を出さないで OutputMessage 関数を使用してください。 プラグインが使用する OutputMessage 関数は InitializePlugin 関数で指定されます。

パラメータ

dwNumberParam [in]

プラグイン定義の数値パラメータが指定されます。

lpStringParam [in]

プラグイン定義の文字列パラメータが指定されます。

lpProgramPath [in]

対象となったプログラムのパスが指定されます。 個別の設定ではなくデフォルトで呼ばれたのであれば NULL が指定されます。

fButtonDown [in]

ボタンダウン時アクションならば TRUE、そうでなければ FALSE が指定されます。

wLanguageId [in]

現在選択されている言語が指定されます。 この値は MAKELANGID マクロが返す値と同じ形式です。

戻り値

関数が成功すれば TRUE、それ以外は FALSE を返します。 FALSEが返ってきた場合、X Wheelはカスタムアクションの残りのアクションをキャンセルします。

UINT XWPLUGINAPI GetActionSummary(DWORD dwNumberParam, LPCWSTR lpStringParam, BOOL fButtonDown, LPWSTR lpString, UINT uSize, WORD wLanguageId);

アクションリストに表示する文字を取得する際に使用されます。

パラメータ

dwNumberParam [in]

アクションの数値パラメータが指定されます。

lpStringParam [in]

アクションの文字列パラメータが指定されます。

fButtonDown [in]

ボタンダウン時アクションならば TRUE、そうでなければ FALSE が指定されます。

lpString [out]

アクションリストに表示する文字を受け取るバッファが指定されます。

uSize [in]

lpString が指すバッファのサイズがワイド文字数の単位で指定されます。 設定すべき文字列のうちこのサイズを超える部分は切り捨てます。 0 が指定された場合は、必要なバッファのサイズ(終端null文字含む)をワイド文字数で返し、lpString が指すバッファは使ってはいけません。

wLanguageId [in]

現在選択されている言語が指定されます。 この値は MAKELANGID マクロが返す値と同じ形式です。

戻り値

uSize に 0 以外の値が指定され、関数が成功した場合は、lpString が指すバッファに書き込まれたワイド文字の数(終端null文字含まず)を返します。 uSize に 0 が指定され、関数が成功した場合は、文字列を受け取るバッファに必要なサイズ(終端null文字含む)をワイド文字数で返します。 関数が失敗すると、0 を返します。

BOOL XWPLUGINAPI AddActions(LPFNREGISTACTIONS lpfnRegistActions, WORD wLanguageId);

『カスタムアクションの編集』ダイアログの追加メニューを作成する際に使用されます。

パラメータ

lpfnRegistActions [in]

『カスタムアクションの編集』ダイアログの追加メニューに項目を追加する関数のポインタが指定されます。 この関数の詳細は RegisterActions を参照。

wLanguageId [in]

現在選択されている言語が指定されます。 この値は MAKELANGID マクロが返す値と同じ形式です。

戻り値

成功すれば TRUE を、そうでなければ FALSE を返します。

INT XWPLUGINAPI EditAction(HWND hParent, DWORD dwNumberParam, LPCWSTR lpStringParam, BOOL fButtonDown, LPFNSETACTIONPARAM lpfnSetActionParam, WORD wLanguageId);

アクションの詳細を設定する際に呼び出される関数です。 『カスタムアクションの編集』ダイアログで追加や編集をする際に呼ばれます。 通常はダイアログを作ることになりますが、 必要でない場合はダイアログを作る必要はありません。

パラメータ

hParent [in]

ダイアログの親ウィンドウが指定されます。

dwNumberParam [in]

アクションの数値パラメータが指定されます。

lpStringParam [in]

アクションの文字列パラメータが指定されます。

fButtonDown [in]

ボタンダウン時アクションならば TRUE、そうでなければ FALSE が指定されます。

lpfnSetActionParam [in]

アクションのパラメータを設定する SetActionParameter 関数のポインタが指定されます。

wLanguageId [in]

現在選択されている言語が指定されます。 この値は MAKELANGID マクロが返す値と同じ形式です。

戻り値

設定するのであれば EDITACTION_OK を、キャンセルするのであれば EDITACTION_CANCEL を返します。

ウィンドウメッセージ

WM_UNLOADPLUGIN

何らかの理由により、プラグインをアンロードする際にX Wheelによりブロードキャストされます。

X Wheel以外がX Wheel Plug-Inを使っている場合に不具合が起きるため、WM_UNLOADPLUGINは使われなくなりました。 1.1規格のPlug-Inであっても使わないようにしてください。

構造体

typedef struct tagREGISTACTION{
    LPCWSTR lpMenuString;
    DWORD   dwDefNumberParam;
    LPCWSTR lpDefStringParam;
} REGISTACTION, *LPREGISTACTION;

lpMenuString

メニューに使われる文字列を指定します。

dwDefNumberParam

アクションの数値バラメータの初期値を指定します。

lpDefStringParam

アクションの文字列バラメータの初期値を指定します。

マクロ

MAKEVERSIONDWORD(xwplugin_major, xwplugin_minor, dll_major, dll_minor)

一般プラグインがGetPluginVersion 関数で返すバージョン情報 DWORD 値を作ります。

パラメータ

xwplugin_major

対象としているX Wheel Plug-In規格のメジャーバージョン

xwplugin_minor

対象としているX Wheel Plug-In規格のマイナーバージョン

dll_major

プラグイン自体のメジャーバージョン

dll_minor

プラグイン自体のマイナーバージョン

X Wheel 側の関数

X Wheel 側の関数です。 直接呼び出すことは出来ません。

BOOL XWAPI OutputMessage(UINT uMessageType, LPCWSTR lpMessage);

プラグインからのメッセージを出力します。

パラメータ

uMessageType [in]

出力するメッセージの種類を指定します。 以下いずれかです。

定数	uMessageType の値
MESSAGE_ERROR	エラーメッセージです。 エラーログに出力されます。 設定によってはポップアップでも表示されます。
MESSAGE_DEBUG	デバッグ用メッセージです。 あくまで開発用であり、公開するバージョンでは使用しないでください。 X Wheelはそのままではデバッグログを出力しません。 デバッグログを有効にするには、レジストリの HKEY_CURRENT_USER\SOFTWARE\Absurd Technology Lab\X Wheel キーの DWORD値 OutputDebugLog を 0 以外にしてください。

lpMessage [in]

出力するメッセージ文字列を指定します。

戻り値

関数が成功すれば TRUE が、そうでなければ FALSE が返ります。

BOOL XWAPI RegisterActions(const LPREGISTACTION lpActions, DWORD dwCount);

『カスタムアクションの編集』ダイアログの追加メニューに項目を追加します。

パラメータ

lpActions [in]

複数の REGISTACTION 構造体からなる 1 つの配列へのポインタを指定します。

dwCount [in]

lpActions で指定した配列の要素数を指定します。

戻り値

関数が成功すれば TRUE が、そうでなければ FALSE が返ります。

BOOL XWAPI SetActionParameter(UINT uParamType, LPVOID lpParam);

アクション実行時に渡されるパラメータを指定します。

パラメータ

uParamType [in]

設定するパラメータの種類を指定します。 以下いずれかです。

定数	lpParam の値
ACTIONPARAM_NUMBER	DWORD 値の変数へのポインタ
ACTIONPARAM_STRING	ワイド文字列のポインタ

lpParam [in]

設定するパラメータを格納したアドレスを指定します。

戻り値

関数が成功すれば TRUE が、そうでなければ FALSE が返ります。

資料