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 56 public interface PropertyEditor { 57 58 /** 59 * Set (or change) the object that is to be edited. Primitive types such 60 * as "int" must be wrapped as the corresponding object type such as 61 * "java.lang.Integer". 62 * 63 * @param value The new target object to be edited. Note that this 64 * object should not be modified by the PropertyEditor, rather 65 * the PropertyEditor should create a new object to hold any 66 * modified value. 67 */ 68 void setValue(Object value); 69 70 /** 71 * Gets the property value. 72 * 73 * @return The value of the property. Primitive types such as "int" will 74 * be wrapped as the corresponding object type such as "java.lang.Integer". 75 */ 76 77 Object getValue(); 78 79 //---------------------------------------------------------------------- 80 81 /** 82 * Determines whether this property editor is paintable. 83 * 84 * @return True if the class will honor the paintValue method. 85 */ 86 87 boolean isPaintable(); 88 89 /** 90 * Paint a representation of the value into a given area of screen 91 * real estate. Note that the propertyEditor is responsible for doing 92 * its own clipping so that it fits into the given rectangle. 93 * <p> 94 * If the PropertyEditor doesn't honor paint requests (see isPaintable) 95 * this method should be a silent noop. 96 * <p> 97 * The given Graphics object will have the default font, color, etc of 98 * the parent container. The PropertyEditor may change graphics attributes 99 * such as font and color and doesn't need to restore the old values. 100 * 101 * @param gfx Graphics object to paint into. 102 * @param box Rectangle within graphics object into which we should paint. 103 */ 104 void paintValue(java.awt.Graphics gfx, java.awt.Rectangle box); 105 106 //---------------------------------------------------------------------- 107 108 /** 109 * Returns a fragment of Java code that can be used to set a property 110 * to match the editors current state. This method is intended 111 * for use when generating Java code to reflect changes made through the 112 * property editor. 113 * <p> 114 * The code fragment should be context free and must be a legal Java 115 * expression as specified by the JLS. 116 * <p> 117 * Specifically, if the expression represents a computation then all 118 * classes and static members should be fully qualified. This rule 119 * applies to constructors, static methods and non primitive arguments. 120 * <p> 121 * Caution should be used when evaluating the expression as it may throw 122 * exceptions. In particular, code generators must ensure that generated 123 * code will compile in the presence of an expression that can throw 124 * checked exceptions. 125 * <p> 126 * Example results are: 127 * <ul> 128 * <li>Primitive expresssion: <code>2</code> 129 * <li>Class constructor: <code>new java.awt.Color(127,127,34)</code> 130 * <li>Static field: <code>java.awt.Color.orange</code> 131 * <li>Static method: <code>javax.swing.Box.createRigidArea(new 132 * java.awt.Dimension(0, 5))</code> 133 * </ul> 134 * 135 * @return a fragment of Java code representing an initializer for the 136 * current value. It should not contain a semi-colon 137 * ('<code>;</code>') to end the expression. 138 */ 139 String getJavaInitializationString(); 140 141 //---------------------------------------------------------------------- 142 143 /** 144 * Gets the property value as text. 145 * 146 * @return The property value as a human editable string. 147 * <p> Returns null if the value can't be expressed as an editable string. 148 * <p> If a non-null value is returned, then the PropertyEditor should 149 * be prepared to parse that string back in setAsText(). 150 */ 151 String getAsText(); 152 153 /** 154 * Set the property value by parsing a given String. May raise 155 * java.lang.IllegalArgumentException if either the String is 156 * badly formatted or if this kind of property can't be expressed 157 * as text. 158 * @param text The string to be parsed. 159 */ 160 void setAsText(String text) throws java.lang.IllegalArgumentException; 161 162 //---------------------------------------------------------------------- 163 164 /** 165 * If the property value must be one of a set of known tagged values, 166 * then this method should return an array of the tags. This can 167 * be used to represent (for example) enum values. If a PropertyEditor 168 * supports tags, then it should support the use of setAsText with 169 * a tag value as a way of setting the value and the use of getAsText 170 * to identify the current value. 171 * 172 * @return The tag values for this property. May be null if this 173 * property cannot be represented as a tagged value. 174 * 175 */ 176 String[] getTags(); 177 178 //---------------------------------------------------------------------- 179 180 /** 181 * A PropertyEditor may choose to make available a full custom Component 182 * that edits its property value. It is the responsibility of the 183 * PropertyEditor to hook itself up to its editor Component itself and 184 * to report property value changes by firing a PropertyChange event. 185 * <P> 186 * The higher-level code that calls getCustomEditor may either embed 187 * the Component in some larger property sheet, or it may put it in 188 * its own individual dialog, or ... 189 * 190 * @return A java.awt.Component that will allow a human to directly 191 * edit the current property value. May be null if this is 192 * not supported. 193 */ 194 195 java.awt.Component getCustomEditor(); 196 197 /** 198 * Determines whether this property editor supports a custom editor. 199 * 200 * @return True if the propertyEditor can provide a custom editor. 201 */ 202 boolean supportsCustomEditor(); 203 204 //---------------------------------------------------------------------- 205 206 /** 207 * Adds a listener for the value change. 208 * When the property editor changes its value 209 * it should fire a {@link PropertyChangeEvent} 210 * on all registered {@link PropertyChangeListener}s, 211 * specifying the {@code null} value for the property name 212 * and itself as the source. 213 * 214 * @param listener the {@link PropertyChangeListener} to add 215 */ 216 void addPropertyChangeListener(PropertyChangeListener listener); 217 218 /** 219 * Removes a listener for the value change. 220 * 221 * @param listener the {@link PropertyChangeListener} to remove 222 */ 223 void removePropertyChangeListener(PropertyChangeListener listener); 224 225 }