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: }