| /* 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., 59 Temple Place, Suite 330, Boston, MA |
| 02111-1307 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. */ |
| |
| |
| package java.beans; |
| |
| /** |
| ** 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).<P> |
| ** |
| ** 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.<P> |
| ** |
| ** 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.<P> |
| ** |
| ** PropertyEditors also must support the ability to return a Java |
| ** initialization string. See the getJavaInitializationString() method for |
| ** details.<P> |
| ** |
| ** 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. |
| ** <OL> |
| ** <LI>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.</LI> |
| ** <LI>Every PropertyEditor must support getJavaInitializationString().</LI> |
| ** <LI>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.</LI> |
| ** <LI>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().</LI> |
| ** <LI>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().</LI> |
| ** <LI>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.</LI> |
| ** </OL> |
| ** |
| ** 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.<P> |
| ** |
| ** 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. |
| **/ |
| 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. |
| **/ |
| 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. |
| **/ |
| void setAsText(String text) throws IllegalArgumentException; |
| |
| /** Get the value of this property in String format. |
| ** Many times this can simply use Object.toString().<P> |
| ** Return null if you do not support getAsText()/setAsText(). |
| ** <code>setAsText(getAsText())</code> 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. |
| **/ |
| 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. |
| **/ |
| 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. |
| **/ |
| 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.<P> |
| ** 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 |
| **/ |
| 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. |
| **/ |
| 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.<P> |
| ** The component must hook up with the PropertyEditor and, whenever a |
| ** change to the value is made, fire a PropertyChangeEvent to the source.<P> |
| ** @return the custom editor for this property type. |
| **/ |
| java.awt.Component getCustomEditor(); |
| |
| |
| /** Adds a property change listener to this PropertyEditor. |
| ** @param listener the listener to add |
| **/ |
| void addPropertyChangeListener(PropertyChangeListener listener); |
| |
| /** Removes a property change listener from this PropertyEditor. |
| ** @param listener the listener to remove |
| **/ |
| 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.<P> |
| ** 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:<P> |
| ** <OL> |
| ** <LI><CODE>2</CODE></LI> |
| ** <LI><CODE>"I am a String"</CODE></LI> |
| ** <LI><CODE>new MyObject(2, "String", new StringBuffer())</CODE></LI> |
| ** </OL> |
| ** @return the initialization string for this object in Java. |
| **/ |
| String getJavaInitializationString(); |
| } |