001 /* java.beans.PropertyEditor 002 Copyright (C) 1998 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package java.beans; 040 041 /** 042 ** PropertyEditors are custom GUI editors for specific types of values. 043 ** 044 ** A PropertyEditor can be used, for example, if you are editing a type of value 045 ** that can be more easily represented graphically, such as a Point, or one that 046 ** can be more easily represented by a list, such as a boolean (true/false).<P> 047 ** 048 ** A PropertyEditor must be able to display its contents when asked to and 049 ** be able to allow the user to change its underlying field value. However, it 050 ** is not the PropertyEditor's responsibility to make the change to the 051 ** underlying Object; in fact, the PropertyEditor does not even know about the 052 ** Object it is actually editing--only about the property it is currently 053 ** editing. When a change is made to the property, the PropertyEditor must 054 ** simply fire a PropertyChangeEvent and allow the RAD tool to actually set 055 ** the property in the underlying Bean.<P> 056 ** 057 ** PropertyEditors should not change the Objects they are given by setValue(). 058 ** These Objects may or may not be the actual Objects which are properties of 059 ** the Bean being edited. Instead, PropertyEditors should create a new Object 060 ** and fire a PropertyChangeEvent with the old and new values.<P> 061 ** 062 ** PropertyEditors also must support the ability to return a Java 063 ** initialization string. See the getJavaInitializationString() method for 064 ** details.<P> 065 ** 066 ** There are several different ways a PropertyEditor may display and control 067 ** editing of its value. When multiple types of input and display are 068 ** given by a single PropertyEditor, the RAD tool may decide which of the call 069 ** to support. Some RAD tools may even be text-only, so even if you support 070 ** a graphical set and get, it may choose the text set and get whenever it can. 071 ** <OL> 072 ** <LI>Every PropertyEditor must support getValue() and setValue(). For 073 ** setValue(), the component must only support it when the argument is 074 ** the same type that the PropertyEditor supports.</LI> 075 ** <LI>Every PropertyEditor must support getJavaInitializationString().</LI> 076 ** <LI>You may support painting the value yourself if you wish. To do this, 077 ** have isPaintable() return true and implement the paintValue() method. 078 ** This method does not determine in any way how the value is edited; 079 ** merely how it is displayed.</LI> 080 ** <LI>Let the caller of the PropertyEditor give the user a text input. Do 081 ** this by returning a non-null String from getAsText(). If you support 082 ** text input, you *must* support setAsText().</LI> 083 ** <LI>Give the caller a set of possible values, such as "true"/"false", that 084 ** the user must select from. To do this, return the list of Strings 085 ** from the getTags() method. The RAD tool may choose to implement the 086 ** user input any way it wishes, and only guarantees that setAsText() will 087 ** only be called with one of the Strings returned from getTags().</LI> 088 ** <LI>You may support a whole custom editing control by supporting 089 ** getCustomEditor(). To do this, return true from supportsCustomEditor() 090 ** and return a Component that does the job. It is the component's job, 091 ** or the PropertyEditor's job, to make sure that when the editor changes 092 ** its value, the PropertyChangeEvent is thrown.</LI> 093 ** </OL> 094 ** 095 ** The PropertyEditor for a particular Bean can be found using the 096 ** PropertyEditorManager class, which goes through a series of different 097 ** checks to find the appropriate class.<P> 098 ** 099 ** 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 }