** ** 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. **
** ** 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(). ** ** @author John Keiser ** @since JDK1.1 ** @version 1.1.0, 30 June 1998 ** @see java.beans.PropertyEditorManager ** @see java.beans.PropertyEditorSupport **/ public interface PropertyEditor { /** 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. ** @param value the value to set this property to. **/ public abstract void setValue(Object value); /** 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. ** @return the current value of the PropertyEditor. **/ public abstract Object getValue(); /** 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. ** @param text the text to set it to. ** @exception IllegalArgumentException if the String is in the wrong format or setAsText() is not supported. **/ public abstract void setAsText(String text) throws IllegalArgumentException; /** 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().
** @return the value of this property in String format.
**/
public abstract String getAsText();
/** 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.
** @return the list of possible String values for this property type.
**/
public abstract String[] getTags();
/** The RAD tool calls this to find out whether the PropertyEditor can paint itself.
** @return true if it can paint itself graphically, false if it cannot.
**/
public abstract boolean isPaintable();
/** 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. ** @param g the Graphics context to paint on ** @param bounds the rectangle you have reserved to work in **/ public abstract void paintValue(java.awt.Graphics g, java.awt.Rectangle bounds); /** The RAD tool calls this to find out whether the PropertyEditor supports a custom component to edit and display itself. ** @return true if getCustomEditor() will return a component, false if not. **/ public abstract boolean supportsCustomEditor(); /** 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.
** @return the custom editor for this property type. **/ public abstract java.awt.Component getCustomEditor(); /** Adds a property change listener to this PropertyEditor. ** @param listener the listener to add **/ public abstract void addPropertyChangeListener(PropertyChangeListener listener); /** Removes a property change listener from this PropertyEditor. ** @param listener the listener to remove **/ public abstract void removePropertyChangeListener(PropertyChangeListener listener); /** 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())