ユーザが,アプリケーションビルダでアプリケーションを構成しているときに, 使用中の様々なビーンの見かけ及び振舞いをカスタム化可能としたい。
このカスタム化を,二つの異なる方法で可能とする。 ビーンが特性の集合をエクスポートする場合は,アプリケーションビルダは, これらの特性を使用して,特性のリスト及び各特性に対する 特性エディタ(property editor) を提供する, GUI 特性シート(property sheet) を構成できる。 ユーザは,この特性シートを使用して,ビーンの様々な特性を更新できる。
この種の単純な特性シートは,小規模から中規模までのビーンに対しては, 通常,正しく作動する。 しかし,より大きく複雑なビーンに対しては, もっと高機能な部品のカスタム化を提供可能としたい。 例えば,単に特性シートの選択で対応するのではなく,部品の作成者が, ビーンをカスタム化する様々な段階を通して,ユーザを誘導するカスタム化 “wizards”を提供できるようにしたい。
そのため,各Java Beanが,ビーンのカスタム化を制御する
カスタマイザ(customizer) クラスを共にもつことを可能にしたい。
このカスタマイザクラスは,対象ビーンをカスタム化するために実行可能な
AWT 部品となることが望ましい。
カスタマイザクラスは,対象ビーンのカスタム化を制御したい場合は,
いかなる GUI の振舞いも提供可能とする。
人が,部品の集合の振舞いをカスタム化した場合, アプリケーションビルダは,5.で示した永続性の機構を使用して, 部品の状態を保存することが望ましい。 アプリケーションを実行する場合に,この備蓄状態は読み戻され, 部品を初期化するのがよい。
特性エディタ(property editor) は,String,Color などの特性値を,GUI が編集可能とするために存在するクラスとする。 ビーン開発者は,ビーンの一部として配布する新しいデータ型のすべてに対し, 新しい特性エディタも配布するかもしれない。 例えば,データベースビーン開発者が,新しい型 foo.baz.SQLString を定義し, 部品特性に対してその型を使用する場合,開発者は, SQLString値を編集するための特性エディタ foo.baz.SQLStringEditor も提供したいと考えるかもしれない。
クラスPropertyEditorは, 特性値の読取り及び書込みの様々な方法を数多く提供する。 すべての特性エディタが,様々なオプションすべてをサポートする必要はない。 低機能では,PropertyEditorは,単に, Stringとして値の読取り及び書込みをサポートするかもしれない。 高機能では,PropertyEditorは,その値を編集するために, ポップアップできる完全な java.awt.Component を提供可能とする。
特性エディタは,特性シートの一部として, 又はより複雑な部品カスタマイザ内のフィールドとして, インスタンス化される可能性がある。 PropertyEditorが,(String,ペイントされた長方形, 完全なカスタムエディタ部品など,として) 様々な方法で表現可能な場合には, 与えられた PropertyEditor を表現する最もよい方法を決定するのは, 高レベルツールの責任とする。
特性エディタの中には, Java Beans実行時の一部として提供されるもの,部品開発者によって提供されるもの, アプリケーションビルダツールによって提供されるもの,などがある。
適切な特性エディタが,与えられた Java データ型に対応して配置可能とするために, Java 型と対応する特性エディタクラスとの間を写像する, クラス java.beans.PropertyEditorManager を提供する。
クラス PropertyEditorManager は,特性エディタのレジストリを管理し, クラスを登録することで, 与えられた Java 型に対応する特性エディタとしての動作を可能にする。 レジストリは,“int”,“boolean”などの, 標準 Java 組込み型に対するエディタを使って,事前にロードする。
Java 型に対する特性エディタを配置しようとする場合, 特性の管理プログラムは,適切な特性エディタを次の手順で探す。
通常,新しい型を定義して,特性エディタを提供したい部品作成者は,単に, 基底型の名前に“Editor”を付けた名前のエディタクラスを提供するのがよい。
アプリケーションビルダツールは, Java Beansで提供されるデフォルト特性エディタの集合を使用するか, 又は基本的な Java 型に対する特性エディタのそれ自体の集合を定義するか のいずれかが可能となる。
特性エディタが変更を行った時はいつでも, イベント“PropertyChange”が発生することが望ましい。 これによって,より高レベルのソフトウェアがその変更を検出し, 新しい値を検索し,対象部品に適切な setXXX 呼出しを行うことができる。
特性エディタは,特性の現在値を表現するオブジェクトを与えられる。 しかし,特性エディタは,直接この初期のオブジェクトを変更しないほうがよい。 代わりに,ユーザの入力に基づき,新しいオブジェクトを生成し, 改訂された特性の状態を反映するのがよい。 特性エディタが,イベント“PropertyChange”を発生させる場合(9.2.2 参照), より高レベルなソフトウェアは,変更を検出し,新しいオブジェクトを検索し, 対象部品上で,適切な特性設定メソッドの呼出しを行い,新しい値を設定する。
Javaにおける最も単純なオブジェクト(String,Color 及び Font)は, 不変なため,このモデルは,それらに対しては,自然に動作する。 しかし,可変データ型に対しても,このモデルは, 最も明確及び最も信頼性が高いモデルと考えられる。 部品の下で,既存の特性オブジェクトの値を変更しようとした場合は, エラー及び誤解を生じる可能性がある。
特性シートの中には,変更された各特性値を, 対象部品に直ちに適用するものがあってもよい。 しかし,ユーザが確認するまで,変更を遅らせることを選択する特性シート (又はカスタマイザ)も存在してよい。
部品の中には,一つの特性値を設定すると, 他の特性値の変更を引き起こすものもある。
特性シートが開いてる間にこれが起こる場合, ユーザは,すべて新しい値で特性シートを更新したいと考える。 そのため,各特性の更新後に,特性シート管理プログラムが, 対象ビーンに関連したすべての特性を再度読み取るほうがよい。 しかし,過剰なスクリーン再描画を避けるために, 特性シート管理プログラムは,“Object.equals”試験が続く“==”を行い, 新しい各特性値と以前の値とを比較することが望ましい。 個々の特性エディタは,値が実際に変更された場合にだけ,更新するのがよい。
他の操作の副作用として特性が変更された場合に, 発生するのが望ましいイベント“IndirectPropertyUpdate” を定義することを検討した。 しかし,これは,非常に少しの性能向上だけのためのインタフェースに, 余分な重みを付加すると思われる。
7.4“束縛特性”も参照のこと。
PropertyEditor を実装する場合, メソッド getJavaInitializationString のサポートが重要なことに注意。 ビルダツールは,このメソッドを使用して, ビーンの状態を復元するソースコードの生成を支援してもよい(5.4 参照)。 例えば,getJavaInitializationString を使用して, 特性シート内に示された現在値に,ビーンの特性を再初期化するコードを生成する かもしれない。
getJavaInitializationString が返す String は, メソッド又はコンストラクタの実引数として渡すことが可能な値を, 表現することが望ましい。
そこで,例えば,次のとおりとなる。
特性シートは,単純な部品のほとんどをカスタム化する,適切な方法とする。
しかし,構成を多くの多様な方法で行える大きな部品に対しては, 部品開発者が,部品をカスタム化するための特別なクラスを提供するのが, 適切かもしれない。 これらのクラスを,カスタマイザ(customizer) とする。
各カスタマイザは, java.awt.Componentから直接的に又は間接的に継承することが望ましく, インタフェースjava.beans.Customizerを実装するのがよい。
各カスタマイザは,通常,別々のAWT対話ウィンドウ内で実行される。 カスタマイザは,それ自体を表現する方法の完全な決定権をもち, ユーザが,カスタム化の様々な段階を通して誘導及び移動するにつれて, 見かけを再描画してもよい。
カスタマイザは,そのスクリーンの見かけ内に, 特性エディタを含むことを選択して,対象データ値を編集してもよい。
各カスタマイザは,カスタム化する対象オブジェクトを, そのコンストラクタの実引数として与えられる。
個々のカスタマイザが,カスタマイザの動作にしたがって変更を適用するか, 又は変更を一括して適切な位置でオブジェクトに適用するかは, 完全に個々のカスタマイザ次第とする。 しかし,可能な場合はいつでも,要求された変更を反映するために, 対象ビーンのスクリーンの見かけをすばやく更新するほうがよい。
ビーンが,それ自体のCustomizerを提供したい場合には,
ビーン自体のクラス BeanInfo (8.6 参照)を提供しなければならない。
そうすれば,ツールは,
メソッド BeanInfo.getBeanDescriptor().getCustomizerClass()を使用して,
ビーンのクラス Customizer を配置することができる。
public interface java.beans.Customizer
カスタマイザクラスは, 対象Java Beanをカスタム化するための完全なカスタム GUI を提供する。
各カスタマイザは,クラス java.awt.Component から継承し, AWT ダイアログ又は AWT パネル内部でインスタンス化できることが望ましい。
各カスタマイザは,nullコンストラクタをもつのがよい。
public void addPropertyChangeListener(PropertyChangeListener listener)
イベント PropertyChange に対応するリスナを登録する。 表示された特性の再生を要求するかもしれない方法で, 対象ビーンを変更する場合はいつでも, カスタマイザは,イベント PropertyChange を起動することが望ましい。
仮引数:
public void removePropertyChangeListener(PropertyChangeListener listener)
イベント PropertyChange に対応するリスナを取り除く。
仮引数:
public void setObject(Object bean)
カスタム化されるオブジェクトを設定する。 このメソッドは,カスタマイザが,任意の親 AWT コンテナに付加される前に, 一度だけ,呼び出されるのがよい。
仮引数:
public interface java.beans.PropertyEditor
クラス PropertyEditor は,ユーザに, 与えられた型の特性値を編集可能とさせたい, GUI に対するサポートを提供する。
PropertyEditor は,特性値を表示及び更新する多様な方法をサポートする。 PropertyEditor のほとんどは, この API で利用可能な様々なオプションの部分集合をサポートするだけでよい。
単純な PropertyEditor は, メソッド getAsText 及びメソッド setAsText をサポートするだけであってもよく, (例えば,) paintValue 又は getCustomEditor をサポートする必要はない。 もっと複雑な型は, getAsText 及び setAsText をサポートすることはできないかもしれないが, その代わりに,paintValue 及び getCustomEditor をサポートする。
すべての PropertyEditor は,三つの単純な表示スタイルのうち, 一つ又はそれ以上をサポートしなければならない。 そこで,次のいずれかが可能となる。
すべての特性エディタは,実引数オブジェクトが, 対応する propertyEditor となる型をもつ場合に, setValue の呼出しをサポートしなければならない。 さらに,各特性エディタは,カスタムエディタ又は setAsText を, サポートしなければならない。
各 PropertyEditor は,null コンストラクタをもつことが望ましい。
public void addPropertyChangeListener(PropertyChangeListener listener)
イベント PropertyChange に対応するリスナを登録する。 PropertyEditor が,その値を変更する場合は, すべての登録された ProertyChangeListener 上で, 特性名に対して null 値及びソースとして自分自体を指定して, イベントPropertyChangeを起動することが望ましい。
仮引数:
public String getAsText()
人が編集可能な文字列としての特性値。
値が編集可能な文字列として表現できない場合は,nullを返す。
nullでない値が返された場合, PropertyEditor は,その文字列を setAsText() 内に戻し, 構文解析する設定になっていることが望ましい。
public Component getCustomEditor()
PropertyEditor は,特性値を編集する, フルカスタム Componentを利用可能とする選択をするかもしれない。 PropertyEditor を,そのエディタ Component 自体に結び付け, イベント ProertyChange を起動することで, 特性値の変更を報告するのは,PropertyEditorの責任とする。
getCustomEditor を呼び出す,より高レベルなコードは, より大きい特性シートに Component を組み込んだり, 個々のダイアログに Component を設置したり, その他様々なことを行ってもよい。
返却値:
public String getJavaInitializationString()
このメソッドは,特性の値を設定するJavaコードを生成する場合に, 使用することを意図する。変数を現特性値で初期化するために使用できる Javaコードの断片を返すことが望ましい。
結果例は,“2”,“newColor(127,127,34)”,“Color.orange”など。
返却値:
public String[] getTags()
特性値が,周知のタグ付き値の集合の一つでなければならない場合, このメソッドは,タグの配列を返すことが望ましい。 これは,(例えば,) enum値を表現するために使用できる。 PropertyEditorがタグをサポートする場合, 値を設定する方法としてのタグ値をもつ setAsText の使用 及び現在値を識別するための getAsText の使用を, サポートすることが望ましい。
返却値:
public Object getValue()
返却値:
public boolean isPaintable()
返却値:
public void paintValue(Graphics gfx, Rectangle box)
値の表現を,スクリーンの与えられた領域に描画する。 propertyEditorは,与えられた長方形に合う自分自体の刈込みに対して, 責任をもつことに注意。
PropertyEditorが描画要求(isPaintable参照)を引き受けない場合は, このメソッドは,全く動作しない。
与えられた Graphics オブジェクトは,親コンテナの,デフォルトの, フォント,カラーなどをもつ。 PropertyEditor は, フォント,カラーなどのグラフィックス属性を変更してよく, 旧値を復元できる必要はない。
仮引数:
public void removePropertyChangeListener(PropertyChangeListener listener)
イベント PropertyChange に対応するリスナを取り除く。
仮引数:
public void setAsText(String text) throws IllegalArgumentException
与えられた String を構文解析することによって, 特性値を設定する。 String が間違ってフォーマットされるか,又は この種の特性がテキストとして表現できない場合には, java.IllegalArgumentException を呼び出す可能性がある。
仮引数:
public void setValue(Object value)
編集するオブジェクトを設定(又は変更)する。 “int”などのプリミティブ型は, “java.lang.Integer”などの対応するオブジェクト型として, ラップしなければならない。
仮引数:
public boolean supportsCustomEditor()
返却値:
public class java.beans.PropertyEditorManager extends java.lang.Object
PropertyEditorManager は,与えられた型名に対する特性エディタを, 配置するために使用できる。 この特性エディタは,与えられたオブジェクトを編集するために, インタフェース java.beans.PropertyEditor をサポートしなければならない。
PropertyEditorManager は,次の三つの技術を使用して, 与えられた型に対するエディタを配置する。
そこで,例えば,入力クラス foo.bah.Fred に対しては, PropertyEditorManager は,まず,そのテーブル内を見て, エディタが,foo.bah.Fred のために登録されているかどうかを調べ, 登録されていた場合,それを使用する。 次に,クラス foo.bah.FredEditor を探す。 さらに,(例えば,)クラス standardEditorsPackage.FredEditorを探す。
Java プリミティブ型,“boolean”,“byte”,“short”,“int”,
“long”,“float”及び“double”,並びにクラス java.lang.String,
java.awt.Color 及び java.awt.Font に対しては,
デフォルトの PropertyEditor が提供される。
public static PropertyEditor findEditor(Class targetType)
与えられた対象型に対して,値エディタを配置する。
仮引数:
返却値:
public static String[] getEditorSearchPath()
返却値:
public static void registerEditor(Class targetType,Class editorClass)
与えられた対象クラスのエディタ値に,使用するエディタクラスを登録する。
仮引数:
public static void setEditorSearchPath(String path[])
特性エディタを見つけるために使用するパッケージ名のリストを変更する。
仮引数:
public class java.beans.PropertyEditorSupport extends java.lang.Object implements java.beans.PropertyEditor
このクラスは,特性エディタの構築を支援するサポートクラスとする。
これは,基底クラス又は委譲先として使用できる。
protected PropertyEditorSupport()
派生する PropertyEditor クラスで使用するコンストラクタ。
protected PropertyEditorSupport(Object source)
PropertyEditor が委譲しているときに使用するコンストラクタ。
仮引数:
public synchronized void addPropertyChangeListener(PropertyChangeListener listener)
イベント PropertyChange のためのリスナを登録する。 クラスは,値が更新されるときはいつでも,PropertyChange 値を起動する。
仮引数:
public void firePropertyChange()
興味あるリスナに修正されたことを報告する。
仮引数:
public String getAsText()
返却値:
public Component getCustomEditor()
PropertyEditor は,その特性値を編集するフルカスタム Component を利用可能にする選択をしてもよい。 PopertyEditor それ自体とそのエディタ Component とを結び付け, イベント PropertyChange を起動することによって特性値の変化を報告するのは, PropertyEditor の責任とする。
getCustomEditor を呼び出す,より高レベルのコードは, より大きな特性シート内にその Component を埋め込む, それ自体の個別なダイアログ内に置く,などを行ってもよい。
返却値:
public String getJavaInitializationString()
このメソッドは,特性値を設定するための Java コードを生成するときに, 使用することを意図している。 現特性値で変数を初期化するために使用できる, Java コードの断片を返すことが望ましい。
結果例は,“2”,“new Color(127,127,34)”,“Color.orange”など。
返却値:
public String[] getTags()
特性値が周知のタグ付き値の集合の一つでなければならない場合は, このメソッドは,タグ値の配列を返すことが望ましい。 これは,(例えば,)enum 値を表現するために使用できる。 PropertyEditor がタグをサポートしている場合は, その値を設定する方法として, タグ値をもつ setAsText の使用をサポートすることが望ましい。
返却値:
public Object getValue()
返却値:
public boolean isPrintable()
返却値:
public void paintValue(Graphics gfx, Rectangle box)
返却値:
public void paintValue(Graphics gfx, Rectangle box)
値の表現を,スクリーンの与えられた領域に描画する。 propertyEditorは,与えられた長方形に合う自分自体の刈込みに対して, 責任をもつことに注意。
PropertyEditorが描画要求(isPaintable参照)を引き受けない場合は, このメソッドは,全く動作しない。
仮引数:
public synchronized void removePropertyChangeListener(PropertyChangeListener listener)
イベント PropertyChange に対するリスナを取り除く。
仮引数:
public void setAsText(String text) throws IllegalArgumentException
与えられた String を構文解析することによって,特性値を設定する。 String が間違ってフォーマットされるか,又は この種の特性がテキストとして表現できない場合には, java.IllegalArgumentException を呼び出す可能性がある。
仮引数:
public void setValue(Object value)
編集するオブジェクトを設定(又は変更)する。
仮引数:
public boolean supportsCustomEditor()
返却値: