ウィジェットオブジェクトAPI

Widget Object APIをローカライズしたものです。原文とは異なる表現を使ったりしています。
この記事のライセンスはCreative Commons 表示-非営利-継承 2.5 一般です。原著作者はOpera Softwareです。

なお、ウィジェットに関する説明は「Opera ウィジェット」を、その他のウィジェット関連の文書について知りたい方はCategory:ウィジェットを、それぞれご覧ください。

はじめに

ウィジェットオブジェクトAPI（Widget Object API）を使えば、widgetオブジェクトとして、またはwindowオブジェクトの拡張として、ウィジェット強力なコントロールを得ることができます。

• ドキュメンテーション
• JavaScriptコード: Widget Object
• ドキュメンテーションのダウンロード
• ライセンス

ウィジェットのDOM

このドキュメントでは、JavaScriptでウィジェットから使えるwidgetオブジェクトとwindowオブジェクトの拡張を説明します。このAPIで、あなたはウィジェットの基礎となるランタイムと通信することができます。このランタイムとは、ウィジェットを表示させたり隠したり、ウィジェットの設定を保存したり、動いているウィジェットの情報を取り出したりするものです。

このAPIのメソッドとプロパティ（widgetオブジェクトと標準のwindowオブジェクトの拡張）は、ウィジェットの中で開いているウェブページからのみ使うことが出来ます。これはつまり、config.xmlを含んだパッケージ内にあり、Operaブラウザにウィジェットとして開かれている場合です。特に記述のない場合、すべてのオブジェクトはJavaScriptからグローバルに使うことができます。

ウィジェットの識別子と入手元

ウィジェットをインストールすると、ブラウザはそれに固有の識別子（ID）を与え、後からそれを参照して使うことができます。これは、widget.identifierプロパティとして見ることができ、ウィジェットURLプロトコルなどで使われます。

さらに、ウィジェットをダウンロードした入手元は、widget.originURLで見ることができます。これは例えば、ユーザーがそのウィジェットについての詳しい情報やアップデートなどを得るリンクとして使うことができます。

ウィジェットURLプロトコル

ウィジェット自身の中身や、将来的には他のウィジェットには、ウィジェットURLプロトコルを使ってアクセスすることができます。このようなURLは下のような形をしています。

widget://[widget identifier]/[path]

identifier（識別子）の部分はwidget.identifierを使って得られます。これを使って、例えばウィジェットに翻訳ファイルを読み込むことができます。

xhr.open('GET','widget://' + widget.identifier + '/resources/i18n.xml',false)

設定を使う

ウィジェットは恒久的に設定を保存することができます。一度保存された設定は、ウィジェットをリロードしたり終了して再起動しても使えますが、ウィジェットを削除すると同時に削除されます。詳しくはwidget.setPreferenceForKey()とwidget.preferenceForKey()をご覧ください。

//'username'キーに'gautamc'値を保存
widget.setPreferenceForKey( 'gautamc', 'username' );
//... ウィジェットを閉じて再起動 ...
var username = widget.preferenceForKey('username');
//また値を使ることができる

もしあるキーに対してnullを保存すると、そのキーに元からあった値は消去されます。

//'username'キーに'gautamc'値を保存
widget.setPreferenceForKey( 'gautamc', 'username' ); 
//... 何かする ...
if ( logout )
{
  widget.setPreferenceForKey( null, 'username' );
}

ウィジェットのモードと解像度の違い

（この章書きかけ）

ステータスメッセージを表示する

ウィジェットは、ウィジェットパネルやステータスバーにステータスメッセージを表示させる設定を持っています。

var updateInterval = setInterval( 120000, function () { 
  window.status = 'Feed last updated ' + new Date (); 
} );

もしwindow.statusプロパティをnullにすると、あらかじめ設定可能なwindow.defaultStatus値に戻します。

ウィジェットを隠したり、表示させたり、閉じたりする

ウィジェットは、ウィンドウとしてもタスクバーにも見えないように隠すことができます。その間もウィジェットはバックグラウンドで動き続けます。これはmwidget.hide()とwidget.show()メソッドを使ってコントロールすることができます。

hideButton.addEventListener( 'click', function () { widget.hide(); }, false );
//...
if ( newItems )
{
  widget.show();
}

ウィジェットはwindow.close()で閉じることもできます。ウィジェットのスタイルガイドにあるように、ウィジェットは「閉じる」ボタンを持たなくてはいけません。widget.opera.comにアップロードされたウィジェットは、「閉じる」ボタンが無ければ拒否されてしまいます。

closeButton.addEventListener( 'click', function () { 
  window.close(); 
}, false );

注：携帯端末ではウィジェットを隠したり閉じたりすることはプログラム不可能です

ユーザーの注意を引く

widget.getAttention()とwidget.showNotification()メソッドを使って、インストールされているウィジェットに何か起こっているとユーザーに通知することができます。

widget.getAttention()は、デスクトップ上ではタスクバーのウィジェットアイコンを点滅させるかそれと同等のことをします。

if ( requestReceived )
{
  widget.getAttention();
}

デスクトップ上では、widget.showNotification()は、デスクトップ上ではシステムトレイのOperaアイコンからポップアップを表示します。このメソッドは、表示するメッセージを引数として取り、ユーザーが通知をクリックするとコールバック（callback）を呼び出します。

if ( itemsReceived )
{
  widget.showNotification( num + ' items received', clickCallkback );
}

これは例えばウィジェットを隠した状態から元に戻すために使うことができます。

注：携帯端末では現在この機能を使っても何も起こりません

ウィジェットを動かしたりリサイズしたりする

ウィジェットは、window.moveTo()、window.moveBy()、window.resizeTo()、window.resizeBy()を使って、動かしたり、cofig.htmlで規定されたサイズを越えてリサイズされることができます。これはつまり、ウィジェットを小さい状態にしておいて、ユーザーが大きくしたいときだけさせるということができます。

resizeToを呼び出すと、ウィジェットは指定された幅と高さに変化します。moveToはウィジェットを指定されたx座標とy座標に動かします。下記の例はウィジェットを左上の角に置き、スクリーンスペースの大きさ一杯まで大きくします。

window.moveTo( 0, 0 );
window.resizeTo( screen.availWidth, screen.availHeight );

resizeByでは、ウィジェットを指定された幅と高さだけ大きくしたり小さくたりします。

//縦横両方に200ピクセルずつサイズを大きくする

window.resizeBy(200,200);

moveByでは、ウィジェットを指定されたdelta_xとdelta_y分だけ移動させます。

//縦横両方に100ピクセルずつ動かす

window.resizeBy(100,100);

注：携帯端末では一度にウィジェットを一つしか表示しないので、移動とリサイズはできません。