The BeanBox allows you to:

• drop beans onto a composition window
• resize and move beans around
• edit the exported properties of a bean
• run a customizer to configure a bean
• connect a bean event source to an event handler method
• connect together bound properties on different beans
• save and restore sets of beans
• make applets from beans
• get an introspection report on a bean
• add new beans from JAR files

Note that the BeanBox is intended as a test container and as a reference base, but it is not intended as a serious application development tool.

It must be emphasized that the BeanBox is merely one rather simplistic way of representing beans to humans. We expect all bean-based tools to use the same standard JavaBeans APIs, but to provide very different ways of visually representing beans and different styles for manipulating and connecting beans.

Running the BeanBox

The BeanBox comes up as three separate windows.

• The middle window is the main beanbox composition window.

• The left-hand window is the ToolBox palette displaying available beans that can be dropped onto the composition window.

• The right-hand window is a PropertySheet showing the properties for the currently selected bean.

Dropping beans onto the composition window

To add a bean to the composition window:

• First click on the bean's name or icon in the left-hand ToolBox window.

• Then click on the location in the center composition window where you want the new bean to appear.

Selecting a bean in the composition window

The currently selected bean is marked with a black-and-white hashed boundary. The right-hand PropertySheet window shows its properties and the "edit" menu provides access to its events, bound properties, etc.

To select a bean you must click the mouse just outside of the bean in the boundary area where the black-and-white hashed boundary will appear.

Some beans (such as the ExplicitButton or the Juggler) will allow you to select the bean by clicking anywhere in the bean, but some other beans (such as the Molecule or the ChangeReporter) won't notice a click on the bean itself, and require you to click in the surrounding border area. This behaviour reflects problems with mouse event processing which we hope to fix for the final version of the BDK.

Moving or resizing a bean

Some beans, such as the BeanBox bean or the ExplicitButton, also allow themselves to be resized. You can try to resize the currently selected bean by clicking on one of the corners of the black-and-white boundary and holding the mouse down and stretching the corner out.

Editing a bean's properties

For each editable property the PropertySheet window shows the name of the property and its current value. The current value may be shown as:

• an editable text field
• or a selection in a choice menu
• or a painted value, where you can click on the painted value to bring up a small modal dialog for that property.

Using a bean Customizer

For those beans that have customizers, the BeanBox allows you to run the customizer to configure your bean.

If the currently selected bean has a customizer, then the "edit" menu on the central window will include a "Customize..." entry. If you select that entry, then a dialog window will come up with the bean's customizer.

Two of the example beans have a customizer. The ExplicitButton has a trivial customizer that simply lets you set the button's label. The JDBC SELECT bean has a much more interesting customizer that will try to connect through JDBC to a local database to help you create a SQL query.

Connecting an event handler

The BeanBox allows you to connect an event from the currently selected bean to a target event handling method on any other bean.

The "edit" menu on the central composition window has an "events" menu that has a sub-menu for all the different kinds of events that the currently selected bean fires. These events are grouped and named according to their EventListener interfaces. So for example, if you select an ExplicitButton bean you will see that it has two EventListener interfaces "button push" and "bound property change", each of which contain a single event.

If you select one of the events from this menu, the BeanBox will start drawing a "rubber band" line from the source bean. You can then click on the border of the target bean to which you want the event delivered. (Note that as for selection, you may need to click on the target bean's border rather than on the bean itself.)

The BeanBox will then check for methods in the target bean that accept the same EventObject argument that is fired by the source event. You will then be offered a dialog box to chose which matching method you would like to have called when the source event is fired. After you select a method, the BeanBox will generate, compile, and load an event adaptor class to connect the source bean's event to the target event handler method.

Try this out by connecting an ExplicitButton's button push event to a Juggler's) start method. Now when you push the button the Juggler will start juggling.

Note that this particular visual style for connecting up events isn't part of the beans architecture, nor is the associated search for a handler method with a particular method signature. Professional application development environments may do things like providing users with a handler method template and allowing the user to type in Java code for an event handler.

Connecting a bound property

The BeanBox allows you to connect a bound property from a source bean to a target property on some other bean. Then when the bound property on the source bean is changed, the associated target property is also automatically updated.

If the currently selected bean supports bound properties, then the "edit" menu will include a "Bind property..." item. If you chose this menu item, then the BeanBox will bring up a dialog showing the bound properties available on the source bean. You can then select a source property and press "OK". The beanbox will then draw a "rubber band" line. You can then click on the border of the target bean to which you want the property bound. (Note that as for selection, you may need to click on the target bean's border rather than on the bean itself.)

The BeanBox will then bring up a dialog listing the target properties on the target bean that match the the of the source property. You can select a target property and press "OK".

Now when you change the source property on the source bean then the target property on the target bean will also be updated.

Try this out by connecting up the background colors on two ExplicitButtons and then use the PropertySheet to change the background color of the source bean.

Saving and restoring beans

Once you have set up some beans in the BeanBox, you can use the "File" menu's "Save.." sub-menu to save away the current state of the BeanBox.

This uses Java Object Serialization to automagically store away all the state of the beans into a named file.

You can then use the "File" menu's "Clear" item to discard the current set of beans and use the "Load..." item to read in and recreate all the serialized beans.

This provides a simple way to test the use of serialization with your beans.

Making applets from beans

You can also set up some beans in the BeanBox and then use "File" menu's "MakeApplet" item to create an Applet that behaves like this set of beans. The resulting Applet uses Java Object Serialization to record the state of any beans effectively containing hidden-state, otherwise, it calls Beans.instantiate() to create a new bean. Only bean properties that have changed during the BeanBox session in which the applet was generated are restored.

Invoking the MakeApplet item will create a JAR file that contains the serialized data (if any) plus hookup and other classes. The action will also create a test HTML file that uses that JAR file (plus any other JAR files containing the buttons used in the Applet), a subdirectory with Java source files plus makefiles, and a "readme" file with more details.

The generated applet can be used in any fully compliant JDK1.1 browser. A simple test platform is the appletviewer from the JDK1.1 distributions. Another fully compliant browser is the HotJava Browser.

The preview2 release of Internet Explorer 4.0 has a couple of problems:

• JAR files are not yet working; you will need to expand the JAR files and modify the generated HTML files. There are more explicit directions in the generated readme file.
• There is a problem with deserialization which causes deserialized components not to listen to mouse events.

The generated applet will not work in the 4.0 and 4.01 versions of Netscape Communicator.

Getting an introspection report on a bean

If you want to see all the properties, methods, and events that the Beans introspector has found on a selected bean, you can use the BeanBox's "report" menu item under the "edit" menu.

This generates a summary report to the standard output of the introspection information for the selected bean.

Adding your bean to the BeanBox

When the BeanBox starts it loads all the JAR files that it finds in the "jars" directory. The BeanBox uses the manifest file in each JAR file to identify any bean classes in the JAR file, and adds those beans to the ToolBox palette in the BeanBox.

To add your bean to the BeanBox, you must wrap it up in a JAR file which contains a suitable manifest file describing the bean. Take a look at one of the example bean makefiles such as demo\juggler.mk (for Windows nmake users) or demo/juggler.gmk (for Unix gnumake users) to see how to create a manifest file and a JAR file.

Once you have a suitable JAR file, simply add it to the "jars" directory and restart the BeanBox, or load the JAR directly using the "LoadJar..." item in the "File" menu.