- * A bean implementor doesn't need to provide a complete set of - * explicit information. You can pick and choose which information - * you want to provide and the rest will be obtained by automatic - * analysis using low-level reflection of the bean classes' methods - * and applying standard design patterns. + * Use the {@code BeanInfo} interface + * to create a {@code BeanInfo} class + * and provide explicit information about the methods, + * properties, events, and other features of your beans. *
- * You get the opportunity to provide lots and lots of different - * information as part of the various XyZDescriptor classes. But - * don't panic, you only really need to provide the minimal core - * information required by the various constructors. - *
- * See also the SimpleBeanInfo class which provides a convenient - * "noop" base class for BeanInfo classes, which you can override - * for those specific places where you want to return explicit info. - *
- * To learn about all the behaviour of a bean see the Introspector class. + * When developing your bean, you can implement + * the bean features required for your application task + * omitting the rest of the {@code BeanInfo} features. + * They will be obtained through the automatic analysis + * by using the low-level reflection of the bean methods + * and applying standard design patterns. + * You have an opportunity to provide additional bean information + * through various descriptor classes. + *
+ * See the {@link SimpleBeanInfo} class that is + * a convenient basic class for {@code BeanInfo} classes. + * You can override the methods and properties of + * the {@code SimpleBeanInfo} class to define specific information. + *
+ * See also the {@link Introspector} class to learn more about bean behavior.
*/
-
public interface BeanInfo {
/**
- * Gets the beans BeanDescriptor.
+ * Returns the bean descriptor
+ * that provides overall information about the bean,
+ * such as its display name or its customizer.
*
- * @return A BeanDescriptor providing overall information about
- * the bean, such as its displayName, its customizer, etc. May
- * return null if the information should be obtained by automatic
- * analysis.
+ * @return a {@link BeanDescriptor} object,
+ * or {@code null} if the information is to
+ * be obtained through the automatic analysis
*/
BeanDescriptor getBeanDescriptor();
/**
- * Gets the beans EventSetDescriptors.
+ * Returns the event descriptors of the bean
+ * that define the types of events fired by this bean.
*
- * @return An array of EventSetDescriptors describing the kinds of
- * events fired by this bean. May return null if the information
- * should be obtained by automatic analysis.
+ * @return an array of {@link EventSetDescriptor} objects,
+ * or {@code null} if the information is to
+ * be obtained through the automatic analysis
*/
EventSetDescriptor[] getEventSetDescriptors();
/**
- * A bean may have a "default" event that is the event that will
- * mostly commonly be used by humans when using the bean.
- * @return Index of default event in the EventSetDescriptor array
- * returned by getEventSetDescriptors.
- *
Returns -1 if there is no default event. + * A bean may have a default event typically applied when this bean is used. + * + * @return index of the default event in the {@code EventSetDescriptor} array + * returned by the {@code getEventSetDescriptors} method, + * or -1 if there is no default event */ int getDefaultEventIndex(); /** * Returns descriptors for all properties of the bean. - * May return {@code null} if the information - * should be obtained by automatic analysis. *
* If a property is indexed, then its entry in the result array - * will belong to the {@link IndexedPropertyDescriptor} subclass + * belongs to the {@link IndexedPropertyDescriptor} subclass * of the {@link PropertyDescriptor} class. * A client of the {@code getPropertyDescriptors} method - * can use "{@code instanceof}" to check + * can use the {@code instanceof} operator to check * whether a given {@code PropertyDescriptor} * is an {@code IndexedPropertyDescriptor}. * - * @return an array of {@code PropertyDescriptor}s - * describing all properties supported by the bean - * or {@code null} + * @return an array of {@code PropertyDescriptor} objects, + * or {@code null} if the information is to + * be obtained through the automatic analysis */ PropertyDescriptor[] getPropertyDescriptors(); /** - * A bean may have a "default" property that is the property that will - * mostly commonly be initially chosen for update by human's who are - * customizing the bean. - * @return Index of default property in the PropertyDescriptor array - * returned by getPropertyDescriptors. - *
Returns -1 if there is no default property.
+ * A bean may have a default property commonly updated when this bean is customized.
+ *
+ * @return index of the default property in the {@code PropertyDescriptor} array
+ * returned by the {@code getPropertyDescriptors} method,
+ * or -1 if there is no default property
*/
int getDefaultPropertyIndex();
/**
- * Gets the beans MethodDescriptors.
+ * Returns the method descriptors of the bean
+ * that define the externally visible methods supported by this bean.
*
- * @return An array of MethodDescriptors describing the externally
- * visible methods supported by this bean. May return null if
- * the information should be obtained by automatic analysis.
+ * @return an array of {@link MethodDescriptor} objects,
+ * or {@code null} if the information is to
+ * be obtained through the automatic analysis
*/
MethodDescriptor[] getMethodDescriptors();
/**
- * This method allows a BeanInfo object to return an arbitrary collection
- * of other BeanInfo objects that provide additional information on the
- * current bean.
- *
- * If there are conflicts or overlaps between the information provided - * by different BeanInfo objects, then the current BeanInfo takes precedence - * over the getAdditionalBeanInfo objects, and later elements in the array - * take precedence over earlier ones. + * This method enables the current {@code BeanInfo} object + * to return an arbitrary collection of other {@code BeanInfo} objects + * that provide additional information about the current bean. + *
+ * If there are conflicts or overlaps between the information + * provided by different {@code BeanInfo} objects, + * the current {@code BeanInfo} object takes priority + * over the additional {@code BeanInfo} objects. + * Array elements with higher indices take priority + * over the elements with lower indices. * - * @return an array of BeanInfo objects. May return null. + * @return an array of {@code BeanInfo} objects, + * or {@code null} if there are no additional {@code BeanInfo} objects */ BeanInfo[] getAdditionalBeanInfo(); /** - * This method returns an image object that can be used to - * represent the bean in toolboxes, toolbars, etc. Icon images - * will typically be GIFs, but may in future include other formats. - *
- * Beans aren't required to provide icons and may return null from - * this method. - *
- * There are four possible flavors of icons (16x16 color, - * 32x32 color, 16x16 mono, 32x32 mono). If a bean choses to only - * support a single icon we recommend supporting 16x16 color. + * Returns an image that can be used to represent the bean in toolboxes or toolbars. *
- * We recommend that icons have a "transparent" background - * so they can be rendered onto an existing background. + * There are four possible types of icons: + * 16 x 16 color, 32 x 32 color, 16 x 16 mono, and 32 x 32 mono. + * If you implement a bean so that it supports a single icon, + * it is recommended to use 16 x 16 color. + * Another recommendation is to set a transparent background for the icons. * - * @param iconKind The kind of icon requested. This should be - * one of the constant values ICON_COLOR_16x16, ICON_COLOR_32x32, - * ICON_MONO_16x16, or ICON_MONO_32x32. - * @return An image object representing the requested icon. May - * return null if no suitable icon is available. + * @param iconKind the kind of icon requested + * @return an image object representing the requested icon, + * or {@code null} if no suitable icon is available + * + * @see #ICON_COLOR_16x16 + * @see #ICON_COLOR_32x32 + * @see #ICON_MONO_16x16 + * @see #ICON_MONO_32x32 */ - java.awt.Image getIcon(int iconKind); + Image getIcon(int iconKind); /** * Constant to indicate a 16 x 16 color icon.