source: trunk/gcc/libjava/java/beans/PropertyEditor.java@ 3103

/* 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>
 **   <LU>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.
         **/