java.beans
介面 PropertyEditor

所有已知實作類別：

PropertyEditorSupport

public interface PropertyEditor

PropertyEditor 類別為希望允許使用者編輯某個給定型別的屬性值的 GUI 提供支持。

PropertyEditor 支持各種不同型別的顯示和更新屬性值的方式。大多數 PropertyEditor 只需要支持此 API 中可用的不同選項的一個子集。

簡單的 PropertyEditor 可能只支持 getAsText 和 setAsText 方法，不需要支持（比如說）paintValue 或 getCustomEditor。更多複雜型別的 PropertyEditor 可能無法支持 getAsText 和 setAsText，但它們將改為支持 paintValue 和 getCustomEditor。

每個 propertyEditor 都必須支持三種簡單顯示樣式之一或更多。這樣便可以：(1) 支持 isPaintable；(2) 從 getTags() 返回一個非 null 的 String[]，以及從 getAsText 返回一個非 null 值；(3) 只從 getAsText() 返回一個非 null 的 String。

當此類別是參數物件型別相對應的 propertyEditor 時，每個屬性編輯器都必須支持調用 setValue。此外，每個屬性編輯器都必須支持一個自定義編輯器，或者支持 setAsText。

每個 PropertyEditor 都應該有一個 null 建構子。

方法摘要

void	addPropertyChangeListener(PropertyChangeListener listener) 註冊一個用於 PropertyChange 事件的偵聽器。
String	getAsText() 以文本形式獲得屬性值。
Component	getCustomEditor() PropertyEditor 可以選擇使用完全自定義的 Component 來編輯自己的屬性值。
String	getJavaInitializationString() 返回一部分 Java 程式碼，可以使用這部分程式碼來設置某個屬性，以比對編輯器當前狀態。
String[]	getTags() 如果屬性值必須是一組已知的加標記值之一，則此方法應該返回一個標記陣列。
Object	getValue() 獲取屬性值。
boolean	isPaintable() 確定此屬性編輯器是否是可繪製的。
void	paintValue(Graphics gfx, Rectangle box) 在螢幕實際狀態給定區域中繪製值的表示形式。
void	removePropertyChangeListener(PropertyChangeListener listener) 移除一個用於 PropertyChange 事件的偵聽器。
void	setAsText(String text) 通過解析給定 String 設置屬性值。
void	setValue(Object value) 設置（或更改）將編輯的物件。
boolean	supportsCustomEditor() 確定此屬性編輯器是否支持自定義編輯器。

方法詳細資訊

setValue

void setValue(Object value)

設置（或更改）將編輯的物件。必須將基本型別（比如 "int"）包裹為相應的物件型別，比如 "java.lang.Integer"。

參數：

value - 要編輯的新目標物件。注意，不應由 PropertyEditor 修改此物件，相反 PropertyEditor 應該創建一個新物件來保存所有修改值。

getValue

Object getValue()

獲取屬性值。

返回：

屬性值。將基本型別（比如 "int"）包裹為相應的物件型別，比如 "java.lang.Integer"。

isPaintable

boolean isPaintable()

確定此屬性編輯器是否是可繪製的。

返回：

如果該類別支持 paintValue 方法，則返回 true。

paintValue

void paintValue(Graphics gfx,
                Rectangle box)

在螢幕實際狀態給定區域中繪製值的表示形式。注意，propertyEditor 負責裁剪自身，以適應給定的矩形。

如果 PropertyEditor 不支持繪製請求（參見 isPaintable），則此方法應該是一個靜寂的無操作。

給定 Graphics 物件將擁有父容器的預設字體、顏色等等。PropertyEditor 可以更改圖形屬性（比如字體和顏色），並且無需恢復舊值。

參數：

gfx - 要繪製的 Graphics 物件。

box - 應該在其中繪製圖形物件的矩形。

getJavaInitializationString

String getJavaInitializationString()

返回一部分 Java 程式碼，可以使用這部分程式碼來設置某個屬性，以比對編輯器當前狀態。此方法在產生 Java 程式碼來反映通過屬性編輯器產生的更改時使用。

程式碼片段應該是上下文無關的，並且必須是一個合法的 Java 表示式，正如 JLS 所規定的那樣。

明確地說，如果表達式表示某一計算，則全部類別和靜態成員都應是完全限定的。此規則適用於建構子、靜態方法和非基本參數。

在對該表達式求值時應該使用警告，因為它可能拋出異常。特別要指出的是，程式碼產生器必須確保產生的程式碼能夠在存在可能拋出已檢查異常的表達式的情況下進行編譯。

範例結果是：

• 基本表達式：2
• 類別建構子：new java.awt.Color(127,127,34)
• 靜態欄位：java.awt.Color.orange
• 靜態方法：javax.swing.Box.createRigidArea(new java.awt.Dimension(0, 5))

返回：

表示用於當前值的 initializer 的 Java 程式碼片段。它不應該套件含結束表達式的分號 (';')。

getAsText

String getAsText()

以文本形式獲得屬性值。

返回：

可編輯字元串形式的屬性值。

如果無法將該值表示為可編輯的字元串，則返回 null。

如果返回的是一個非 null 值，則應該準備好 PropertyEditor，以便回到 setAsText() 中解析字元串。

setAsText

void setAsText(String text)
               throws IllegalArgumentException

通過解析給定 String 設置屬性值。如果該 String 格式出錯或者無法將此類別屬性表示為文本，則可能引發 java.lang.IllegalArgumentException。

參數：

text - 要解析的字元串。

拋出：

IllegalArgumentException

getTags

String[] getTags()

如果屬性值必須是一組已知的加標記值之一，則此方法應該返回一個標記陣列。可以用此方法來表示（例如）列舉值。如果 PropertyEditor 支持標記，那麼它應該支持使用 setAsText（同時使用標記值）作為設置值的一種方式，並支持使用 getAsText 來標識當前值。

返回：

此屬性的標記值。如果無法將此屬性表示為加標記的值，則返回 null。

getCustomEditor

Component getCustomEditor()

PropertyEditor 可以選擇使用完全自定義的 Component 來編輯自己的屬性值。PropertyEditor 負責將其自身與其編輯器 Component 聯繫起來，並報告由於觸發 PropertyChange 事件而造成的屬性值更改。

調用 getCustomEditor 的更高層級別的程式碼可以將 Component 嵌入一些更大的屬性表單，或者放入它們自己的個別對話框，或者……

返回：

允許使用者直接編輯當前屬性值的 java.awt.Component。如果這不受支持，則返回 null。

supportsCustomEditor

boolean supportsCustomEditor()

確定此屬性編輯器是否支持自定義編輯器。

返回：

如果 propertyEditor 可以提供一個自定義編輯器，則返回 true。

addPropertyChangeListener

void addPropertyChangeListener(PropertyChangeListener listener)

註冊一個用於 PropertyChange 事件的偵聽器。當 PropertyEditor 更改自己的值時，它應該在所有已註冊的 PropertyChangeListener 上觸發一個 PropertyChange 事件，指定 null 值為屬性名稱，並指定自身為源。

參數：

listener - 觸發 PropertyChange 事件時要調用的物件。

removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener listener)

移除一個用於 PropertyChange 事件的偵聽器。

參數：

listener - 要移除的 PropertyChange 偵聽器。