# 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:

- project`Root.java` (the Root file) contains the code that creates the component tree, sets properties and layout information.
- project`Ops.java` (the Ops file) contains the operations and event handler code.
- project`Main.java` (the Main file) contains the application (or applet) subclass and the `main()` routine for calling the application in a standalone mode.
- project`.java` (the Group file) glues it all together, and is where the GUI programmer puts custom initialization code and other methods needed by 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