PropertyEditor


1   /*
2    * @(#)PropertyEditor.java  1.37 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.beans;
9   
10  /**
11   * A PropertyEditor class provides support for GUIs that want to
12   * allow users to edit a property value of a given type.
13   * <p>
14   * PropertyEditor supports a variety of different kinds of ways of
15   * displaying and updating property values.  Most PropertyEditors will
16   * only need to support a subset of the different options available in
17   * this API.
18   * <P>
19   * Simple PropertyEditors may only support the getAsText and setAsText
20   * methods and need not support (say) paintValue or getCustomEditor.  More
21   * complex types may be unable to support getAsText and setAsText but will
22   * instead support paintValue and getCustomEditor.
23   * <p>
24   * Every propertyEditor must support one or more of the three simple
25   * display styles.  Thus it can either (1) support isPaintable or (2)
26   * both return a non-null String[] from getTags() and return a non-null
27   * value from getAsText or (3) simply return a non-null String from 
28   * getAsText().
29   * <p>
30   * Every property editor must support a call on setValue when the argument
31   * object is of the type for which this is the corresponding propertyEditor.
32   * In addition, each property editor must either support a custom editor,
33   * or support setAsText.
34   * <p>
35   * Each PropertyEditor should have a null constructor.
36   */
37  
38  public interface PropertyEditor {
39  
40      /**
41       * Set (or change) the object that is to be edited.  Primitive types such
42       * as "int" must be wrapped as the corresponding object type such as
43       * "java.lang.Integer".
44       *
45       * @param value The new target object to be edited.  Note that this
46       *     object should not be modified by the PropertyEditor, rather 
47       *     the PropertyEditor should create a new object to hold any
48       *     modified value.
49       */
50      void setValue(Object   value);
51  
52      /**
53       * Gets the property value.
54       *
55       * @return The value of the property.  Primitive types such as "int" will
56       * be wrapped as the corresponding object type such as "java.lang.Integer".
57       */
58  
59      Object   getValue();
60  
61      //----------------------------------------------------------------------
62  
63      /**
64       * Determines whether this property editor is paintable.
65       *
66       * @return  True if the class will honor the paintValue method.
67       */
68  
69      boolean isPaintable();
70  
71      /**
72       * Paint a representation of the value into a given area of screen
73       * real estate.  Note that the propertyEditor is responsible for doing
74       * its own clipping so that it fits into the given rectangle.
75       * <p>
76       * If the PropertyEditor doesn't honor paint requests (see isPaintable)
77       * this method should be a silent noop.
78       * <p>
79       * The given Graphics object will have the default font, color, etc of
80       * the parent container.  The PropertyEditor may change graphics attributes
81       * such as font and color and doesn't need to restore the old values.
82       *
83       * @param gfx  Graphics object to paint into.
84       * @param box  Rectangle within graphics object into which we should paint.
85       */
86      void paintValue(java.awt.Graphics   gfx, java.awt.Rectangle   box);
87  
88      //----------------------------------------------------------------------
89  
90      /**
91       * Returns a fragment of Java code that can be used to set a property
92       * to match the editors current state. This method is intended
93       * for use when generating Java code to reflect changes made through the 
94       * property editor.
95       * <p>
96       * The code fragment should be context free and must be a legal Java 
97       * expression as specified by the JLS.
98       * <p>
99       * Specifically, if the expression represents a computation then all
100      * classes and static members should be fully qualified. This rule 
101      * applies to constructors, static methods and non primitive arguments.
102      * <p>
103      * Caution should be used when evaluating the expression as it may throw
104      * exceptions. In particular, code generators must ensure that generated
105      * code will compile in the presence of an expression that can throw 
106      * checked exceptions.
107      * <p>
108      * Example results are:
109      * <ul>
110      * <li>Primitive expresssion: <code>2</code>
111      * <li>Class constructor: <code>new java.awt.Color(127,127,34)</code>
112      * <li>Static field: <code>java.awt.Color.orange</code>
113      * <li>Static method: <code>javax.swing.Box.createRigidArea(new 
114      *                                   java.awt.Dimension(0, 5))</code>
115      * </ul>
116      *
117      * @return a fragment of Java code representing an initializer for the
118      *         current value. It should not contain a semi-colon 
119      *         ('<code>;</code>') to end the expression.
120      */
121     String   getJavaInitializationString();
122 
123     //----------------------------------------------------------------------
124 
125     /**
126      * Gets the property value as text.
127      * 
128      * @return The property value as a human editable string.
129      * <p>   Returns null if the value can't be expressed as an editable string.
130      * <p>   If a non-null value is returned, then the PropertyEditor should
131      *       be prepared to parse that string back in setAsText().
132      */
133     String   getAsText();
134 
135     /**
136      * Set the property value by parsing a given String.  May raise
137      * java.lang.IllegalArgumentException if either the String is
138      * badly formatted or if this kind of property can't be expressed
139      * as text.
140      * @param text  The string to be parsed.
141      */
142     void setAsText(String   text) throws java.lang.IllegalArgumentException  ;
143 
144     //----------------------------------------------------------------------
145 
146     /**
147      * If the property value must be one of a set of known tagged values, 
148      * then this method should return an array of the tags.  This can
149      * be used to represent (for example) enum values.  If a PropertyEditor
150      * supports tags, then it should support the use of setAsText with
151      * a tag value as a way of setting the value and the use of getAsText
152      * to identify the current value.
153      *
154      * @return The tag values for this property.  May be null if this 
155      *   property cannot be represented as a tagged value.
156      *  
157      */
158     String  [] getTags();
159 
160     //----------------------------------------------------------------------
161 
162     /**
163      * A PropertyEditor may choose to make available a full custom Component
164      * that edits its property value.  It is the responsibility of the
165      * PropertyEditor to hook itself up to its editor Component itself and
166      * to report property value changes by firing a PropertyChange event.
167      * <P>
168      * The higher-level code that calls getCustomEditor may either embed
169      * the Component in some larger property sheet, or it may put it in
170      * its own individual dialog, or ...
171      *
172      * @return A java.awt.Component that will allow a human to directly
173      *      edit the current property value.  May be null if this is
174      *      not supported.
175      */
176 
177     java.awt.Component   getCustomEditor();
178 
179     /**
180      * Determines whether this property editor supports a custom editor.
181      *
182      * @return  True if the propertyEditor can provide a custom editor.
183      */
184     boolean supportsCustomEditor();
185   
186     //----------------------------------------------------------------------
187 
188     /**
189      * Register a listener for the PropertyChange event.  When a
190      * PropertyEditor changes its value it should fire a PropertyChange
191      * event on all registered PropertyChangeListeners, specifying the
192      * null value for the property name and itself as the source.
193      *
194      * @param listener  An object to be invoked when a PropertyChange
195      *      event is fired.
196      */
197     void addPropertyChangeListener(PropertyChangeListener   listener);
198 
199     /**
200      * Remove a listener for the PropertyChange event.
201      *
202      * @param listener  The PropertyChange listener to be removed.
203      */
204     void removePropertyChangeListener(PropertyChangeListener   listener);
205 
206 }
207
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags