Operations (Filters and Actions)

The term "operation" refers to specialized callbacks that you can define using the Visual Java operations editor. Callbacks are typically implemented by adding custom code to the Group file. However, for simple callbacks, it is often more convenient to use a Visual Java operation than to add custom code to the group class. In many cases a Visual Java operation can automate all of the code generation for a callback. You may find that you can use the operations editor for all or most of your callbacks.

An operation consists of two parts: a filter and an action. The filter is "when," and the action is "what." For example, consider an operation that shows a window when the user clicks a button. In this case, the operation is defined for the button, with an event filter of "Action Event," and an action of "Show Window."

Operations must be associated with a specific component. Operations defined for a given component can be triggered only by events and messages that originate from the component itself. More than one operation can be defined for each component. Operations are ordered, so that if two operations match the same event, the operation closer to the beginning of the list is invoked first.

Editing Operations Using the Operations Editor

The operations editor is available for all components and is accessed by clicking on the Edit operations button in the Attribute Editor.

The operations editor has Insert and Delete buttons:

If you accidentally delete operations, you can click Reset to reset the list to its state after the last Apply operation. Note that there is no undo operation, so you cannot undo changes you have applied.

Each time you click Insert, an operation is added to the list. Visual Java automatically assigns a unique name for each operation you create. You can edit that name in the Op Name field. Note that operation names must be unique within a group.

To create an operation:

  1. Select a component in the layout window.
  2. Open the attributes editor. (click on )
  3. Click the Edit operations button.
  4. Click Insert to create the operation.
  5. Click on the Filter button to activate the Filter editor dialog box. This allows you to modify the filter associated with the operations. Filters are described in Filters.
  6. Click on the Action button to modify the operation's action. Actions are described in Actions.

As you add most filters and actions you can test them "live" in the layout window. Custom actions added in the Action dialog box are available only when running the application and are not available live in the layout panel.

Filters

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

Event Filter

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

There are four aspects to an event filter:

The only required element is the id. The id determines the type of event for the filter. The key, modifiers, 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 Down" event id can be further narrowed by specifying a key filter of "C." This can be narrowed even further by specifying the modifier "Control." This filter will be triggered when the operation's component has the keyboard focus and the user presses Control-C.

Available modifiers depend on the event id. For key events, the modifiers are:

For mouse events, the modifiers are:

The click count element is important only for mouse events. To catch a double-click, the event id is "Mouse Down" and the click count is 2.

Message Filter

With this version of Visual Java, messages are not automatically generated, 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:

Each of these parts is a string that is matched against any messages that are received. The message name must be specified, but the type and target name can be left blank. The type and target name are additional filters within the scope of the message name.

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

Actions

The action part of the operation determines what happens when there is a matching event. Visual Java specifically supports some common actions such as showing and hiding a component, exiting the application, and setting an attribute on a component. You can also specify custom code that will be executed when the action is invoked.

Common actions and custom code actions are not treated quite the same. 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, not while you are building the application. Future versions of Visual Java may support live code actions while building the application.


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

Action Types

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

Show, Hide

After you choose one of these actions from the menu, you must choose a target for the action from the Target display 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

After you choose Set Attribute from the menu, you must:
  1. Choose 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 choice menu

    If you choose the Constant from the menu, you can statically set the value using the provided editors, text fields, and so on.

    If you choose Event Arg from the menu, the event arg 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. 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 in this way will cause the checkbox to toggle the component between the enabled and disabled states.

Execute Code

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

The code you enter in the Execute Code area is saved in the .gui file, and later generated into the <ProjectName>Ops.java file.

Special Variables

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

For a group named MyProg:

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 enter:
  import java.net.*;
  URL url = new URL(gui.urlTF.get("text"));
  URLConnection connection = url.openConnection();

The following code is generated into the <ProjectName>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, enter:
  String string_selected=((List) listShadow.getBody()).getSelectedItem();
In general, it is better to use the shadow class for the get() and set() methods rather than getBody() 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), enter:
 Applet ap = getApplet();
 String param = ap.getParameter("blinkrate");


See also:

Visual Java Overview
The Visual Menu
Visual Java Components
Laying Out GUI Interfaces
Generating Java Source Code
Visual Java Runtime Classes
Creating Menus
Adding Custom Components and Windows
Using Groups and Shadows (Basic)
Using Groups and Shadows (Advanced)
Visual Java API Documentation
Visual Java Runtime Packages
Class Hierarchy
Index of all Fields and Methods