1 /* 2 * Copyright (c) 1996, 2003, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.beans; 27 28 /** 29 * A PropertyEditor class provides support for GUIs that want to 30 * allow users to edit a property value of a given type. 31 * <p> 32 * PropertyEditor supports a variety of different kinds of ways of 33 * displaying and updating property values. Most PropertyEditors will 34 * only need to support a subset of the different options available in 35 * this API. 36 * <P> 37 * Simple PropertyEditors may only support the getAsText and setAsText 38 * methods and need not support (say) paintValue or getCustomEditor. More 39 * complex types may be unable to support getAsText and setAsText but will 40 * instead support paintValue and getCustomEditor. 41 * <p> 42 * Every propertyEditor must support one or more of the three simple 43 * display styles. Thus it can either (1) support isPaintable or (2) 44 * both return a non-null String[] from getTags() and return a non-null 45 * value from getAsText or (3) simply return a non-null String from 46 * getAsText(). 47 * <p> 48 * Every property editor must support a call on setValue when the argument 49 * object is of the type for which this is the corresponding propertyEditor. 50 * In addition, each property editor must either support a custom editor, 51 * or support setAsText. 52 * <p> 53 * Each PropertyEditor should have a null constructor. 54 * 55 * @since 1.1 56 */ 57 58 public interface PropertyEditor { 59 60 /** 61 * Set (or change) the object that is to be edited. Primitive types such 62 * as "int" must be wrapped as the corresponding object type such as 63 * "java.lang.Integer". 64 * 65 * @param value The new target object to be edited. Note that this 66 * object should not be modified by the PropertyEditor, rather 67 * the PropertyEditor should create a new object to hold any 68 * modified value. 69 */ 70 void setValue(Object value); 71 72 /** 73 * Gets the property value. 74 * 75 * @return The value of the property. Primitive types such as "int" will 76 * be wrapped as the corresponding object type such as "java.lang.Integer". 77 */ 78 79 Object getValue(); 80 81 //---------------------------------------------------------------------- 82 83 /** 84 * Determines whether this property editor is paintable. 85 * 86 * @return True if the class will honor the paintValue method. 87 */ 88 89 boolean isPaintable(); 90 91 /** 92 * Paint a representation of the value into a given area of screen 93 * real estate. Note that the propertyEditor is responsible for doing 94 * its own clipping so that it fits into the given rectangle. 95 * <p> 96 * If the PropertyEditor doesn't honor paint requests (see isPaintable) 97 * this method should be a silent noop. 98 * <p> 99 * The given Graphics object will have the default font, color, etc of 100 * the parent container. The PropertyEditor may change graphics attributes 101 * such as font and color and doesn't need to restore the old values. 102 * 103 * @param gfx Graphics object to paint into. 104 * @param box Rectangle within graphics object into which we should paint. 105 */ 106 void paintValue(java.awt.Graphics gfx, java.awt.Rectangle box); 107 108 //---------------------------------------------------------------------- 109 110 /** 111 * Returns a fragment of Java code that can be used to set a property 112 * to match the editors current state. This method is intended 113 * for use when generating Java code to reflect changes made through the 114 * property editor. 115 * <p> 116 * The code fragment should be context free and must be a legal Java 117 * expression as specified by the JLS. 118 * <p> 119 * Specifically, if the expression represents a computation then all 120 * classes and static members should be fully qualified. This rule 121 * applies to constructors, static methods and non primitive arguments. 122 * <p> 123 * Caution should be used when evaluating the expression as it may throw 124 * exceptions. In particular, code generators must ensure that generated 125 * code will compile in the presence of an expression that can throw 126 * checked exceptions. 127 * <p> 128 * Example results are: 129 * <ul> 130 * <li>Primitive expresssion: <code>2</code> 131 * <li>Class constructor: <code>new java.awt.Color(127,127,34)</code> 132 * <li>Static field: <code>java.awt.Color.orange</code> 133 * <li>Static method: <code>javax.swing.Box.createRigidArea(new 134 * java.awt.Dimension(0, 5))</code> 135 * </ul> 136 * 137 * @return a fragment of Java code representing an initializer for the 138 * current value. It should not contain a semi-colon 139 * ('<code>;</code>') to end the expression. 140 */ 141 String getJavaInitializationString(); 142 143 //---------------------------------------------------------------------- 144 145 /** 146 * Gets the property value as text. 147 * 148 * @return The property value as a human editable string. 149 * <p> Returns null if the value can't be expressed as an editable string. 150 * <p> If a non-null value is returned, then the PropertyEditor should 151 * be prepared to parse that string back in setAsText(). 152 */ 153 String getAsText(); 154 155 /** 156 * Set the property value by parsing a given String. May raise 157 * java.lang.IllegalArgumentException if either the String is 158 * badly formatted or if this kind of property can't be expressed 159 * as text. 160 * @param text The string to be parsed. 161 */ 162 void setAsText(String text) throws java.lang.IllegalArgumentException; 163 164 //---------------------------------------------------------------------- 165 166 /** 167 * If the property value must be one of a set of known tagged values, 168 * then this method should return an array of the tags. This can 169 * be used to represent (for example) enum values. If a PropertyEditor 170 * supports tags, then it should support the use of setAsText with 171 * a tag value as a way of setting the value and the use of getAsText 172 * to identify the current value. 173 * 174 * @return The tag values for this property. May be null if this 175 * property cannot be represented as a tagged value. 176 * 177 */ 178 String[] getTags(); 179 180 //---------------------------------------------------------------------- 181 182 /** 183 * A PropertyEditor may choose to make available a full custom Component 184 * that edits its property value. It is the responsibility of the 185 * PropertyEditor to hook itself up to its editor Component itself and 186 * to report property value changes by firing a PropertyChange event. 187 * <P> 188 * The higher-level code that calls getCustomEditor may either embed 189 * the Component in some larger property sheet, or it may put it in 190 * its own individual dialog, or ... 191 * 192 * @return A java.awt.Component that will allow a human to directly 193 * edit the current property value. May be null if this is 194 * not supported. 195 */ 196 197 java.awt.Component getCustomEditor(); 198 199 /** 200 * Determines whether this property editor supports a custom editor. 201 * 202 * @return True if the propertyEditor can provide a custom editor. 203 */ 204 boolean supportsCustomEditor(); 205 206 //---------------------------------------------------------------------- 207 208 /** 209 * Adds a listener for the value change. 210 * When the property editor changes its value 211 * it should fire a {@link PropertyChangeEvent} 212 * on all registered {@link PropertyChangeListener}s, 213 * specifying the {@code null} value for the property name 214 * and itself as the source. 215 * 216 * @param listener the {@link PropertyChangeListener} to add 217 */ 218 void addPropertyChangeListener(PropertyChangeListener listener); 219 220 /** 221 * Removes a listener for the value change. 222 * 223 * @param listener the {@link PropertyChangeListener} to remove 224 */ 225 void removePropertyChangeListener(PropertyChangeListener listener); 226 227 }