001 /*
002 * Copyright 1996-1999 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.beans;
027
028 /**
029 * A bean implementor who wishes to provide explicit information about
030 * their bean may provide a BeanInfo class that implements this BeanInfo
031 * interface and provides explicit information about the methods,
032 * properties, events, etc, of their bean.
033 * <p>
034 * A bean implementor doesn't need to provide a complete set of
035 * explicit information. You can pick and choose which information
036 * you want to provide and the rest will be obtained by automatic
037 * analysis using low-level reflection of the bean classes' methods
038 * and applying standard design patterns.
039 * <p>
040 * You get the opportunity to provide lots and lots of different
041 * information as part of the various XyZDescriptor classes. But
042 * don't panic, you only really need to provide the minimal core
043 * information required by the various constructors.
044 * <P>
045 * See also the SimpleBeanInfo class which provides a convenient
046 * "noop" base class for BeanInfo classes, which you can override
047 * for those specific places where you want to return explicit info.
048 * <P>
049 * To learn about all the behaviour of a bean see the Introspector class.
050 */
051
052 public interface BeanInfo {
053
054 /**
055 * Gets the beans <code>BeanDescriptor</code>.
056 *
057 * @return A BeanDescriptor providing overall information about
058 * the bean, such as its displayName, its customizer, etc. May
059 * return null if the information should be obtained by automatic
060 * analysis.
061 */
062 BeanDescriptor getBeanDescriptor();
063
064 /**
065 * Gets the beans <code>EventSetDescriptor</code>s.
066 *
067 * @return An array of EventSetDescriptors describing the kinds of
068 * events fired by this bean. May return null if the information
069 * should be obtained by automatic analysis.
070 */
071 EventSetDescriptor[] getEventSetDescriptors();
072
073 /**
074 * A bean may have a "default" event that is the event that will
075 * mostly commonly be used by humans when using the bean.
076 * @return Index of default event in the EventSetDescriptor array
077 * returned by getEventSetDescriptors.
078 * <P> Returns -1 if there is no default event.
079 */
080 int getDefaultEventIndex();
081
082 /**
083 * Gets the beans <code>PropertyDescriptor</code>s.
084 *
085 * @return An array of PropertyDescriptors describing the editable
086 * properties supported by this bean. May return null if the
087 * information should be obtained by automatic analysis.
088 * <p>
089 * If a property is indexed, then its entry in the result array will
090 * belong to the IndexedPropertyDescriptor subclass of PropertyDescriptor.
091 * A client of getPropertyDescriptors can use "instanceof" to check
092 * if a given PropertyDescriptor is an IndexedPropertyDescriptor.
093 */
094 PropertyDescriptor[] getPropertyDescriptors();
095
096 /**
097 * A bean may have a "default" property that is the property that will
098 * mostly commonly be initially chosen for update by human's who are
099 * customizing the bean.
100 * @return Index of default property in the PropertyDescriptor array
101 * returned by getPropertyDescriptors.
102 * <P> Returns -1 if there is no default property.
103 */
104 int getDefaultPropertyIndex();
105
106 /**
107 * Gets the beans <code>MethodDescriptor</code>s.
108 *
109 * @return An array of MethodDescriptors describing the externally
110 * visible methods supported by this bean. May return null if
111 * the information should be obtained by automatic analysis.
112 */
113 MethodDescriptor[] getMethodDescriptors();
114
115 /**
116 * This method allows a BeanInfo object to return an arbitrary collection
117 * of other BeanInfo objects that provide additional information on the
118 * current bean.
119 * <P>
120 * If there are conflicts or overlaps between the information provided
121 * by different BeanInfo objects, then the current BeanInfo takes precedence
122 * over the getAdditionalBeanInfo objects, and later elements in the array
123 * take precedence over earlier ones.
124 *
125 * @return an array of BeanInfo objects. May return null.
126 */
127 BeanInfo[] getAdditionalBeanInfo();
128
129 /**
130 * This method returns an image object that can be used to
131 * represent the bean in toolboxes, toolbars, etc. Icon images
132 * will typically be GIFs, but may in future include other formats.
133 * <p>
134 * Beans aren't required to provide icons and may return null from
135 * this method.
136 * <p>
137 * There are four possible flavors of icons (16x16 color,
138 * 32x32 color, 16x16 mono, 32x32 mono). If a bean choses to only
139 * support a single icon we recommend supporting 16x16 color.
140 * <p>
141 * We recommend that icons have a "transparent" background
142 * so they can be rendered onto an existing background.
143 *
144 * @param iconKind The kind of icon requested. This should be
145 * one of the constant values ICON_COLOR_16x16, ICON_COLOR_32x32,
146 * ICON_MONO_16x16, or ICON_MONO_32x32.
147 * @return An image object representing the requested icon. May
148 * return null if no suitable icon is available.
149 */
150 java.awt.Image getIcon(int iconKind);
151
152 /**
153 * Constant to indicate a 16 x 16 color icon.
154 */
155 final static int ICON_COLOR_16x16 = 1;
156
157 /**
158 * Constant to indicate a 32 x 32 color icon.
159 */
160 final static int ICON_COLOR_32x32 = 2;
161
162 /**
163 * Constant to indicate a 16 x 16 monochrome icon.
164 */
165 final static int ICON_MONO_16x16 = 3;
166
167 /**
168 * Constant to indicate a 32 x 32 monochrome icon.
169 */
170 final static int ICON_MONO_32x32 = 4;
171 }
|