Hook japanese

mooz edited this page Oct 26, 2010 · 1 revision

はじめに

以下に示すコードの動作を確認する為には Eval コマンドが役に立ちます。

M-: (Alt + : など) と入力し、開いたプロンプトにコードを打ち込み Enter キーを押す。 Eval コマンドは開発者の良き友です。

詳しい説明に関しては このページ を参照してください。

フックについて

KeySnail のフックシステムを利用すると、プログラムの様々な部分に設けられたフックポイントへ関数を割り当てておくことが可能となります。また、プラグインなどがフックを独自に用意することもできます。

例えば KeyPress フックへ関数を登録する場合は .keysnail.js の末尾へ次のようなコードを記述します。

hook.addToHook("KeyPress",
               function (aKey) {
                   display.prettyPrint(aKey + " pressed");
               });

このようにしておくと、ユーザがキーを入力する度に display.prettyPrint(aKey + " pressed") が実行されるようになります。ここでは入力されたキーの名前を画面へ表示しています。

フックポイントへの関数割り当てには addToHooksetHook を用います。両者とも取る引数は同じですが、 addToHook がフックポイントの末尾へ関数を追加するのに対し、 setHook はそれまでにフックポイントへ登録された関数全てを消去した後に関数登録を行います。

ゆえに、プラグイン内でフック登録を行う場合は必ず addToHook を使うようにしてください。

フックポイントの提供

プラグインは、とてもシンプルな方法で独自のフックポイントを用意することが可能です。

フックポイントとしたい場所に hook.callHook("フックポイント名", 引数) の一行を記述して下さい。こうしておくことで、そのフックポイントに割り当てられた関数へ引数が渡され、実行されます。

例えば KeySnail 内部の key モジュールでは、次のようにしてフックポイントが提供されています。

hook.callHook("KeyBoardQuit", aEvent);
hook.callHook("PostCommand", hookArg);

この例を見て分かるように、各フックポイントによって関数に渡される引数は異なります。以下に記された説明を参考にしてください。

KeyPress

呼ばれるタイミング

ユーザがキーを入力する度にこのフックへ登録された関数が呼ばれます。

引数

このフックへ登録された関数には キーイベント が渡されます。

使用例

hook.addToHook("KeyPress",
               function (aKey) {
                   display.prettyPrint(key.keyEventToString(aKey) + " pressed");
               });

aKey には入力されたキーのキーイベントが渡るので、ここではそれを文字列形式へ変換し、画面へと表示しています。

KeyBoardQuit

呼ばれるタイミング

ユーザが key.quitKey (デフォルトは C-g) を入力した際に呼ばれます。

引数

このフックへ登録された関数には キーイベント が渡されます。

使用例

hook.setHook('KeyBoardQuit', function (aEvent) {
    if (key.currentKeySequence.length)
        return;

    command.closeFindBar();

    if (util.isCaretEnabled())
        command.resetMark(aEvent);
    else             
        goDoCommand("cmd_selectNone");

    if (KeySnail.windowType == "navigator:browser")
        key.generateKey(aEvent.originalTarget, KeyEvent.DOM_VK_ESCAPE, true);
});

これは多くのユーザの .keysnail.js へ実際に記述されているであろう設定です。通常の方法では key.quitKey にコマンドを割り当てることができないため、このようにしてフックポイントへとコマンドを登録することで、対応しています。

PreCommand, PostCommand

呼ばれるタイミング

キーに割り当てられたコマンドが呼ばれる前 (PreCommand) と呼ばれた後 (PostCommand) に、このフックポイントへ登録された関数が呼ばれます。

引数

このフックへ登録された関数には次のようなオブジェクトが渡されます。

var hookArg = {
            func  : aFunc,
            event : aEvent,
            arg   : aArg
        };

func には コマンド本体 (関数) が、 event には キーイベント が、 arg には 前置引数 がそれぞれ格納されます。

特別な動作

PreCommand フックへ割り当てられた関数内で例外を投げると、そのコマンドの実行をキャンセルすることが可能です。

使用例

hook.addToHook("PostCommand",
               function (aHookArg) {
                   var func = aHookArg.func;
                   display.prettyPrint(func.ksDescription + " executed");
               });

ここでは aHookArg.func として「コマンド本体」を入手し、そのコマンドの説明を func.ksDescription として得たのち、画面へと表示しています。

ClipboardChanged

呼ばれるタイミング

クリップボードの内容が変化したとき (ユーザがテキストをコピーしたとき) に呼ばれます。

引数

ユーザがコピーしたテキストの内容 が渡ります。

特別な動作

PreCommand フックへ割り当てられた関数内で例外を投げると、そのテキストは KeySnail のキルリングへ格納されません。

使用例

hook.addToHook("ClipboardChanged",
               function (aText) {
                   util.alert("Clipboard Changed!", aText + " copied");
               });

ここでは新しくコピーされたテキストの内容を、ダイアログ表示しています。

LocationChange

呼ばれるタイミング

ロケーションバーの値が変化したとき、つまりページがロードされた際やタブが切り替わった際に呼ばれます。

引数

ロードされたページ、切り替わったタブのページの URI が格納されたオブジェクトが渡ります。

文字列としての URL は spec プロパティに格納されています。

使用例

hook.addToHook('LocationChange', function (aNsURI) {
    if (aNsURI || aNsURI.spec) {
        var url = aNsURI.spec;

        display.prettyPrint(url);
    }
});

この例では、タブが切り替わった際などにスクリーンの右上へその URL を表示しています。

GreaseMonkey のように、特定のサイトに対する処理を行いたい場合に便利でしょう。

PluginLoaded

呼ばれるタイミング

全プラグインのロードが終わった際に呼ばれます。

引数

このフックは特に引数を渡しません。

使用例

このフックはプラグイン内でから他のプラグインの値を利用したり、上書きする際に有用です。

KeySnail は次のような順番でプラグインをロードします。

  1. 名前が _ で始まるプラグイン (ライブラリ)
  2. 初期化ファイル (.keysnail.js)
  3. 各プラグインを名前順にロード

その為、フェーズ 3 の「各プラグイン」内で他のプラグインの値を利用したり上書きしようとすると、対象となるプラグインがそのプラグインより先にロードされている保証がないため (もちろん名前を変更することで順番を操作することは可能ですが) うまくいきません。

ここで PluginLoaded フックの出番です。このフックへ登録された関数は、先ほどのリストでいうと次のような位置で呼ばれます。

  1. 名前が _ で始まるプラグイン (ライブラリ)
  2. 初期化ファイル (.keysnail.js)
  3. 各プラグインを名前順にロード
  4. PluginLoaded に登録された関数の実行

PluginLoaded に登録された関数が呼ばれる時点では各プラグインのロードが終わっているため、安心してプラグインの値を使用したり変更したりすることが出来るというわけです。

例えば Caret hint プラグインでは HoK プラグインの拡張ヒントモードアクションの値を上書きする為に、このフックへ関数を登録しています。

hook.addToHook('PluginLoaded', function () {
    if (!plugins.hok)
        return;

    var actions = [
        [headMode, M({ja: "キャレットを要素の先頭へ移動", en: "Move caret to the head of the selected element"}),
         function (e) moveCaret(e, true, false)],
        [tailMode, M({ja: "キャレットを要素の末尾へ移動", en: "Move caret to the tail of the selected element"}),
         function (e) moveCaret(e, false, false)],
        [selectHeadMode, M({ja: "要素を選択してキャレットを先頭へ移動", en: "Select element and move caret to the head"}),
         function (e) moveCaret(e, false, true)],
        [selectTailMode, M({ja: "要素を選択してキャレットを末尾へ移動", en: "Select element and move caret to the tail"}),
         function (e) moveCaret(e, false, true)]
    ];
// 以下省略

Unload

呼ばれるタイミング

Firefox のメインウィンドウが閉じられる際に呼ばれます。

引数

このフックは特に引数を渡しません。

使用例

このフックに登録された関数はデストラクタのように振る舞ってくれます。プラグインの後処理などを行いたい場合に便利でしょう。

バージョン

Unload フックは KeySnail 1.1.8 から用意されています。

KeySnailInitialized

呼ばれるタイミング

KeySnail の初期化が終了した際に呼ばれます。

引数

特に引数を渡しません。

バージョン

Unload フックは KeySnail 1.3.2 から用意されています。

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.