Now browsing the archives for 8月, 2010.

Jetpack SDK 0.7 の Panel API

Jetpack SDK 0.7 では新たに Panel API が追加され、HTMLで記述されたGUIを表示可能なパネル型UIを追加するこが可能になりました。 Widget API で追加したボタン型UIと連携して、ボタンをクリックするとパネルを開くことも可能です。

基本的な使い方

Panel API を使うためには、まず panel モジュールをインポートします。なお、本記事のサンプルスクリプトでは exports.main の記載などを省略しています。

var panels = require("panel");

次に、 Panel コンストラクタを使ってパネル型UIを作ります。引数には、色々なプロパティを有するオブジェクトを渡します。下記の例では 幅200、高さ150ピクセルのパネル上に指定したURLをロードします。

var myPanel = panels.Panel({
    width : 200,
    height: 150,
    contentURL: "http://www.example.com/",
});

Panel コンストラクタで生成した panel オブジェクトの show メソッドを呼び出すと、パネルを開くことができます。メソッドの引数に何も指定しない場合は親ウィンドウの中央にパネルが開かれます。

myPanel.show();

widget API の Widget コンストラクタの引数オブジェクトの panel プロパティに panel オブジェクトをセットすることで、ボタン型UIをクリックしてパネルを開くこともできます。

const widgets = require("widget");
var button = widgets.Widget({
    label: "Test",
    image: "chrome://browser/skin/Secure24.png",
    panel: myPanel
});
widgets.add(button);

パネル型UIへ自前のHTMLをロードする

self API を使うと、パッケージの data フォルダ内に格納した自前のHTMLをパネル型UIへロードすることができます。

data/panel.html
<html>
<body>
    <p>Jetpack</p>
    <button onclick="say('Hello');">Say Hello</button>
    <button onclick="say('Bye');">Say Bye</button>
</body>
</html>
lib/main.js
const self = require("self");
var myPanel = panels.Panel({
    width : 200,
    height: 150,
    contentURL: self.data.url("panel.html"),
});

パネル型UIへコンテントスクリプトをロードする

引き続き、上記のパネルに配置されたボタンをクリックした際に、 Jetpack SDK の notifications API を使って通知を表示させるようにします。パネル型UIにロードされたHTMLからは直接 notifications API を呼び出すことはできず、2つの JavaScript コンテキスト間でメッセージを受け渡す、少し回りくどいやり方となります。

まず、 Panel コンストラクタの引数オブジェクトへ contentScriptURL プロパティを追加し、 self API を使って data フォルダ内に格納した panel.js のURLを配列で指定します。また、 contentScriptWhen プロパティに “ready” という値を指定することで、パネル内のHTMLロード完了時にスクリプトが実行されるようになります。

lib/main.js
const self = require("self");
var myPanel = panels.Panel({
    width : 200,
    height: 150,
    contentURL: self.data.url("panel.html"),
    contentScriptURL: [self.data.url("panel.js")],
    contentScriptWhen: "ready",
});

contentScriptURL プロパティによって読み込まれるスクリプト(コンテントスクリプト)は、HTMLに<script>タグで記述したスクリプトと異なる特殊な JavaScript コンテキストで実行されます。そのため、HTMLの window オブジェクトにアクセスするには明示的に window. とする必要があります。以下の例では window オブジェクト直下に say という関数を追加し、 button 要素の onclick 属性から呼び出し可能にしています。また、コンテントスクリプトでは特殊な変数 panel の sendMessage メソッドによって main.js 側の JavaScript コンテキストへ文字列(あるいはJSON文字列化可能なオブジェクトなど)を送ることができます。

data/panel.js
window.say = function(text) {
    panel.sendMessage(text);
};

panel オブジェクトの sendMessage で送られた文字列(あるいはJSON文字列化可能なオブジェクトなど)は、 main.js 側の JavaScript コンテキスト内の panel オブジェクトの onMessage コールバック関数によって受け取ることができます。以下の例では受け取った文字列を notifications API を使って通知として表示します。

lib/main.js
const self = require("self");
var myPanel = panels.Panel({
    width : 200,
    height: 150,
    contentURL: self.data.url("panel.html"),
    contentScriptURL: [self.data.url("panel.js")],
    contentScriptWhen: "ready",
    onMessage: function(message, callback) {
        require("notifications").notify({
            title: "Message from Panel",
            text: message
        });
    }
});

Panel

TOP

Jetpack SDK 0.7 の Notifications API

Jetpack SDK 0.7 では新たに Notifications API が追加され、Firefox のダウンロード完了通知などでお馴染みのスライド式の通知UIを表示することが可能になりました。 Notifications API を使うためには、まず notifcations モジュールをインポートします。

const notifications = require("notifications");

通知を表示するためには notify メソッドを呼び出します。引数には、以下のプロパティを有するオブジェクトを渡します。

プロパティ 概要
title
text
通知に表示する文字列。
iconURL 通知に表示する画像のURL。 self APIを使って自パッケージ内の data フォルダに格納した画像を指定することも可能。
data onClick の引数として渡される文字列。
onClick 通知をクリックした際の処理。引数に data プロパティの値が渡される。
notifications.notify({
    title: "Jetpack",
    text: "This is a notification.",
    iconURL: "chrome://browser/skin/Geolocation-64.png",
    data: "test",
    onClick: function(data) {
        console.log(data);
    },
});

notification

TOP

Jetpack SDK 0.7 の Clipboard API

Jetpack SDK 0.7 では新たに Clipboard API が追加され、クリップボードへのコピー、およびコピーされたデータの取得が可能になりました。 Clipboard API を使うためには、まず clipboard モジュールをインポートします。

const clipboard = require("clipboard");

クリップボードへのコピー

クリップボードへ文字列をコピーするには、 set メソッドを使います。

clipboard.set("hello");

set メソッドの第2引数へデータ形式を指定して、HTMLソースをコピーすることも可能です。現在対応しているデータ形式は text, html のみですが、将来的には画像やファイルなどの形式にも対応するようです。第2引数を省略した場合は text 形式となります。

clipboard.set("<em>hello</em>", "html");

クリップボード内のデータ取得

クリップボード内のデータを取得するには、 get メソッドを使います。

var data = clipboard.get();

第2引数へデータ形式を指定した場合、その形式のデータを取得できます。第2引数を省略した場合は text 形式となります。

var data = clipboard.get("html");

クリップボード内のデータ形式を調べる

現在クリップボードへコピーされているデータの形式を調べるには、 currentFlavors プロパティを使います。データ形式はひとつとは限りませんので、戻り値は配列となります。

var types = clipboard.currentFlavors;

TOP

nsITransactionManager を使ったトランザクション管理

拡張機能やXULアプリにて、ユーザの操作に対する「元に戻す」「やり直し」機能を実装する際、 nsITransactionManager が便利です。例えば Firefox 本体ではブックマークの追加/削除/移動などが nsITransactionManager によってトランザクション管理されています。

基本形

ユーザがボタンをクリックすると、金額が加算されて合計金額がテキストボックスに表示されるような、簡単なXULアプリを作ってみます。

bank.xul
<?xml version="1.0"?>

<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>

<page xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
      title="Bank" onload="init();">

    <script type="application/x-javascript" src="bank.js" />

    <textbox id="total" />
    <hbox>
        <button label="Deposit $1"   oncommand="deposit(1);" />
        <button label="Deposit $10"  oncommand="deposit(10);" />
        <button label="Deposit $100" oncommand="deposit(100);" />
    </hbox>

</page>

引き続き JavaScript で機能を実装します。合計金額を gTotalMoney というグローバル変数に保持し、合計金額をテキストボックスに表示するための updateUI 関数を作っておきます。 onload イベント発生時に呼び出される init 関数では、 updateUI で合計金額の初期値「$0」を表示します。
ボタンをクリックしたときに呼び出される deposit 関数では、引数に渡された金額を gTotalMoney に加算した後、 updateUI で合計金額の表示を更新します。

bank.js
var gTotalMoney = 0;

function init() {
    updateUI();
}

function updateUI() {
    document.getElementById("total").value = "$" + gTotalMoney.toString();
}

function deposit(aMoney) {
    gTotalMoney += aMoney;
    updateUI();
}

トランザクション管理

では、上記のアプリでボタンをクリックした後、その処理を元に戻す/やり直しできるようにします。

はじめに、一連のトランザクションを管理するための nsITransactionManager インスタンスであるグローバル変数 gTxnManager およびその初期化処理を追加します。

bank.js
var gTotalMoney = 0;
var gTxnManager;

function init() {
    gTxnManager = Components.classes["@mozilla.org/transactionmanager;1"].
                  createInstance(Components.interfaces.nsITransactionManager);
    updateUI();
}

トランザクション管理をして元に戻す/やり直し可能にするためには、個々の処理を nsITransaction インタフェースを実装したオブジェクトとして記述する必要があります。今回の場合は預金処理を表す DepositTxn クラスを以下のような設計で作ります。

メンバ 概要
_money コンストラクタの引数に渡された金額を内部的に保持するためのプロパティ。
doTransaction このトランザクションを実行する際に呼び出されるメソッド。
合計金額へ _money 分だけ加算する。
undoTransaction このトランザクションを元に戻す際に呼び出されるメソッド。
合計金額から _money 分だけ減算する。
redoTransaction このトランザクションをやり直しする際に呼び出されるメソッド。
通常は doTransaction と同じ処理を実行すればよい。
merge
isTransient
詳細不明。
function DepositTxn(aMoney) {
    this._money = aMoney;
}

DepositTxn.prototype = {
    doTransaction  : function() { gTotalMoney += this._money; },
    undoTransaction: function() { gTotalMoney -= this._money; },
    redoTransaction: function() this.doTransaction(),
    merge: function() false,
    get isTransient() false,
};

deposit 関数を書き換えて、合計金額を直接変更する代わりに、預金処理トランザクションクラスのインスタンスを生成して gTxnManagerdoTransaction メソッドへ渡します。こうすることで、内部的に DepositTxn インスタンスの doTransaction が呼び出されて合計金額への加算が行われ、なおかつその処理が元に戻す処理のスタックへ追加され、必要に応じて元に戻すことが可能となります。

function deposit(aMoney) {
    var txn = new DepositTxn(aMoney);
    gTxnManager.doTransaction(txn);
    updateUI();
}

次に、アプリのUIへ元に戻す/やり直しするためのボタンを追加します。

bank.xul
    <hbox>
        <button id="undoButton" label="Undo" oncommand="undo();" />
        <button id="redoButton" label="Redo" oncommand="redo();" />
    </hbox>

それぞれのボタン押下時の処理として、 nsITransactionManager の undoTransaction および redoTransaction メソッドを呼び出します。すると、元に戻す/やり直し処理のスタックの最後尾にあるトランザクション(nsITransaction インスタンス)の undoTransaction および redoTransaction メソッドが実行されます。その後、合計金額の表示を更新します。

bank.js
function undo() {
    gTxnManager.undoTransaction();
    updateUI();
}

function redo() {
    gTxnManager.redoTransaction();
    updateUI();
}

バッチ処理

例えば複数のブックマークを選択して削除した後に元に戻すと、複数のブックマークが一括して復元されます。このように、一連のトランザクションをバッチ処理として実行する場合の元に戻す/やり直しを実装します。

はじめに、アプリのUIへ複数の金額を一括して預金するためのボタンを追加します。

bank.xul
        <button label="Deposit $1+$10+$100" oncommand="depositSet([1,10,100]);" />

depositSet 関数は引数に渡された金額の配列すべてについて合計金額へ加算します。このとき、 nsITransactionManager の beginBatch メソッドを呼んでから doTransaction で個々の金額についての預金処理を実行し、最後に endBatch を呼ぶようにします。これにより、一連の預金処理がグループ化され、元に戻す際に一括して元に戻す処理が実行されます。

bank.js
function depositSet(aMoneys) {
    gTxnManager.beginBatch();
    aMoneys.forEach(function(money) {
        var txn = new DepositTxn(money);
        gTxnManager.doTransaction(txn);
    });
    gTxnManager.endBatch();
    updateUI();
}

元に戻す/やり直しスタックのリセット

nsITransactionManager の clear メソッドによって、元に戻す/やり直しスタックをいったんリセットすることができます。このメソッドを使って預金処理を確定させるボタンを作ってみます。

bank.xul
        <button id="completeButton" label="Complete" oncommand="complete();" />
bank.js
function complete() {
    gTxnManager.clear();
}

元に戻す/やり直しスタック内の個数

nsITransactionManager の numberOfUndoItems, numberOfRedoItems プロパティで元に戻す/やり直しスタック内の個数を調べることができます。これを使って元に戻す/やり直し可能なときだけボタンを押下可能にするようにしてみます。

bank.js
function updateUI() {
    document.getElementById("total").value = "$" + gTotalMoney.toString();
    var canUndo = gTxnManager.numberOfUndoItems > 0;
    var canRedo = gTxnManager.numberOfRedoItems > 0;
    function setDisabled(id, disabled) {
        var elt = document.getElementById(id);
        if (disabled)
            elt.setAttribute("disabled", "true");
        else
            elt.removeAttribute("disabled");
    }
    setDisabled("undoButton", !canUndo);
    setDisabled("redoButton", !canRedo);
    setDisabled("completeButton", !canUndo && !canRedo);
}

トランザクションの監視

nsITransactionManager の AddListener に nsITransactionListener インタフェースを実装したオブジェクトを渡して、トランザクションを監視することができます。 RemoveListener で監視を終了するのを忘れずに。

bank.xul
<page xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
      title="Bank" onload="init();" onunload="uninit();">
bank.js
function init() {
    gTxnManager = Components.classes["@mozilla.org/transactionmanager;1"].
                  createInstance(Components.interfaces.nsITransactionManager);
    gTxnManager.AddListener(gTxnListener);
    updateUI();
}

function uninit() {
    gTxnManager.RemoveListener(gTxnListener);
}

nsITransactionListener は多くのメソッドを持ち、元に戻す/やり直し処理の直前/直後などにコールバック処理を設定することができます。今回は元に戻す処理の直前に確認のダイアログを表示し、「キャンセル」ボタンを押下することで中止できるようにします。以下のように willUndo メソッドで true を返すと、処理を中止することができます。

var gTxnListener = {
    willDo: function() {},
    didDo: function() {},
    willUndo: function(aMgr, aTxn) {
        if (!window.confirm("Would you like to undo?"))
            return true;
    },
    didUndo: function() {},
    willRedo: function() {},
    didRedo: function() {},
    willBeginBatch: function() {},
    didBeginBatch: function() {},
    willEndBatch: function() {},
    didEndBatch: function() {},
    willMerge: function() {},
    didMerge: function() {},
};

TOP

while ループ条件中の in 演算子の不思議な挙動

JavaScript で単純なキーバリュー型のオブジェクトから、新しい一意のキーを生成する関数を作った(HTML にしたソースコードはこちら)。

function func() {
    var obj = {1:1, 2:2, 3:3};
    var i = 0;
    do { i++; } while (i in obj);
    return i;
}
alert(func());
alert(func());
alert(func());

これを Firefox 3.6 で実行すると、なぜか結果が 4, 4, 2 だったり 4, 2, 2 だったりと毎回結果が変わる不思議な動作となる。 JavaScript のJIT機能を無効にした場合や、IEなどの他ブラウザでは想定どおり 4, 4, 4 となる。不思議なことに while 文の条件を while (i in obj === true) にした場合も 4, 4, 4 となる。

while ループの条件中でこういう in の使い方をするときは以下のいずれかの方式にしたほうが安全っぽい。

while (obj[i] !== undefined)
while (obj.hasOwnProperty(i))

TOP