1 /*
2 * Copyright 1996-1999 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.beans;
27
28 /**
29 * A bean implementor who wishes to provide explicit information about
30 * their bean may provide a BeanInfo class that implements this BeanInfo
31 * interface and provides explicit information about the methods,
32 * properties, events, etc, of their bean.
33 * <p>
34 * A bean implementor doesn't need to provide a complete set of
35 * explicit information. You can pick and choose which information
36 * you want to provide and the rest will be obtained by automatic
37 * analysis using low-level reflection of the bean classes' methods
38 * and applying standard design patterns.
39 * <p>
40 * You get the opportunity to provide lots and lots of different
41 * information as part of the various XyZDescriptor classes. But
42 * don't panic, you only really need to provide the minimal core
43 * information required by the various constructors.
44 * <P>
45 * See also the SimpleBeanInfo class which provides a convenient
46 * "noop" base class for BeanInfo classes, which you can override
47 * for those specific places where you want to return explicit info.
48 * <P>
49 * To learn about all the behaviour of a bean see the Introspector class.
50 */
51
52 public interface BeanInfo {
53
54 /**
55 * Gets the beans <code>BeanDescriptor</code>.
56 *
57 * @return A BeanDescriptor providing overall information about
58 * the bean, such as its displayName, its customizer, etc. May
59 * return null if the information should be obtained by automatic
60 * analysis.
61 */
62 BeanDescriptor getBeanDescriptor();
63
64 /**
65 * Gets the beans <code>EventSetDescriptor</code>s.
66 *
67 * @return An array of EventSetDescriptors describing the kinds of
68 * events fired by this bean. May return null if the information
69 * should be obtained by automatic analysis.
70 */
71 EventSetDescriptor[] getEventSetDescriptors();
72
73 /**
74 * A bean may have a "default" event that is the event that will
75 * mostly commonly be used by humans when using the bean.
76 * @return Index of default event in the EventSetDescriptor array
77 * returned by getEventSetDescriptors.
78 * <P> Returns -1 if there is no default event.
79 */
80 int getDefaultEventIndex();
81
82 /**
83 * Returns descriptors for all properties of the bean.
84 * May return {@code null} if the information
85 * should be obtained by automatic analysis.
86 * <p>
87 * If a property is indexed, then its entry in the result array
88 * will belong to the {@link IndexedPropertyDescriptor} subclass
89 * of the {@link PropertyDescriptor} class.
90 * A client of the {@code getPropertyDescriptors} method
91 * can use "{@code instanceof}" to check
92 * whether a given {@code PropertyDescriptor}
93 * is an {@code IndexedPropertyDescriptor}.
94 *
95 * @return an array of {@code PropertyDescriptor}s
96 * describing all properties supported by the bean
97 * or {@code null}
98 */
99 PropertyDescriptor[] getPropertyDescriptors();
100
101 /**
102 * A bean may have a "default" property that is the property that will
103 * mostly commonly be initially chosen for update by human's who are
104 * customizing the bean.
105 * @return Index of default property in the PropertyDescriptor array
106 * returned by getPropertyDescriptors.
107 * <P> Returns -1 if there is no default property.
108 */
109 int getDefaultPropertyIndex();
110
111 /**
112 * Gets the beans <code>MethodDescriptor</code>s.
113 *
114 * @return An array of MethodDescriptors describing the externally
115 * visible methods supported by this bean. May return null if
116 * the information should be obtained by automatic analysis.
117 */
118 MethodDescriptor[] getMethodDescriptors();
119
120 /**
121 * This method allows a BeanInfo object to return an arbitrary collection
122 * of other BeanInfo objects that provide additional information on the
123 * current bean.
124 * <P>
125 * If there are conflicts or overlaps between the information provided
126 * by different BeanInfo objects, then the current BeanInfo takes precedence
127 * over the getAdditionalBeanInfo objects, and later elements in the array
128 * take precedence over earlier ones.
129 *
130 * @return an array of BeanInfo objects. May return null.
131 */
132 BeanInfo[] getAdditionalBeanInfo();
133
134 /**
135 * This method returns an image object that can be used to
136 * represent the bean in toolboxes, toolbars, etc. Icon images
137 * will typically be GIFs, but may in future include other formats.
138 * <p>
139 * Beans aren't required to provide icons and may return null from
140 * this method.
141 * <p>
142 * There are four possible flavors of icons (16x16 color,
143 * 32x32 color, 16x16 mono, 32x32 mono). If a bean choses to only
144 * support a single icon we recommend supporting 16x16 color.
145 * <p>
146 * We recommend that icons have a "transparent" background
147 * so they can be rendered onto an existing background.
148 *
149 * @param iconKind The kind of icon requested. This should be
150 * one of the constant values ICON_COLOR_16x16, ICON_COLOR_32x32,
151 * ICON_MONO_16x16, or ICON_MONO_32x32.
152 * @return An image object representing the requested icon. May
153 * return null if no suitable icon is available.
154 */
155 java.awt.Image getIcon(int iconKind);
156
157 /**
158 * Constant to indicate a 16 x 16 color icon.
159 */
160 final static int ICON_COLOR_16x16 = 1;
161
162 /**
163 * Constant to indicate a 32 x 32 color icon.
164 */
165 final static int ICON_COLOR_32x32 = 2;
166
167 /**
168 * Constant to indicate a 16 x 16 monochrome icon.
169 */
170 final static int ICON_MONO_16x16 = 3;
171
172 /**
173 * Constant to indicate a 32 x 32 monochrome icon.
174 */
175 final static int ICON_MONO_32x32 = 4;
176 }
Save This Page