Source for java.beans.BeanInfo

   1: /* java.beans.BeanInfo
   2:    Copyright (C) 1998 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10:  
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package java.beans;
  40: 
  41: /**
  42:  ** BeanInfo can be implemented in order to provide explicit information to the Introspector.
  43:  **
  44:  ** When you write a BeanInfo class, you implement this interface
  45:  ** and provide explicit information by returning a non-null
  46:  ** value from the appropriate method.  If you wish the
  47:  ** Introspector to determine certain information in the normal
  48:  ** way, just return null (or in the case of int methods, return
  49:  ** -1).  There is a class called SimpleBeanInfo which returns
  50:  ** null from all methods, which you may extend and only
  51:  ** override the methods you wish to override.<P>
  52:  **
  53:  ** When you have written the class, give it the name
  54:  ** <CODE>&lt;Bean Class Name&gt;BeanInfo</CODE> and place it in
  55:  ** the same package as the Bean, or in the bean info search path
  56:  ** (see Introspector for information on search paths).<P>
  57:  **
  58:  ** A simple note about the way the Introspector interacts with
  59:  ** BeanInfo.  Introspectors look at a Bean class and determine
  60:  ** if there is a BeanInfo class with it.  If there is not a
  61:  ** BeanInfo class, it will behave as if the BeanInfo class
  62:  ** provided was a SimpleBeanInfo class (i.e. it will determine
  63:  ** all information automatically).<P>If there is a BeanInfo
  64:  ** class, then any methods that do *not* return null are
  65:  ** regarded as providing definitive information about the class
  66:  ** and all of its superclasses for those information types.
  67:  ** Even if a parent BeanInfo class explicitly returns that
  68:  ** information, it will not be used.
  69:  **
  70:  ** @author John Keiser
  71:  ** @since JDK1.1
  72:  ** @version 1.1.0, 28 Jul 1998
  73:  **/
  74: 
  75: public interface BeanInfo {
  76:     /** Use this as a parameter for the getIcon() command to retrieve a certain type of icon. **/
  77:     int ICON_COLOR_16x16 = 1;
  78:     /** Use this as a parameter for the getIcon() command to retrieve a certain type of icon. **/
  79:     int ICON_COLOR_32x32 = 2;
  80:     /** Use this as a parameter for the getIcon() command to retrieve a certain type of icon. **/
  81:     int ICON_MONO_16x16 = 3;
  82:     /** Use this as a parameter for the getIcon() command to retrieve a certain type of icon. **/
  83:     int ICON_MONO_32x32 = 4;
  84: 
  85:     /** Get the general description of this Bean type.
  86:      ** @return the BeanDescriptor for the Bean, or null if
  87:      **         the BeanDescriptor should be obtained by
  88:      **         Introspection.
  89:      **/
  90:     BeanDescriptor getBeanDescriptor();
  91: 
  92:     /** Get the events this Bean type fires.
  93:      ** @return the EventDescriptors representing events this
  94:      **         Bean fires.  Returns <CODE>null</CODE> if the
  95:      **         events are to be acquired by Introspection.
  96:      **/
  97:     EventSetDescriptor[] getEventSetDescriptors();
  98: 
  99:     /** Get the "default" event, basically the one a RAD tool
 100:      ** user is most likely to select.
 101:      ** @return the index into the getEventSetDescriptors()
 102:      **         that the user is most likely to use.  Returns
 103:      **         <CODE>-1</CODE> if there is no default event.
 104:      **/
 105:     int getDefaultEventIndex();
 106: 
 107:     /** Get the properties (get/set method pairs) this Bean
 108:      ** type supports.
 109:      ** @return the PropertyDescriptors representing the
 110:      **         properties this Bean type supports.
 111:      **         Returns <CODE>null</CODE> if the properties
 112:      **         are to be obtained by Introspection.
 113:      **/
 114:     PropertyDescriptor[] getPropertyDescriptors();
 115: 
 116:     /** Get the "default" property, basically the one a RAD
 117:      ** tool user is most likely to select.
 118:      ** @return the index into the getPropertyDescriptors()
 119:      **         that the user is most likely to use.  Returns
 120:      **         <CODE>-1</CODE> if there is no default event.
 121:      **/
 122:     int getDefaultPropertyIndex();
 123: 
 124:     /** Get the methods this Bean type supports.
 125:      ** @return the MethodDescriptors representing the
 126:      **         methods this Bean type supports.  Returns
 127:      **         <CODE>null</CODE> if the methods are to be
 128:      **         obtained by Introspection.
 129:      **/
 130:     MethodDescriptor[] getMethodDescriptors();
 131: 
 132:     /** Get additional BeanInfos representing this Bean.
 133:      ** In this version of JavaBeans, this method is used so
 134:      ** that space and time can be saved by reading a BeanInfo
 135:      ** for each class in the hierarchy (super, super(super),
 136:      ** and so on).<P>
 137:      **
 138:      ** The order of precedence when two pieces of BeanInfo
 139:      ** conflict (such as two PropertyDescriptors that have
 140:      ** the same name), in order from highest precedence to
 141:      ** lowest, is:
 142:      ** <OL>
 143:      ** <LI>This BeanInfo object.</LI>
 144:      ** <LI><CODE>getAdditionalBeanInfo()[getAdditionalBeanInfo().length]</CODE></LI>
 145:      ** <LI> ... </LI>
 146:      ** <LI><CODE>getAdditionalBeanInfo()[1]</CODE></LI>
 147:      ** <LI><CODE>getAdditionalBeanInfo()[0]</CODE></LI>
 148:      ** </OL><P>
 149:      **
 150:      ** <STRONG>Spec Note:</STRONG> It is possible that
 151:      ** returning <CODE>null</CODE> from this method could
 152:      ** stop Introspection in its tracks, but it is unclear
 153:      ** from the spec whether this is the case.
 154:      **
 155:      ** @return additional BeanInfos representing this Bean.
 156:      **         <CODE>null</CODE> may be returned (see Spec
 157:      **         Note, above).
 158:      **/
 159:     BeanInfo[] getAdditionalBeanInfo();
 160: 
 161:     /** Get a visual icon for this Bean.
 162:      ** A Bean does not have to support icons, and if it does
 163:      ** support icons, it does not have to support every single
 164:      ** type.  Sun recommends that if you only support one
 165:      ** type, you support 16x16 color.  Sun also notes that you
 166:      ** should try to use a type (like GIF) that allows for
 167:      ** transparent pixels, so that the background of the RAD
 168:      ** tool can show through.<P>
 169:      **
 170:      ** <STRONG>Spec Note:</STRONG> If you do not support the
 171:      ** type of icon that is being asked for, but you do
 172:      ** support another type, it is unclear whether you should
 173:      ** return the other type or not.  I would presume not.
 174:      **
 175:      ** @param iconType the type of icon to get (see the
 176:      **        ICON_* constants in this class).
 177:      ** @return the icon, or null if that type of icon is
 178:      **         unsupported by this Bean.
 179:      **/
 180:     java.awt.Image getIcon(int iconType);
 181: }