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 构造方法。

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 侦听器。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。