java.beans

Interface PropertyEditor

Known Implementing Classes:: ColorEditor, FontEditor, NativeBooleanEditor, NativeByteEditor, NativeDoubleEditor, NativeFloatEditor, NativeIntEditor, NativeLongEditor, NativeShortEditor, PropertyEditorSupport, StringEditor

public 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.

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.
Every PropertyEditor must support getJavaInitializationString().
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.
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().
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().
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, PropertyEditorSupport

Method Summary
`void`	`addPropertyChangeListener(PropertyChangeListener listener)` Adds a property change listener to this PropertyEditor.
`String`	`getAsText()` Get the value of this property in String format.
`Component`	`getCustomEditor()` The RAD tool calls this to grab the component that can edit this type.
`String`	`getJavaInitializationString()` Get a Java language-specific String which could be used to create an Object of the specified type.
`String[]`	`getTags()` Get a list of possible Strings which this property type can have.
`Object`	`getValue()` Accessor method to get the current value the PropertyEditor is working with.
`boolean`	`isPaintable()` The RAD tool calls this to find out whether the PropertyEditor can paint itself.
`void`	`paintValue(Graphics g, Rectangle bounds)` The RAD tool calls this to paint the actual value of the property.
`void`	`removePropertyChangeListener(PropertyChangeListener listener)` Removes a property change listener from this PropertyEditor.
`void`	`setAsText(String text)` Set the value of this property using a String.
`void`	`setValue(Object value)` Called by the RAD tool to set the value of this property for the PropertyEditor.
`boolean`	`supportsCustomEditor()` The RAD tool calls this to find out whether the PropertyEditor supports a custom component to edit and display itself.

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

Adds a property change listener to this PropertyEditor.
Parameters:
listener - the listener to add

getAsText

public String getAsText()

Get the value of this property in String format. Many times this can simply use Object.toString().
Return null if you do not support getAsText()/setAsText(). setAsText(getAsText()) should be valid; i.e. the stuff you spit out in getAsText() should be able to go into setAsText().
Returns:
the value of this property in String format.

getCustomEditor

public Component getCustomEditor()

The RAD tool calls this to grab the component that can edit this type. The component may be painted anywhere the RAD tool wants to paint it-- even in its own window.
The component must hook up with the PropertyEditor and, whenever a change to the value is made, fire a PropertyChangeEvent to the source.

Returns:
the custom editor for this property type.

getJavaInitializationString

public String getJavaInitializationString()

Get a Java language-specific String which could be used to create an Object of the specified type. Every PropertyEditor must support this.
The reason for this is that while most RAD tools will serialize the Beans and deserialize them at runtime, some RAD tools will generate code that creates the Beans. Examples of Java initialization strings would be:

2
"I am a String"
new MyObject(2, "String", new StringBuffer())

Returns:
the initialization string for this object in Java.

getTags

public String[] getTags()

Get a list of possible Strings which this property type can have. The value of these will be used by the RAD tool to construct some sort of list box or to check text box input, and the resulting String passed to setAsText() should be one of these. Note, however, that like most things with this mammoth, unwieldy interface, this is not guaranteed. Thus, you must check the value in setAsText() anyway.
Returns:
the list of possible String values for this property type.

getValue

public Object getValue()

Accessor method to get the current value the PropertyEditor is working with. If the property type is native, it will be wrapped in the appropriate wrapper type.
Returns:
the current value of the PropertyEditor.

isPaintable

public boolean isPaintable()

The RAD tool calls this to find out whether the PropertyEditor can paint itself.
Returns:
true if it can paint itself graphically, false if it cannot.

paintValue

public void paintValue(Graphics g,
                       Rectangle bounds)

The RAD tool calls this to paint the actual value of the property. The Graphics context will have the same current font, color, etc. as the parent Container. You may safely change the font, color, etc. and not change them back.
This method should do a silent no-op if isPaintable() is false.
Parameters:
g - the Graphics context to paint on
bounds - the rectangle you have reserved to work in

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

Removes a property change listener from this PropertyEditor.
Parameters:
listener - the listener to remove

setAsText

public void setAsText(String text)
            throws IllegalArgumentException

Set the value of this property using a String. Whether or not this PropertyEditor is editing a String type, this converts the String into the type of the PropertyEditor.
Parameters:
text - the text to set it to.
Throws:
IllegalArgumentException - if the String is in the wrong format or setAsText() is not supported.

setValue

public void setValue(Object value)

Called by the RAD tool to set the value of this property for the PropertyEditor. If the property type is native, it should be wrapped in the appropriate wrapper type.
Parameters:
value - the value to set this property to.

supportsCustomEditor

public boolean supportsCustomEditor()

The RAD tool calls this to find out whether the PropertyEditor supports a custom component to edit and display itself.
Returns:
true if getCustomEditor() will return a component, false if not.

java.beans.PropertyEditor Copyright (C) 1998 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

Overview Package Class Use Source Tree Index Deprecated About
Prev Class \| Next Class		Frames \| No Frames
Summary: Nested \| Field \| Method \| Constr	Detail: Nested \| Field \| Method \| Constr