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="http://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>

属性

activetitlebarcolor
型: color 文字列
ウィンドウがアクティブな時のタイトルバーについて、背景色を指定された色にし、ウィンドウ内容との間の境界線を非表示にします。この属性は Mac OS X でのみ有効です。
buttonalign
型: 文字列型
box が含むボタンのための align 属性の値。
buttondir
型: 文字列型
box が含むボタンのための dir 属性の値。
buttonorient
型: 文字列型
box が含むボタンのための orient 属性の値。
buttonpack
型: 文字列型
box が含むボタンのための pack 属性の値。
buttons
型: カンマで区切られた下記の値のリスト
ダイアログボックス中に現れるボタンをカンマで区切ったリスト。ボタンはユーザのプラットフォームに適した位置に置かれ、基本的なイベントハンドリングが自動で行われます。次の値をリストで使用することができます。
  • accept: 押下すると変更を許諾する OKボタンです。このボタンがデフォルトになります。
  • cancel: 操作を中止するキャンセルボタンです。
  • help: ダイアログについてのヘルプを表示するヘルプボタンです。
  • disclosure: 追加の情報を表示するボタンです。これはボタンになるか、情報を表示する三角形になります。
  • extra1:任意で追加されるボタンです。buttonlabelextra1 属性でこのボタンのラベルを設定することができます。
  • extra2: 任意で追加されるもう一つのボタンです。buttonlabelextra2 属性でこのボタンのラベルを設定することができます。

註: ダイアログボックス内にボタンを表示したくないときは、属性の値に "," (カンマ 1 つ) を設定してください。

defaultButton
型: 文字列型
通常、この属性を設定すべきではありません。設定すると、ダイアログ内のデフォルトボタンを指定します。一般的に、これは Enter キーが押された時にボタンが有効化されることを意味します。この属性には buttons 属性で設定できる値と同じものを設定します。
inactivetitlebarcolor
型: color 文字列
ウィンドウが非アクティブな時のタイトルバーについて、背景色を指定された色にし、ウィンドウ内容との間の境界線を非表示にします。この属性は Mac OS X でのみ有効です。
lastSelected
型: 文字列型
最後に選択されたペインの id を設定します。次に設定ダイアログを開いたとき、このペインがデフォルトで開かれます。
onbeforeaccept
型: スクリプトコード
この属性内のコードは、OK ボタンが押された時、または acceptDialog メソッドが呼ばれた時に呼び出されます。

 

ondialogaccept
型: スクリプトコード
この属性内のコードは、accept ボタンが押された時、もしくは acceptDialog メソッドが呼ばれた時に呼ばれます。ハンドラが true を返す場合、ダイアログは閉じますが、false を返す場合、閉じることはありません。
ondialogcancel
型: スクリプトコード
この属性内のコードは、"cancel" ボタンが押されたとき、または cancelDialog メソッドが呼ばれたときに呼び出されます。このルーチンが true を返す場合、そのままダイアログが閉じられます。false を返す場合は閉じられません。
ondialogdisclosure
型: スクリプトコード
この属性内のコードは、"disclosure" ボタンが押された時、呼び出されます。
ondialoghelp
型: スクリプトコード
この属性内のコードは、"help" ボタンが押されたとき呼び出されます。
onpaneload
型: スクリプトコード
ここで定義されたコードは、window の load イベントのように、ペインが読み込まれた時、呼び出されます。
title
型: 文字列型
window のタイトルバーに表示するためのテキスト。
type
型: 文字列型
メイン設定ウィンドウの子ダイアログには、この属性を child に設定してください。プラットフォームにとって適切な動作であれば、設定はメインダイアログが閉じられた時のみ保存されます。

プロパティ

buttons
型: 下記の値をカンマで区切ったリスト
ダイアログボックス中に現れるボタンをカンマで区切ったリスト。ボタンはユーザのプラットフォームに適した位置に置かれ、基本的なイベントハンドリングが自動で行われます。次の値をリストで使用することができます:
  • accept: 押下すると変更を許諾する OKボタンです。このボタンがデフォルトになります。
  • cancel: 操作を中止するキャンセルボタンです。
  • help: ダイアログについてのヘルプを表示するヘルプボタンです。
  • disclosure: 追加の情報を表示するボタンです。これはボタンになるか、情報を表示する三角形になります。
  • extra1: 任意で追加されるボタンです。buttonlabelextra1 属性でこのボタンのラベルを設定することができます。
  • extra2: 任意で追加されるもう一つのボタンです。buttonlabelextra2 属性でこのボタンのラベルを設定することができます。
currentPane
型: prefpane 要素
現在表示されているペインへの参照。現在のペインを変更するには showPane メソッドを使用してください。
defaultButton
型: 文字列型
通常、この属性を設定すべきではありません。設定すると、ダイアログ内のデフォルトボタンを指定します。一般的に、これは Enter キーが押下された時にボタンが有効化されることを意味します。この属性には buttons 属性で設定できる値と同じものを設定します。

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

lastSelected
型: 文字列型
最後に選択されたペインの id を設定します。次に設定ダイアログを開いたとき、このペインがデフォルトで開かれます。
preferencePanes
型: DOM NodeList
window 内のすべての prefpane 要素のリストを保持します。
type
型: 文字列型
type 属性の値の取得と設定。

メソッド

XUL 要素からの継承
blur, click, doCommand, focus, getElementsByAttribute getElementsByAttributeNS

DOM 要素からの継承
addEventListener(), appendChild(), compareDocumentPosition, dispatchEvent(), getAttribute(), getAttributeNode(), getAttributeNodeNS(), getAttributeNS(), getElementsByTagName(), getElementsByTagNameNS(), getFeature, getUserData, hasAttribute(), hasAttributeNS(), hasAttributes(), hasChildNodes(), insertBefore(), isEqualNode, isSameNode, isSupported(), lookupNamespaceURI, lookupPrefix, normalize(), removeAttribute(), removeAttributeNode(), removeAttributeNS(), removeChild(), removeEventListener(), replaceChild(), setAttribute(), setAttributeNode(), setAttributeNodeNS(), setAttributeNS(), setUserData

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

ドキュメントのタグと貢献者

 このページの貢献者: Piro, Marsf
 最終更新者: Piro,