JavaBeans components comply with the JavaBeans specification (at http://splash.javasoft.com/beans/), which contains the design goals, rules, and naming standards for a JavaBeans component. Any discussion of components in JBuilder refers to JavaBeans components. A JavaBean or simply a bean is a JavaBeans component.
Components are the building blocks of JBuilder applications. Although many components represent visible parts of a user interface, components can also represent nonvisual elements in a program, such as timers and databases.
There are three ways to view components:
Before you attempt to write components, we strongly recommend that you become familiar with the existing components in JBuilder. If you adopt the model-view architecture used by the JBCL components, you'll be using a flexible and powerful style of component writing.
Defining the limits of component writing is much like defining the limits of programming. We can't tell you every kind of component you can create, any more than we can tell you all the programs you can write. What we can do is tell you how to write your code so that it fits well in the JBuilder environment and so you can use them in other visual tools that support the JavaBeans standard.
These component categories are discussed in greater detail below.
UI components must always extend some class that is capable of drawing to the screen. Ultimately, they all descend from java.awt.Component. Usually you should extend an existing component to be certain that you implement all the methods that the JavaBeans model requires.
Non-UI components, in contrast, can extend any appropriate class. They must simply obey the basic rules for components: they have a public parameterless constructor and properly named and constructed accessor methods for properties and events they surface at design time.
Non-UI components provide encapsulated functionality to the user interface, generally by interacting with UI components. They have no ability to paint anything to the screen. At design time, non-UI components appear in the Component Tree, rather than in the UI Designer. Users select the non-UI component in the Component Tree to manipulate the component's properties and events.
The Database component is an example of a non-UI component. It becomes a part of an application, but is never visible to the user of the application. The Database component, like all non-UI components, never draws anything on the screen.
When you work with a non-UI component, you can drop them on the UI Designer or the Component Tree, but they appear the Component Tree only, not on the UI Designer.
The purpose of the model-view architecture is to separate the representation of data from the model itself and allow for multiple views of the same data. Components that instantiate these model-view classes to perform their work are often referred to as composite components. Most of JBuilder's controls are composite components.
Some of JBuilder's standard components have the term "control" as a part of their names (for example, TreeControl in borland.jbcl.control). These composite components are so named to distinguish them from the model-view classes that have similar names. In most cases, the class with "control" in its name is the complete component that can be used to design visually, and which has been developed from the view component of the same name. The "view" is the corresponding view class of the control, and it is used for developing original composite components. For example, the TreeControl is based on the TreeView class.
See also:
Overview of component writing
Understanding model-view architecture
The JavaBeans component model is a specification for how to code components. Components that comply with this specification work in JBuilder's visual environment. JBuilder parses the component code and makes its properties and events available in the Component Inspector. The complete component model specification is available in the JavaBeans specification at http://splash.javasoft.com/beans/.
The following are the most significant requirements for components:
public FtpRequestDialog();
Property accessor methods must have a specific signature. The read method must take no parameters and return an object of the type identical to the property type. For boolean properties the read method begins with the word "is"; for all other properties the read method begins with the word "get".
The write (or set) method must take a single parameter identical to the property type and return void. For example, the component property background (which contains the state of the component's background color) would have accessor methods with the following signatures:
public Color getBackground(); public void setBackground(Color color);Properties can have multiple write accessor methods, but they must have one with the signature shown here. Any overloaded methods are simply component methods for programmatic access to the property. They do not appear in the Inspector.
For details of property specification, see Creating properties.
public void add<event>Listener(<event>Listener <listener>) throws TooMayListeners;The add listener method for multicast events is the same, except that it does not throw the TooManyListenersException:
public void add<event>Listener (<event>Listener <listener>);Both unicast and multicast use the same form of the remove listener method:
public void remove<event>Listener(<event>Listener <listener>);
For example, the following is a declaration for an addSelectionListener() method:
public void addSelectionListener(VectorSelectionListener listener)When a container calls addSelectionListener(), the container is registered with the source component that defines the method as a listener of vector-model selection events.
Events and event registration methods are explained in more depth in Working with events. In addition to these requirements, the JavaBeans specification at http://splash.javasoft.com/beans/ provides guidelines to help you to write well-designed components that interact well with other Java components.
Using properties in components has a number of advantages:
Properties take advantage of the full power of JBuilder's UI Designer. The component user can change the state of a component (by setting a property value) and immediately see the effects of that change on the program. By default, all of a component's public properties are available to other components, but you can control design-time access to component properties by using the optional BeanInfo interface to specify which properties should be exposed.
You can include complex functionality in a property's accessor methods. The component user need never know about that functionality, but simply make the setProperty() or getProperty() method call. A property that looks like a simple number can actually be a complex calculation or a lookup in a database. Your component users don't have to deal with that complexity.
You can have the accessor method notify other objects or call other methods whenever a property is set or read. The accessor method can encapsulate all kinds of complex behavior for a component; all the component user needs to know is how to make a method call.
public class MyComponent extends BevelPanel { private int redValue; private int greenValue; private int blueValue; public int getShadowColor() { return redValue | greenValue | blueValue; } public void setShadowColor(int color) { redValue = color & 0xff0000; // class data members greenValue = color & 0x00FF00; blueValue = color & 0x0000FF; } }Although MyComponent has no actual class data member named shadowColor, the property is correctly defined because of the two accessor methods, getShadowColor() and setShadowColor(). These methods write and read three variables and calculate a value for the property. Although it's common for a component property to set a variable with the same name as the property itself, it is not required. The component property must merely have correctly declared property accessor methods for the property to be valid.
Creating properties explains how to add properties to your components.
There are few restrictions on what component methods can do, but you should make every effort to ensure that your methods are as intuitive as possible. Name your methods so that the purpose of the method is obvious. Avoid preconditions on method use. If you must have preconditions on a method call, build in tests to validate that conditions are met and provide exception handling for situations where a method call is inappropriate.
Take care in the naming of methods to make your components easier to use. Choose the shortest descriptive name. Avoid abbreviating method names. Remember, too, that methods are actions. If you find yourself creating many methods that have no verbs in their names, consider creating properties instead. Do not include the data type of arguments in the method name. Instead name methods and arguments so that the method signature provides a complete but non-redundant description of the action. For example, void paste(Image) tells you everything you need to use this paste() method. By contrast, void pasteImage(Image) is redundant and visually confusing.
If a component's code complies with the JavaBeans rules, JBuilder recognizes the component's events and displays them in the Component Inspector.
Event source components have registration methods, which are similar in naming patterns to the accessor methods of properties. Working with events explains how to add standard event sets or event sets you define yourself.
Standard Java events are grouped on listener interfaces (and, in some cases, on source interfaces). These are the standard event sets and their events:
See also:
Understanding model-view architecture
As you add components to the container, JBuilder creates constraints objects to manage their layout constraints, based upon the layout manager of the container.
For details on how to work with layout managers, see Using layout managers.
There are four types of models in JBCL:
The model package also contains two view manager interfaces and classes.
See also:
Understanding model-view architecture
The view package also contains several item painters and item editors. Some of these are used by JBCL controls and others are provided for your convenience. Some of the item painters and editors are wrappers. For example, if you want to display and image and a string for each data item in the model, you could use a CompositeItemPainter, which is constructed with one ImageItemPainter and one TextItemPainter.