Source for java.beans.PropertyEditor

   1: /* java.beans.PropertyEditor
   2:    Copyright (C) 1998 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package java.beans;
  40: 
  41: /**
  42:  ** PropertyEditors are custom GUI editors for specific types of values.
  43:  **
  44:  ** A PropertyEditor can be used, for example, if you are editing a type of value
  45:  ** that can be more easily represented graphically, such as a Point, or one that
  46:  ** can be more easily represented by a list, such as a boolean (true/false).<P>
  47:  **
  48:  ** A PropertyEditor must be able to display its contents when asked to and
  49:  ** be able to allow the user to change its underlying field value.  However, it
  50:  ** is not the PropertyEditor's responsibility to make the change to the
  51:  ** underlying Object; in fact, the PropertyEditor does not even know about the
  52:  ** Object it is actually editing--only about the property it is currently
  53:  ** editing.  When a change is made to the property, the PropertyEditor must
  54:  ** simply fire a PropertyChangeEvent and allow the RAD tool to actually set
  55:  ** the property in the underlying Bean.<P>
  56:  **
  57:  ** PropertyEditors should not change the Objects they are given by setValue().
  58:  ** These Objects may or may not be the actual Objects which are properties of
  59:  ** the Bean being edited.  Instead, PropertyEditors should create a new Object
  60:  ** and fire a PropertyChangeEvent with the old and new values.<P>
  61:  **
  62:  ** PropertyEditors also must support the ability to return a Java
  63:  ** initialization string.  See the getJavaInitializationString() method for
  64:  ** details.<P>
  65:  **
  66:  ** There are several different ways a PropertyEditor may display and control
  67:  ** editing of its value.  When multiple types of input and display are
  68:  ** given by a single PropertyEditor, the RAD tool may decide which of the call
  69:  ** to support.  Some RAD tools may even be text-only, so even if you support
  70:  ** a graphical set and get, it may choose the text set and get whenever it can.
  71:  ** <OL>
  72:  **   <LI>Every PropertyEditor must support getValue() and setValue().  For
  73:  **       setValue(), the component must only support it when the argument is
  74:  **       the same type that the PropertyEditor supports.</LI>
  75:  **   <LI>Every PropertyEditor must support getJavaInitializationString().</LI>
  76:  **   <LI>You may support painting the value yourself if you wish.  To do this,
  77:  **       have isPaintable() return true and implement the paintValue() method.
  78:  **       This method does not determine in any way how the value is edited;
  79:  **       merely how it is displayed.</LI>
  80:  **   <LI>Let the caller of the PropertyEditor give the user a text input.  Do
  81:  **       this by returning a non-null String from getAsText().  If you support
  82:  **       text input, you *must* support setAsText().</LI>
  83:  **   <LI>Give the caller a set of possible values, such as "true"/"false", that
  84:  **       the user must select from.  To do this, return the list of Strings
  85:  **       from the getTags() method.  The RAD tool may choose to implement the
  86:  **       user input any way it wishes, and only guarantees that setAsText() will
  87:  **       only be called with one of the Strings returned from getTags().</LI>
  88:  **   <LI>You may support a whole custom editing control by supporting
  89:  **       getCustomEditor().  To do this, return true from supportsCustomEditor()
  90:  **       and return a Component that does the job.  It is the component's job,
  91:  **       or the PropertyEditor's job, to make sure that when the editor changes
  92:  **       its value, the PropertyChangeEvent is thrown.</LI>
  93:  ** </OL>
  94:  **
  95:  ** The PropertyEditor for a particular Bean can be found using the
  96:  ** PropertyEditorManager class, which goes through a series of different
  97:  ** checks to find the appropriate class.<P>
  98:  **
  99:  ** A PropertyChangeEvent should be thrown from the PropertyEditor whenever a
 100:  ** bound  property (a property PropertyDescriptor.isBound() set to true)
 101:  ** changes.  When this happens, the editor itself should *not* change the value
 102:  ** itself, but rather allow the RAD tool to call setValue() or setAsText().
 103:  **
 104:  ** @author John Keiser
 105:  ** @since JDK1.1
 106:  ** @version 1.1.0, 30 June 1998
 107:  ** @see java.beans.PropertyEditorManager
 108:  ** @see java.beans.PropertyEditorSupport
 109:  **/
 110: 
 111: public interface PropertyEditor {
 112:         /** Called by the RAD tool to set the value of this property for the PropertyEditor.
 113:          ** If the property type is native, it should be wrapped in the appropriate
 114:          ** wrapper type.
 115:          ** @param value the value to set this property to.
 116:          **/
 117:         void setValue(Object value);
 118: 
 119:         /** Accessor method to get the current value the PropertyEditor is working with.
 120:          ** If the property type is native, it will be wrapped in the appropriate
 121:          ** wrapper type.
 122:          ** @return the current value of the PropertyEditor.
 123:          **/
 124:         Object getValue();
 125: 
 126: 
 127:         /** Set the value of this property using a String.
 128:          ** Whether or not this PropertyEditor is editing a String type, this converts
 129:          ** the String into the type of the PropertyEditor.
 130:          ** @param text the text to set it to.
 131:          ** @exception IllegalArgumentException if the String is in the wrong format or setAsText() is not supported.
 132:          **/
 133:         void setAsText(String text) throws IllegalArgumentException;
 134: 
 135:         /** Get the value of this property in String format.
 136:          ** Many times this can simply use Object.toString().<P>
 137:          ** Return null if you do not support getAsText()/setAsText().
 138:          ** <code>setAsText(getAsText())</code> should be valid; i.e. the stuff you spit out in
 139:          ** getAsText() should be able to go into setAsText().
 140:          ** @return the value of this property in String format.
 141:          **/
 142:         String getAsText();
 143: 
 144:         /** Get a list of possible Strings which this property type can have.
 145:          ** The value of these will be used by the RAD tool to construct some sort
 146:          ** of list box or to check text box input, and the resulting String passed
 147:          ** to setAsText() should be one of these.  Note, however, that like most things
 148:          ** with this mammoth, unwieldy interface, this is not guaranteed.  Thus, you
 149:          ** must check the value in setAsText() anyway.
 150:          ** @return the list of possible String values for this property type.
 151:          **/
 152:         String[] getTags();
 153: 
 154: 
 155:         /** The RAD tool calls this to find out whether the PropertyEditor can paint itself.
 156:          ** @return true if it can paint itself graphically, false if it cannot.
 157:          **/
 158:         boolean isPaintable();
 159: 
 160:         /** The RAD tool calls this to paint the actual value of the property.
 161:          ** The Graphics context will have the same current font, color, etc. as the
 162:          ** parent Container.  You may safely change the font, color, etc. and not
 163:          ** change them back.<P>
 164:          ** This method should do a silent no-op if isPaintable() is false.
 165:          ** @param g the Graphics context to paint on
 166:          ** @param bounds the rectangle you have reserved to work in
 167:          **/
 168:         void paintValue(java.awt.Graphics g, java.awt.Rectangle bounds);
 169: 
 170: 
 171:         /** The RAD tool calls this to find out whether the PropertyEditor supports a custom component to edit and display itself.
 172:          ** @return true if getCustomEditor() will return a component, false if not.
 173:          **/
 174:         boolean supportsCustomEditor();
 175: 
 176:         /** The RAD tool calls this to grab the component that can edit this type.
 177:          ** The component may be painted anywhere the RAD tool wants to paint it--
 178:          ** even in its own window.<P>
 179:          ** The component must hook up with the PropertyEditor and, whenever a
 180:          ** change to the value is made, fire a PropertyChangeEvent to the source.<P>
 181:          ** @return the custom editor for this property type.
 182:          **/
 183:         java.awt.Component getCustomEditor();
 184: 
 185: 
 186:         /** Adds a property change listener to this PropertyEditor.
 187:          ** @param listener the listener to add
 188:          **/
 189:         void addPropertyChangeListener(PropertyChangeListener listener);
 190: 
 191:         /** Removes a property change listener from this PropertyEditor.
 192:          ** @param listener the listener to remove
 193:          **/
 194:         void removePropertyChangeListener(PropertyChangeListener listener);
 195: 
 196:         /** Get a Java language-specific String which could be used to create an Object
 197:          ** of the specified type.  Every PropertyEditor must support this.<P>
 198:          ** The reason for this is that while most RAD tools will serialize the Beans
 199:          ** and deserialize them at runtime, some RAD tools will generate code that
 200:          ** creates the Beans.  Examples of Java initialization strings would be:<P>
 201:          ** <OL>
 202:          **     <LI><CODE>2</CODE></LI>
 203:          **     <LI><CODE>"I am a String"</CODE></LI>
 204:          **     <LI><CODE>new MyObject(2, "String", new StringBuffer())</CODE></LI>
 205:          ** </OL>
 206:          ** @return the initialization string for this object in Java.
 207:          **/
 208:         String getJavaInitializationString();
 209: }