libjava/java/beans/PropertyEditorSupport.java

   1 /* java.beans.PropertyEditorSupport
   2    Copyright (C) 1998, 2004 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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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 /**
  43  * PropertyEditorSupport helps with PropertyEditors,
  44  * implementing base functionality that they usually must
  45  * have but which is a pain to implement.  You may extend
  46  * from this class or use it as a standalone.<P>
  47  *
  48  * This class does not do any painting or actual editing.
  49  * For that, you must use or extend it.  See the
  50  * PropertyEditor class for better descriptions of what
  51  * the various methods do.
  52  *
  53  * @author John Keiser
  54  * @author Robert Schuster
  55  * @since 1.1
  56  * @status updated to 1.5
  57  */
  58 public class PropertyEditorSupport implements PropertyEditor
  59 {
  60   Object eventSource;
  61   Object value;
  62   PropertyChangeSupport pSupport;
  63
  64   /** Call this constructor when you are deriving from
  65    * PropertyEditorSupport.
  66    *
  67    * Using this constructor the event source is this PropertyEditorSupport
  68    * instance itself.
  69    *
  70    * @since 1.5
  71    * @specnote this was <code>protected</code> prior to 1.5
  72    */
  73   public PropertyEditorSupport()
  74   {
  75     eventSource = this;
  76     pSupport = new PropertyChangeSupport(this);
  77   }
  78
  79   /** Call this constructor when you are using
  80    * PropertyEditorSupport as a helper object.
  81    *
  82    * This constructor throws a NullPointerException when <code>source</code> is <code>null</code>,
  83    * for compatibility reasons with J2SDK 1.5.0 .
  84    *
  85    * @param source The source to use when firing
  86    * property change events.
  87    * @since 1.5
  88    * @specnote this was <code>protected</code> prior to 1.5
  89    */
  90   public PropertyEditorSupport(Object source)
  91   {
  92     // note: constructor rejects source being null for the sake of compatibility
  93     // with official 1.5.0 implementation
  94     if (source == null)
  95       throw new NullPointerException("Event source must not be null.");
  96
  97     eventSource = source;
  98     pSupport = new PropertyChangeSupport(eventSource);
  99   }
 100
 101   /** Sets the current value of the property and a property change
 102    * event is fired to all registered PropertyChangeListener instances.
 103    *
 104    * @param newValue The new value for the property.
 105    */
 106   public void setValue(Object newValue)
 107   {
 108     value = newValue;
 109
 110     // specification in java.beans.PropertyChangeEvent says
 111     // that without a property name (first argument) the
 112     // new and the old value should always be null
 113     pSupport.firePropertyChange(null, null, null);
 114   }
 115
 116   /** Gets the current value of the property.
 117    *
 118    * @return the current value of the property.
 119    */
 120   public Object getValue()
 121   {
 122     return value;
 123   }
 124
 125   /** Gets whether this object is paintable or not.
 126    *
 127    * @return <CODE>false</CODE>
 128    */
 129   public boolean isPaintable()
 130   {
 131     return false;
 132   }
 133
 134   /** Paints this object.  This class does nothing in
 135    * this method.
 136    */
 137   public void paintValue(java.awt.Graphics g, java.awt.Rectangle r)
 138   {
 139   }
 140
 141   /** Gets the Java initialization String for the current
 142    * value of the Object.  This class returns gibberish or
 143    * null (though the spec does not say which).<P>
 144    * <STRONG>Implementation Note:</STRONG> This class
 145    * returns the string "@$#^" to make sure the code will
 146    * be broken, so that you will know to override it when
 147    * you create your own property editor.
 148    *
 149    * @return the Java initialization string.
 150    */
 151   public String getJavaInitializationString()
 152   {
 153     return "@$#^";
 154   }
 155
 156   /** Gets the value as text.
 157    * In this class, you cannot count on getAsText() doing
 158    * anything useful, although in this implementation I
 159    * do toString().
 160    *
 161    * @return the value as text.
 162    */
 163   public String getAsText()
 164   {
 165     return value != null ? value.toString() : "null";
 166   }
 167
 168   /** Sets the value as text.
 169    * In this class, you cannot count on setAsText() doing
 170    * anything useful across implementations.
 171    * <STRONG>Implementation Note:</STRONG> In this
 172    * implementation it checks if the String is "null", and
 173    * if it is, sets the value to null, otherwise it throws
 174    * an IllegalArgumentException.
 175    *
 176    * @param s the text to convert to a new value.
 177    * @exception IllegalArgumentException if the text is
 178    * malformed.
 179    */
 180   public void setAsText(String s) throws IllegalArgumentException
 181   {
 182     if (s.equals("null"))
 183       setValue(null);
 184     else
 185       throw new IllegalArgumentException();
 186   }
 187
 188   /** Returns a list of possible choices for the value.
 189    *
 190    * @return <CODE>null</CODE>
 191    */
 192   public String[] getTags()
 193   {
 194     return null;
 195   }
 196
 197   /** Returns a custom component to edit the value.
 198    *
 199    * @return <CODE>null</CODE> in this class.
 200    */
 201   public java.awt.Component getCustomEditor()
 202   {
 203     return null;
 204   }
 205
 206   /** Finds out whether this property editor supports a
 207    * custom component to edit its value.
 208    *
 209    * @return <CODE>false</CODE> in this class.
 210    */
 211   public boolean supportsCustomEditor()
 212   {
 213     return false;
 214   }
 215
 216   /** Adds a property change listener to this property editor.
 217    *
 218    * @param l the listener to add.
 219    */
 220   public void addPropertyChangeListener(PropertyChangeListener l)
 221   {
 222     pSupport.addPropertyChangeListener(l);
 223   }
 224
 225   /** Removes a property change listener from this property editor.
 226    *
 227    * @param l the listener to remove.
 228    */
 229   public void removePropertyChangeListener(PropertyChangeListener l)
 230   {
 231     pSupport.removePropertyChangeListener(l);
 232   }
 233
 234   /** Notifies people that we've changed, although we don't
 235    * tell them just how.
 236    */
 237   public void firePropertyChange()
 238   {
 239     pSupport.firePropertyChange(null, null, null);
 240   }
 241
 242   /** Returns the bean that is used as the source of events.
 243    *
 244    * @return The event source object
 245    * @since 1.5
 246    */
 247   public Object getSource()
 248   {
 249     return eventSource;
 250   }
 251
 252   /** Sets the bean that is used as the source of events
 253    * when property changes occur.
 254    *
 255    * The event source bean is for informational purposes only
 256    * and should not be changed by the <code>PropertyEditor</code>.
 257    *
 258    * @param source
 259    * @since 1.5
 260    */
 261   public void setSource(Object source)
 262   {
 263     eventSource = source;
 264   }
 265 }