# What Is a Component Operation?

When you add a behavior to a component, you are defining an operation for it. The term "operation" refers to specialized callbacks that you can define using the GUI builder Operations dialog box. Callbacks are typically implemented by adding custom code to the Group file (project`.java`).

This section covers:

- Operations
- Filters
- Actions

For instructions on adding a specific behavior to a component, see Adding Operations to Components.

## Operations

Operations can be implemented by adding custom code to the Ops file through the Operations dialog box. However, code added to the Ops file should be kept to a minimum as that code can be overwritten when the file is regenerated. A better method is to add minimal lines of code to the Ops file (for example, a single line that calls an operation) and add the main body of code to the Group file (the project`.java` file).

In many cases, you can go through the Operations dialog box to use predefined GUI builder operations, which might automate all of the code generation. Another way to add operations is to edit the group file directly through the source editor.

An operation consists of two parts:

- A filter that defines when an action happens (the cause)
- An action that defines what the action is (the effect)

For example, consider an operation that shows a window when the user clicks a button. The operation is defined for the button with a filter of Action Event (the button is pressed) and an action of Show Window.

You must associate operations with a specific component. An operation is usually triggered by events and messages that originate from its associated component. More than one operation can be defined for each component. If two operations match the same event, the operation that is closer to the beginning of the list is called first.

## Filters

There are two different types of filters: event filters and message filters. An event filter is triggered by AWT events, and a message filter is triggered by messages from other groups. The target for these messages must match the component or group for which the operation is being defined.

For information on new-style and old-style event handling, see the JDK documentation, "Java AWT: Delegation Event Model." (You may have to reset the proxies on the Java Workshop help browser if you have difficulties reaching the Delegation Event Model.)

For a demonstration of how to use the new style 1.1 events, see

On Solaris:
install-dir-path`/examples/JellyBeanExample`

On Microsoft Windows 95 and Windows NT:
install-dir-path`\examples\JellyBeanExample`

### Event Filter

There are many event filters that can be defined for an action. Some examples are Mouse Down, Key Press, and Action Event. An event filter is used to select particular types of AWT events for which an action should be called (see the JDK documentation of the AWT Event class for more details).

An event filter has four parameters:

- Id
- Key
- Modifier
- Click Count

The only required element is the Id. The Event Id determines the type of event for the filter. The Key, Modifier, and Click Count fields are used to further narrow the scope of the filter for a given Event Id.

For example, the set of events selected by the Key Press Event Id can be further narrowed by specifying the key, `C`. The event filter can be narrowed even further by specifying the modifier `Control`. The event filter, Key Press, will be triggered when the operation's component is selected and the user presses `Control-C`.

The types of modifiers available depend on the Event Id. For key events, the modifiers are:

- Shift
- Control
- Meta
- Alt

For mouse events, the modifiers are:

- Left Mouse
- Middle Mouse
- Right Mouse

The Click Count is important only for mouse events. To catch a double-click, the Event Id is Mouse Down, the Modifier is Left Mouse, and the Click Count is 2.

### Message Filter

Currently, GUI builder, does not automatically generate messages. You must write the code that generates a message. You can use the Operations dialog box to specify incoming messages and the actions that they trigger when they are received.

A message filter has three parts:

- Name
- Type
- Target Name

Each of these parts is a string that is matched against any messages that are received. You must specify the message Name, but the Type and Target Name fields can be left blank. The Type and Target Name are additional filters within the scope of the message name. Note that the target object is always searched for and must match the Target Name if a Target Name is supplied.

The component for which the operation is defined must be the target of the message (if the target is defined), or the filter will not be triggered. For example, you might have a custom subgroup that sends out "Apply" messages. To trigger off of the "Apply" message, you should select the group and then edit its `operations` attribute. Then define an operation that has a message filter with the name "Apply." Optionally, you can define the target to be the group.

## Actions

An operation's action determines what happens when there is a matching event. GUI builder specifically supports some common actions, such as showing and hiding a component, exiting the application, and setting an attribute on a component. You can specify custom code that is called when the action is triggered.

Common actions and custom code actions are not treated in quite the same way. Common actions are live both while the application is running and while you are building the application. Custom code actions are live only while the program is running. Future versions of GUI builder may support live code actions while building the application.

The exit action is not live while building the application because it would cause GUI builder to exit and unsaved changes would be lost.

### Action Types

Choose one of the following action types from the Action Type menu:

- Show
- Hide
- Exit
- Set Attribute
- Execute Code

#### Show, Hide

After you choose one of these actions from the menu, you must select a target for the action from the Target pane. The target is the component that will be shown or hidden when the action is invoked.

#### Exit

There is no target for the exit action.

#### Set Attribute

If you choose Set Attribute, you must:

1. Select a component from the Target pane and an attribute of that component from the Name pane.
2. Choose either Constant or Event Arg from the Value Source menu.

   If you choose Constant, you can statically set the value using the provided windows, text boxes, and so on.

   If you choose Event Arg, the event argument must be the same type as the attribute that you have selected. For example, checkboxes have Boolean event arguments. The `enabled` attribute defined for components is also a Boolean value. Therefore, you can legally choose the Event Arg option for the checkbox as long as you select the `enabled` attribute for the target component. Defining an action this way causes the checkbox to toggle the component between the enabled and disabled states.

#### Execute Code

If you choose Execute Code from the Action Type menu, a text box is available for you to enter code. You can enter custom operations that are automatically included in your application.

The code you enter in the Execute Code box is saved in the `.gui` file, and is later generated into the project-name`Ops.java` file.

The preferred method is to write custom code as individual handlers in the group file (the project`.java` file). Then invoke the handler from the Execute Code box. For example, in the Execute Code box you call:

    group.myActionHandler();

In the group file, you define the operation:

    public void myActionHandler(){
           ...
    }

#### Special Variables

There are several important variables that are available within the scope of the custom code segment.

For a group named `MyProg`:

- `MyProg group;`
  Group variable. The group is guaranteed to be initialized when the action is invoked.

- `MyProgRoot gui;`
  Root variable. The root will be non-null when the action is invoked.

- `Message msg;`
  The message that triggered the action. The message will always be non-null.

- `Event evt;`
  AWT event that triggered the action. This will be null only if the triggering message is not an AWT event. This can happen if the operation is using a message filter instead of an event filter.

  For more information on message handling and AWT events, see Message Handling (Operations).

The following is a code segment that shows the window `frame1` when a button is clicked:

      gui.frame1.set("visible", Boolean.TRUE);

The following is a code segment that shows or hides the window `frame1` depending on the state of a checkbox:

      gui.frame1.set("visible", evt.arg);

#### Import Statements

You can add import statements at the top of your custom code. The code generator will place them in the correct location in the generated sources. For example, if you type:

      import java.net.*;
      URL url = new URL(gui.urlTF.get("text"));
      URLConnection connection = url.openConnection();

the following code is generated into the project-name`Ops.java` file. Note the position of the import statement.

      import java.io.net.*;
      private void handleCallback(int index, Message msg, Event evt) {
        switch (index) {
        case 1:
          {
    group.exit();
          }
          break;
        case 2:
          {
    URL url = new URL(gui.urlTF.get("text"));
    URLConnection connection = url.openConnection();
          }
         }
      }

#### Accessing AWT Methods for Shadows Classes

The `getBody()` call allows you to access methods of the classes on which shadow classes are based. For example, if you want to determine which item is selected in a `ListShadow` object, type:

      String string_selected=((List) listShadow.getBody()).getSelectedItem();

To access the methods, you must cast the result of the `getBody` call.

You can use either the shadow class for the `get()` and `set()` methods or the `getBody()` method, which accesses the AWT component directly. The shadow class methods utilize workarounds and optimizations. For example:

    String string_selected=listShadow.get("selectedItem");

#### Accessing the Applet

The `group` class provides a method for accessing the applet. For example, if in your operation you need to access a parameter supplied to the applet (in this case the blink rate), type:

     Applet ap = getApplet();
     String param = ap.getParameter("blinkrate");

See also:

  Adding Operations to Components
  Generating Java Source Code
  GUI Builder Runtime Classes
  What Are Groups and Shadows?
  Using>More On Groups and Shadows

  Visual Java GUI Builder API Documentation
    Visual Java GUI Builder Runtime Packages
    Class Hierarchy
    Index of All Fields and Methods