Hook (Japanese) - mooz/keysnail GitHub Wiki

• トップ
• 使い方
• Tips
• カスタマイズ
• フック
• プラグインを入手
• プラグインを書く

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

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

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

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

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

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

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

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

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

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

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

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

hook.callHook("KeyBoardQuit", aEvent);

hook.callHook("PostCommand", hookArg);

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

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

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

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

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

ユーザが 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) に、このフックポイントへ登録された関数が呼ばれます。

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

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 として得たのち、画面へと表示しています。

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

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

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

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

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

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

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

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

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

        display.prettyPrint(url);
    }
});

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

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

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

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

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

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)]
    ];
// 以下省略

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

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

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

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

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

特に引数を渡しません。

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