Quick Start on Groups and Shadows

The groups and shadows framework provides a component mechanism that allows the Java WorkShop GUI builder to import and manipulate components.

Shadows

A shadow class is a wrapper around an AWT component or bean. The wrapped object is called the body, and you access it by using the getBody() method. The shadow provides an API for accessing the attributes of the body using the get and set methods. The body's methods are also available and can be used directly instead of the shadow's accessors.

Getting the Component Body From the Shadow

In the Group and Ops files there is a variable gui that is an instance of the application's Root class, which is the root of the hierarchy of shadow instances for the application's graphical user interface. When you set the name of the component using the attribute editor, that name is available as a data member of the Root class, and contains the shadow instance rather than the component itself. To get the AWT component or bean that the shadow is wrapping, use the getBody method, and cast it to the appropriate class.

Groups

Groups provide a mechanism for creating interchangeable components that can be plugged together using GUI builder or by programmatic means.

Customizing Application Startup

The file you edit to add your own code is the Group file (project.java). The Main file contains the entry pint methods for the application or applet. You cannot edit the Main file; if you need to customize some of the startup behavior of your application, there are hooks provided in the group class to do so.

There are several methods in the Group file that are called during the startup sequence. Overriding these methods allows you to have code executed at the appropriate time.

initGroup Called after the shadow tree is created. At this point all the shadows are available, but the AWT component bodies and beans have not been created yet. You can get and set properties on the shadows using the get and set methods.

This method is called only once during the lifetime of a group. Usually, you do not need to put any code in this method.

createGroup Called when the group's AWT component bodies are created which happens the first time the group is made visible or when the group's create method is called explicitly.

This method should contain any code that is needed when the AWT components or bean bodies are initialized.

destroyGroup Called when the group is destroyed and the AWT component hierarchy is destroyed. The shadow hierarchy is not destroyed.

This method should contain code that cleans up data structures created in the createGroup method.

showGroup
hideGroup
Called when the group is made visible or invisible.

These methods should contain code that is related to groups becoming visible or invisible.

The generated Group file has comments that explain each of these methods in more detail.

Overview of the Generated Files

Currently, GUI builder generates four files that are compiled into the application:

Events

Java WorkShop supports both JDK 1.0 and JDK 1.1 style events. You can mix both types in your application. However, you can use only one style for a given component. Specifically, if you add event listeners to a component, the JDK 1.0 style events no longer propagate.

Filters

GUI builder provides a mechanism for filtering JDK 1.0 style events on AWT components using the Filters dialog box. This dialog box allows you to specify which events an operation responds to.

Actions

The Actions dialog box supports several action types. The Show, Hide, Set Property, and Exit actions perform simple operations without your having to write any code. The Execute Code actions allow you to customize the operation by writing a small amount of code.

The Actions dialog box shows a text field in which you write code fragments. This code is generated into the Ops file. There are two variables, group and gui, available in the scope of this code fragment. A simple way to use this mechanism is to declare a public method in the group class and call it in the code fragment.

For example, you can put a method in your group class:

 public void doSomething() {
   // do something
 }
and then call it from the dialog box:
 group.doSomething();

See also:

Tips on Using Beans and Shadows
What Is a Component Operation?
What Are Groups and Shadows?
More On Groups and Shadows