1 |
14 |
jlechner |
/* 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 |
|
|
}
|