001/* java.beans.BeanInfo
002   Copyright (C) 1998 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010 
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.beans;
040
041/**
042 ** BeanInfo can be implemented in order to provide explicit information to the Introspector.
043 **
044 ** When you write a BeanInfo class, you implement this interface
045 ** and provide explicit information by returning a non-null
046 ** value from the appropriate method.  If you wish the
047 ** Introspector to determine certain information in the normal
048 ** way, just return null (or in the case of int methods, return
049 ** -1).  There is a class called SimpleBeanInfo which returns
050 ** null from all methods, which you may extend and only
051 ** override the methods you wish to override.<P>
052 **
053 ** When you have written the class, give it the name
054 ** <CODE>&lt;Bean Class Name&gt;BeanInfo</CODE> and place it in
055 ** the same package as the Bean, or in the bean info search path
056 ** (see Introspector for information on search paths).<P>
057 **
058 ** A simple note about the way the Introspector interacts with
059 ** BeanInfo.  Introspectors look at a Bean class and determine
060 ** if there is a BeanInfo class with it.  If there is not a
061 ** BeanInfo class, it will behave as if the BeanInfo class
062 ** provided was a SimpleBeanInfo class (i.e. it will determine
063 ** all information automatically).<P>If there is a BeanInfo
064 ** class, then any methods that do *not* return null are
065 ** regarded as providing definitive information about the class
066 ** and all of its superclasses for those information types.
067 ** Even if a parent BeanInfo class explicitly returns that
068 ** information, it will not be used.
069 **
070 ** @author John Keiser
071 ** @since JDK1.1
072 ** @version 1.1.0, 28 Jul 1998
073 **/
074
075public interface BeanInfo {
076        /** Use this as a parameter for the getIcon() command to retrieve a certain type of icon. **/
077        int ICON_COLOR_16x16 = 1;
078        /** Use this as a parameter for the getIcon() command to retrieve a certain type of icon. **/
079        int ICON_COLOR_32x32 = 2;
080        /** Use this as a parameter for the getIcon() command to retrieve a certain type of icon. **/
081        int ICON_MONO_16x16 = 3;
082        /** Use this as a parameter for the getIcon() command to retrieve a certain type of icon. **/
083        int ICON_MONO_32x32 = 4;
084
085        /** Get the general description of this Bean type.
086         ** @return the BeanDescriptor for the Bean, or null if
087         **         the BeanDescriptor should be obtained by
088         **         Introspection.
089         **/
090        BeanDescriptor getBeanDescriptor();
091
092        /** Get the events this Bean type fires.
093         ** @return the EventDescriptors representing events this
094         **         Bean fires.  Returns <CODE>null</CODE> if the
095         **         events are to be acquired by Introspection.
096         **/
097        EventSetDescriptor[] getEventSetDescriptors();
098
099        /** 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}