001 /*
002 * Copyright 1996-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.beans;
027
028 import java.beans.*;
029
030 /**
031 * This is a support class to help build property editors.
032 * <p>
033 * It can be used either as a base class or as a delagatee.
034 */
035
036 public class PropertyEditorSupport implements PropertyEditor {
037
038 /**
039 * Constructs a <code>PropertyEditorSupport</code> object.
040 *
041 * @since 1.5
042 */
043 public PropertyEditorSupport() {
044 setSource(this );
045 }
046
047 /**
048 * Constructs a <code>PropertyEditorSupport</code> object.
049 *
050 * @param source the source used for event firing
051 * @since 1.5
052 */
053 public PropertyEditorSupport(Object source) {
054 if (source == null) {
055 throw new NullPointerException();
056 }
057 setSource(source);
058 }
059
060 /**
061 * Returns the bean that is used as the
062 * source of events. If the source has not
063 * been explicitly set then this instance of
064 * <code>PropertyEditorSupport</code> is returned.
065 *
066 * @return the source object or this instance
067 * @since 1.5
068 */
069 public Object getSource() {
070 return source;
071 }
072
073 /**
074 * Sets the source bean.
075 * <p>
076 * The source bean is used as the source of events
077 * for the property changes. This source should be used for information
078 * purposes only and should not be modified by the PropertyEditor.
079 *
080 * @param source source object to be used for events
081 * @since 1.5
082 */
083 public void setSource(Object source) {
084 this .source = source;
085 }
086
087 /**
088 * Set (or change) the object that is to be edited.
089 *
090 * @param value The new target object to be edited. Note that this
091 * object should not be modified by the PropertyEditor, rather
092 * the PropertyEditor should create a new object to hold any
093 * modified value.
094 */
095 public void setValue(Object value) {
096 this .value = value;
097 firePropertyChange();
098 }
099
100 /**
101 * Gets the value of the property.
102 *
103 * @return The value of the property.
104 */
105 public Object getValue() {
106 return value;
107 }
108
109 //----------------------------------------------------------------------
110
111 /**
112 * Determines whether the class will honor the paintValue method.
113 *
114 * @return True if the class will honor the paintValue method.
115 */
116
117 public boolean isPaintable() {
118 return false;
119 }
120
121 /**
122 * Paint a representation of the value into a given area of screen
123 * real estate. Note that the propertyEditor is responsible for doing
124 * its own clipping so that it fits into the given rectangle.
125 * <p>
126 * If the PropertyEditor doesn't honor paint requests (see isPaintable)
127 * this method should be a silent noop.
128 *
129 * @param gfx Graphics object to paint into.
130 * @param box Rectangle within graphics object into which we should paint.
131 */
132 public void paintValue(java.awt.Graphics gfx, java.awt.Rectangle box) {
133 }
134
135 //----------------------------------------------------------------------
136
137 /**
138 * This method is intended for use when generating Java code to set
139 * the value of the property. It should return a fragment of Java code
140 * that can be used to initialize a variable with the current property
141 * value.
142 * <p>
143 * Example results are "2", "new Color(127,127,34)", "Color.orange", etc.
144 *
145 * @return A fragment of Java code representing an initializer for the
146 * current value.
147 */
148 public String getJavaInitializationString() {
149 return "???";
150 }
151
152 //----------------------------------------------------------------------
153
154 /**
155 * Gets the property value as a string suitable for presentation
156 * to a human to edit.
157 *
158 * @return The property value as a string suitable for presentation
159 * to a human to edit.
160 * <p> Returns "null" is the value can't be expressed as a string.
161 * <p> If a non-null value is returned, then the PropertyEditor should
162 * be prepared to parse that string back in setAsText().
163 */
164 public String getAsText() {
165 return (this .value != null) ? this .value.toString() : null;
166 }
167
168 /**
169 * Sets the property value by parsing a given String. May raise
170 * java.lang.IllegalArgumentException if either the String is
171 * badly formatted or if this kind of property can't be expressed
172 * as text.
173 *
174 * @param text The string to be parsed.
175 */
176 public void setAsText(String text)
177 throws java.lang.IllegalArgumentException {
178 if (value instanceof String) {
179 setValue(text);
180 return;
181 }
182 throw new java.lang.IllegalArgumentException(text);
183 }
184
185 //----------------------------------------------------------------------
186
187 /**
188 * If the property value must be one of a set of known tagged values,
189 * then this method should return an array of the tag values. This can
190 * be used to represent (for example) enum values. If a PropertyEditor
191 * supports tags, then it should support the use of setAsText with
192 * a tag value as a way of setting the value.
193 *
194 * @return The tag values for this property. May be null if this
195 * property cannot be represented as a tagged value.
196 *
197 */
198 public String[] getTags() {
199 return null;
200 }
201
202 //----------------------------------------------------------------------
203
204 /**
205 * A PropertyEditor may chose to make available a full custom Component
206 * that edits its property value. It is the responsibility of the
207 * PropertyEditor to hook itself up to its editor Component itself and
208 * to report property value changes by firing a PropertyChange event.
209 * <P>
210 * The higher-level code that calls getCustomEditor may either embed
211 * the Component in some larger property sheet, or it may put it in
212 * its own individual dialog, or ...
213 *
214 * @return A java.awt.Component that will allow a human to directly
215 * edit the current property value. May be null if this is
216 * not supported.
217 */
218
219 public java.awt.Component getCustomEditor() {
220 return null;
221 }
222
223 /**
224 * Determines whether the propertyEditor can provide a custom editor.
225 *
226 * @return True if the propertyEditor can provide a custom editor.
227 */
228 public boolean supportsCustomEditor() {
229 return false;
230 }
231
232 //----------------------------------------------------------------------
233
234 /**
235 * Register a listener for the PropertyChange event. The class will
236 * fire a PropertyChange value whenever the value is updated.
237 *
238 * @param listener An object to be invoked when a PropertyChange
239 * event is fired.
240 */
241 public synchronized void addPropertyChangeListener(
242 PropertyChangeListener listener) {
243 if (listeners == null) {
244 listeners = new java.util.Vector();
245 }
246 listeners.addElement(listener);
247 }
248
249 /**
250 * Remove a listener for the PropertyChange event.
251 *
252 * @param listener The PropertyChange listener to be removed.
253 */
254 public synchronized void removePropertyChangeListener(
255 PropertyChangeListener listener) {
256 if (listeners == null) {
257 return;
258 }
259 listeners.removeElement(listener);
260 }
261
262 /**
263 * Report that we have been modified to any interested listeners.
264 */
265 public void firePropertyChange() {
266 java.util.Vector targets;
267 synchronized (this ) {
268 if (listeners == null) {
269 return;
270 }
271 targets = (java.util.Vector) listeners.clone();
272 }
273 // Tell our listeners that "everything" has changed.
274 PropertyChangeEvent evt = new PropertyChangeEvent(source, null,
275 null, null);
276
277 for (int i = 0; i < targets.size(); i++) {
278 PropertyChangeListener target = (PropertyChangeListener) targets
279 .elementAt(i);
280 target.propertyChange(evt);
281 }
282 }
283
284 //----------------------------------------------------------------------
285
286 private Object value;
287 private Object source;
288 private java.util.Vector listeners;
289 }
|