home *** CD-ROM | disk | FTP | other *** search
/ Chip 1998 November / Chip_1998-11_cd.bin / tema / Cafe / main.bin / PropertyEditor.java < prev    next >
Text File  |  1997-10-01  |  8KB  |  194 lines
  1. /*
  2.  * @(#)PropertyEditor.java    1.26 97/05/26  
  3.  * 
  4.  * Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion bdk_beta
  20.  * 
  21.  */
  22.  
  23. package java.beans;
  24.  
  25. /**
  26.  * A PropertyEditor class provides support for GUIs that want to
  27.  * allow users to edit a property value of a given type.
  28.  * <p>
  29.  * PropertyEditor supports a variety of different kinds of ways of
  30.  * displaying and updating property values.  Most PropertyEditors will
  31.  * only need to support a subset of the different options available in
  32.  * this API.
  33.  * <P>
  34.  * Simple PropertyEditors may only support the getAsText and setAsText
  35.  * methods and need not support (say) paintValue or getCustomEditor.  More
  36.  * complex types may be unable to support getAsText and setAsText but will
  37.  * instead support paintValue and getCustomEditor.
  38.  * <p>
  39.  * Every propertyEditor must support one or more of the three simple
  40.  * display styles.  Thus it can either (1) support isPaintable or (2)
  41.  * both return a non-null String[] from getTags() and return a non-null
  42.  * value from getAsText or (3) simply return a non-null String from 
  43.  * getAsText().
  44.  * <p>
  45.  * Every property editor must support a call on setValue when the argument
  46.  * object is of the type for which this is the corresponding propertyEditor.
  47.  * In addition, each property editor must either support a custom editor,
  48.  * or support setAsText.
  49.  * <p>
  50.  * Each PropertyEditor should have a null constructor.
  51.  */
  52.  
  53. public interface PropertyEditor {
  54.  
  55.     /**
  56.      * Set (or change) the object that is to be edited.  Builtin types such
  57.      * as "int" must be wrapped as the corresponding object type such as
  58.      * "java.lang.Integer".
  59.      *
  60.      * @param value The new target object to be edited.  Note that this
  61.      *     object should not be modified by the PropertyEditor, rather 
  62.      *     the PropertyEditor should create a new object to hold any
  63.      *     modified value.
  64.      */
  65.     void setValue(Object value);
  66.  
  67.     /**
  68.      * @return The value of the property.  Builtin types such as "int" will
  69.      * be wrapped as the corresponding object type such as "java.lang.Integer".
  70.      */
  71.  
  72.     Object getValue();
  73.  
  74.     //----------------------------------------------------------------------
  75.  
  76.     /**
  77.      * @return  True if the class will honor the paintValue method.
  78.      */
  79.  
  80.     boolean isPaintable();
  81.  
  82.     /**
  83.      * Paint a representation of the value into a given area of screen
  84.      * real estate.  Note that the propertyEditor is responsible for doing
  85.      * its own clipping so that it fits into the given rectangle.
  86.      * <p>
  87.      * If the PropertyEditor doesn't honor paint requests (see isPaintable)
  88.      * this method should be a silent noop.
  89.      * <p>
  90.      * The given Graphics object will have the default font, color, etc of
  91.      * the parent container.  The PropertyEditor may change graphics attributes
  92.      * such as font and color and doesn't need to restore the old values.
  93.      *
  94.      * @param gfx  Graphics object to paint into.
  95.      * @param box  Rectangle within graphics object into which we should paint.
  96.      */
  97.     void paintValue(java.awt.Graphics gfx, java.awt.Rectangle box);
  98.  
  99.     //----------------------------------------------------------------------
  100.  
  101.     /**
  102.      * This method is intended for use when generating Java code to set
  103.      * the value of the property.  It should return a fragment of Java code
  104.      * that can be used to initialize a variable with the current property
  105.      * value.
  106.      * <p>
  107.      * Example results are "2", "new Color(127,127,34)", "Color.orange", etc.
  108.      *
  109.      * @return A fragment of Java code representing an initializer for the
  110.      *       current value.
  111.      */
  112.     String getJavaInitializationString();
  113.  
  114.     //----------------------------------------------------------------------
  115.  
  116.     /**
  117.      * @return The property value as a human editable string.
  118.      * <p>   Returns null if the value can't be expressed as an editable string.
  119.      * <p>   If a non-null value is returned, then the PropertyEditor should
  120.      *         be prepared to parse that string back in setAsText().
  121.      */
  122.     String getAsText();
  123.  
  124.     /**
  125.      * Set the property value by parsing a given String.  May raise
  126.      * java.lang.IllegalArgumentException if either the String is
  127.      * badly formatted or if this kind of property can't be expressed
  128.      * as text.
  129.      * @param text  The string to be parsed.
  130.      */
  131.     void setAsText(String text) throws java.lang.IllegalArgumentException;
  132.  
  133.     //----------------------------------------------------------------------
  134.  
  135.     /**
  136.      * If the property value must be one of a set of known tagged values, 
  137.      * then this method should return an array of the tags.  This can
  138.      * be used to represent (for example) enum values.  If a PropertyEditor
  139.      * supports tags, then it should support the use of setAsText with
  140.      * a tag value as a way of setting the value and the use of getAsText
  141.      * to identify the current value.
  142.      *
  143.      * @return The tag values for this property.  May be null if this 
  144.      *   property cannot be represented as a tagged value.
  145.      *    
  146.      */
  147.     String[] getTags();
  148.  
  149.     //----------------------------------------------------------------------
  150.  
  151.     /**
  152.      * A PropertyEditor may choose to make available a full custom Component
  153.      * that edits its property value.  It is the responsibility of the
  154.      * PropertyEditor to hook itself up to its editor Component itself and
  155.      * to report property value changes by firing a PropertyChange event.
  156.      * <P>
  157.      * The higher-level code that calls getCustomEditor may either embed
  158.      * the Component in some larger property sheet, or it may put it in
  159.      * its own individual dialog, or ...
  160.      *
  161.      * @return A java.awt.Component that will allow a human to directly
  162.      *      edit the current property value.  May be null if this is
  163.      *        not supported.
  164.      */
  165.  
  166.     java.awt.Component getCustomEditor();
  167.  
  168.     /**
  169.      * @return  True if the propertyEditor can provide a custom editor.
  170.      */
  171.     boolean supportsCustomEditor();
  172.   
  173.     //----------------------------------------------------------------------
  174.  
  175.     /**
  176.      * Register a listener for the PropertyChange event.  When a
  177.      * PropertyEditor changes its value it should fire a PropertyChange
  178.      * event on all registered PropertyChangeListeners, specifying the
  179.      * null value for the property name and itself as the source.
  180.      *
  181.      * @param listener  An object to be invoked when a PropertyChange
  182.      *        event is fired.
  183.      */
  184.     void addPropertyChangeListener(PropertyChangeListener listener);
  185.  
  186.     /**
  187.      * Remove a listener for the PropertyChange event.
  188.      *
  189.      * @param listener  The PropertyChange listener to be removed.
  190.      */
  191.     void removePropertyChangeListener(PropertyChangeListener listener);
  192.  
  193. }
  194.