prefwindow

設定ダイアログに使用される特別なウィンドウ。この要素は window タグの中に置いて使用し、一つ以上の prefpane 要素を含めなければなりません。ボタンの行が preference ダイアログの各 prefpane すべてに現れます。通常、各ペインは関連する設定が一つのグループにまとめられます。一つの prefpane しかないときは、ナビゲーション領域が隠されます。

変更がすぐに適用される慣習のあるプラットフォーム上では、ユーザインタフェース要素が変更されるとすぐに設定が調整されます。他のプラットフォーム上では、ダイアログが閉じられるまで設定が適用されません。

設定ウィンドウをは、他のダイアログと同じように、window の openDialog メソッドを使用して開くことができます。デフォルトで指定のペインを開くには、openDialog の四番目の引数に特定のペインの id を渡します。また、prefwindow タグ上の lastSelected 属性に開始するペインの id を設定して指定することもできます。通常は、この属性を設定しなくても、設定ダイアログを最後に閉じた時に表示していたものが自動的にデフォルトのペインとして設定されます。

詳しい情報が設定システムの記事にあります。

XULrunner ベースのアプリケーションに対しての重要な注意事項: 設定システム (toolkit の一部分) は、依然、二つの browser.* 設定に頼っています。一つ目は真偽値を設定する browser.preferences.instantApply です。preference ウィンドウは、あなたのアプリケーションのデフォルト値にこれが設定されていないと正しく動作しません (詳しくは bug 485150 を参照)。この設定値が true の場合、設定ウィンドウでユーザが設定を選択すると、OK ボタンを押してダイアログを閉じなくても設定がすぐに適用されます。二つ目は同じく真偽値を設定する browser.preferences.animateFadeIn です。これは XULrunner ベースのアプリケーションで省略できますが、デフォルトの動作設定 (Mac OS X では true、その他のプラットフォームでは false) を上書きできます。

属性

buttonalign, buttondir, buttonorient, buttonpack, buttons, defaultButton, lastSelected, onbeforeaccept, ondialogaccept, ondialogcancel, ondialogdisclosure, ondialoghelp, onpaneload, title, type

プロパティ

buttons, currentPane, defaultButton, lastSelected, preferencePanes, type

メソッド

acceptDialog, addPane, cancelDialog, centerWindowOnScreen, getButton, openSubDialog, openWindow, showPane

例

   <?xml version="1.0"?>
   <?xml-stylesheet href="chrome://global/skin/" type="text/css"?>   
   <prefwindow xmlns="https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
     <prefpane id="saveoptions" label="Backups">
       <preferences>
         <preference id="pref-backup" name="myapp.mybackups" type="bool"/>
         <preference id="pref-backupduration" name="myapp.mybackups.duration" type="int"/>
       </preferences>
       <checkbox label="Automatically Save Backups" preference="pref-backup"/>
       <textbox label="Duration:" preference="pref-backupduration"/>
     </prefpane>
   </prefwindow>

属性

プロパティ

instantApply （読み取り専用）

ウィンドウが "instant apply" モード（設定の変更が即座に適用されるモード）かどうかを示します。値は真偽値のユーザ設定 browser.preferences.instantApply から読み込まれます。（?? それは <field> として宣言されているため、あなたは値を書き換える事ができますが、私はそれが正しい事とは思えません。）

メソッド

acceptDialog()

戻り値の型: 戻り値なし

dialog に同意して閉じます。OK ボタンの押下と似ています。

addPane( prefpane )

戻り値の型: 戻り値なし

ペインのリストに prefpane を追加します。

cancelDialog()

戻り値の型: 戻り値無し

dialog をキャンセルして閉じます。Cancel ボタンの押下と似ています。

animate(aOldPane, aNewPane)

これはおそらく公開メソッドではありません（？）。

centerWindowOnScreen()

戻り値の型: 戻り値無し

dialog をスクリーンの中央に配置します。

getButton( type )

戻り値の型: button 要素

指定した type に一致する、 dialog 内の button 要素を返します。

openSubDialog( url, features, params )

戻り値の型: window

子ダイアログを開きます。通常、このメソッドはユーザに詳細オプションを設定させるために使用します。引数は window の openDialog に似ていますが、window 名を提供する必要はありません。url は XUL ファイルでなければなりません。子ダイアログも prefwindow である場合は、その type 属性を child に設定してください。メインダイアログが閉じられた時、その設定が保存されます。

openWindow( windowtype, url, features, params )

戻り値の型: window

子ウィンドウを開きます。windowtype は window 形式を指定する文字列です。指定した形式のウィンドウがすでに開かれている場合、このメソッドは、もう一つのウィンドウを開く代わりに、そのウィンドウにフォーカスを切り替えて最前面に表示します。指定した形式のウィンドウが開かれていない場合、与えられた url を表示する新しいウィンドウが開かれます。

showPane( prefpane )

戻り値の型: 戻り値無し

特定のペインに表示を切り替えます。

注意。あなたは、そのサブウィンドウが既に開かれている時に openWindow() を使って渡されたパラメータを受け取るために、initWithParams() という関数をサブウィンドウの中で定義する事ができます。例えば Firefox のパーミッションマネージャの UI は同じウィンドウを画像、ソフトウェアのインストール、ポップアップのブロックの3つのダイアログのために使っています。このウィンドウでは initWithParams() を、ウィンドウを開き直さずにダイアログの種類を変えるために使っています。

以下のような使い方がお薦めです：

// subwindow.js
function onLoad(ev) {
  // 何らかの初期化処理

  initWithParams(window.arguments[0]); // 1つのパラメータだけがウィンドウに渡される事を期待しています。
}

function initWithParams(aParams) {
  // これは、ウィンドウが既に開かれていて openWindow() で再度フォーカスされる時に呼ばれるでしょう。
}

注意点

モーダルなサブダイアログを開く場合

サブダイアログは document.documentElement を経由してのみ開く事ができ、window からは開けません。従って、openSubDialog() を呼び出す例は以下のようになります：

document.documentElement.openSubDialog("chrome://myextension/content/options-sub.xul", "", null)

prefwindow で prefpane を使う時の問題

-<prefpane> 以外の要素を prefwindow に置きたいと思った場合、それらはすべての <prefpane> よりも後に置くべきです。prefpane 以外の要素を最初の <prefpane> よりも前に置いた場合、ペインの切り替え時におかしな挙動を目にするかもしれません。これは バグ 296418 によるものです。

間違った例：

<prefwindow>
  <script src="config.js"/>
  <prefpane label="pane1" src="pane1.xul"/>
  <prefpane label="pane2" src="pane2.xul"/>
</prefwindow>

正しい例：

<prefwindow>
  <prefpane label="pane1" src="pane1.xul"/>
  <prefpane label="pane2" src="pane2.xul"/>
  <script src="config.js"/>
</prefwindow>

関連項目

prefpane