Interface PropertyEditor

PropertyEditors are custom GUI editors for specific types of values. A PropertyEditor can be used, for example, if you are editing a type of value that can be more easily represented graphically, such as a Point, or one that can be more easily represented by a list, such as a boolean (true/false).

A PropertyEditor must be able to display its contents when asked to and be able to allow the user to change its underlying field value. However, it is not the PropertyEditor's responsibility to make the change to the underlying Object; in fact, the PropertyEditor does not even know about the Object it is actually editing--only about the property it is currently editing. When a change is made to the property, the PropertyEditor must simply fire a PropertyChangeEvent and allow the RAD tool to actually set the property in the underlying Bean.

PropertyEditors should not change the Objects they are given by setValue(). These Objects may or may not be the actual Objects which are properties of the Bean being edited. Instead, PropertyEditors should create a new Object and fire a PropertyChangeEvent with the old and new values.

PropertyEditors also must support the ability to return a Java initialization string. See the getJavaInitializationString() method for details.

There are several different ways a PropertyEditor may display and control editing of its value. When multiple types of input and display are given by a single PropertyEditor, the RAD tool may decide which of the call to support. Some RAD tools may even be text-only, so even if you support a graphical set and get, it may choose the text set and get whenever it can.

1. Every PropertyEditor must support getValue() and setValue(). For setValue(), the component must only support it when the argument is the same type that the PropertyEditor supports.
2. Every PropertyEditor must support getJavaInitializationString().
3. You may support painting the value yourself if you wish. To do this, have isPaintable() return true and implement the paintValue() method. This method does not determine in any way how the value is edited; merely how it is displayed.
4. Let the caller of the PropertyEditor give the user a text input. Do this by returning a non-null String from getAsText(). If you support text input, you *must* support setAsText().
5. Give the caller a set of possible values, such as "true"/"false", that the user must select from. To do this, return the list of Strings from the getTags() method. The RAD tool may choose to implement the user input any way it wishes, and only guarantees that setAsText() will only be called with one of the Strings returned from getTags().
6. You may support a whole custom editing control by supporting getCustomEditor(). To do this, return true from supportsCustomEditor() and return a Component that does the job. It is the component's job, or the PropertyEditor's job, to make sure that when the editor changes its value, the PropertyChangeEvent is thrown.

The PropertyEditor for a particular Bean can be found using the PropertyEditorManager class, which goes through a series of different checks to find the appropriate class.

A PropertyChangeEvent should be thrown from the PropertyEditor whenever a bound property (a property PropertyDescriptor.isBound() set to true) changes. When this happens, the editor itself should *not* change the value itself, but rather allow the RAD tool to call setValue() or setAsText().

Since: JDK1.1

See Also: PropertyEditorManager