Interaction Wizard Editor

Overview

The purpose of the Interaction Wizard Editor is to edit the way a component's methods and events will appear in the Interaction Wizard. Using the Interaction Wizard Editor, you can specify which events and methods will be seen and how they will be described. (For more information about creating new events and methods for a component, see the Component Writers Guide.)

To open the Interaction Wizard Editor, do one of the following:


Step 1 of 3

The first page of the Interaction Wizard Editor is where you select the component class you want to edit for how it displays in the Interaction Wizard. If you have already selected a component in the Component Tree, its class will be proposed in the Component class to edit field. Otherwise, you need to either select a component from the list box, or enter the fully qualified class name of the component you want to edit.

For example, if you wanted to edit the ChartWrapper component, you would type in the following:

borland.jbcl.appletwrappers.barchart.ChartWrapper.


Step 2 of 3

Step 2 of the Interaction Wizard Editor allows you to specify which of the event sets generated by this component will be visible in the Interaction Wizard UI. What the Interaction Wizard Editor does is to use introspection on the component to find all of the "addXxxListener" methods it exposes. For each of those, it determines the set of events which can be generated by the component (based on the event methods of the "XxxListener" interface that is the parameter of the addXxxListener() method). An "event set" is the collection of events associated with the particular addXxxListener() method and its associated interface, and the individual "events" are the methods on that interface.

For example, for the ChartWrapper component, the Interaction Wizard Editor would find six different event sets, because ChartWrapper, or its superclasses, expose those six addXxxxListener() methods.

Selecting the events to expose

Click on the name of an event set to see the specific event interface involved. For example, for the ChartWrapper component, if you select FOCUS_EVENTS, the Interaction Wizard Editor displays the interface name java.awt.FocusListener. You can also click the arrow to the left of the event set name to expand the event set so you can see the specific event(s) available in this event set.

To make all of the events of an event set visible in the Interaction Wizard, check This event set exposed to interactions:. This checkbox toggles the state of the event set between being visible or not visible in the Interaction Wizard. When a green dot appears beside an event set name, its event methods are visible in the Interaction Wizard.

Changing the presentation order of the event sets

To change the order in which the event sets generated by this component will be presented in the Interaction Wizard, select the event set you want to move, and click the Move Up or Move Down button.

Changing the event set name and the event description

The Interaction Wizard has a knowledge base (jbuilder\bin\interactions.ini) that already knows about some general purpose event sets, and also suggests a "user friendly" description for each event within the event set. Below is the section of the interactions.ini file that describes the FOCUS_EVENTS set:

adapter FOCUS_EVENTS java.awt.event.FocusListener {  
   "Got focus" focusGained(FocusEvent)  
   "Lost focus" focusLost(FocusEvent)  
}

In the example shown here of FOCUS_EVENT, the associated event interface is java.awt.event.FocusListener. It has two events that can be generated, with proposed descriptions of "Got focus" and "Lost focus".

You can modify the name of the event set, as it will be seen in this editor, and the descriptions of the individual events, as they will be seen in this editor and in the Interaction Wizard.

To change the name of an event set, click on it, type the new name in the Description box, and click the Change button. For example, for the ChartWrapper component, click on the event set FOCUS_EVENT, and then type a new event set name (such as CHART_FOCUS_EVENTS) in the Description field, and then click Change. The screen in this example would now look like this:

To change the description for a particular event within the event set, select the event, enter a new description in the Description text field, then click the Change button. For example, on the ChartWrapper, select the "Got focus" event, and in the Description text field, enter "The chart got focus" and click Change. The screen in this example would now look like this:

Note that the checkbox labeled This event set exposed to interactions: is disabled when the selected item is an event. This is because you can only expose or hide a whole event set, not the individual events.

If you had changed the event wording without changing the event set, then this change would have been propagated to all components using that same event set.

With the two changes in the above example, Interaction Wizard Editor would generate a new event set in interactions.ini that would look like this:

adapter CHART_FOCUS_EVENTS java.awt.event.FocusListener {  
    "The Chart Got focus" focusGained(FocusEvent)
    "Lost Focus" focusLost(FocusEvent)  
}
 


Step 3 of 3

Specifying the actions that can be performed

Step 3 of the Interaction Wizard Editor is where you specify the actions that can be performed on the component.

The Interaction Wizard Editor uses introspection on the component to obtain a list of its public methods. It then presents the list to you, so you can selectively choose which methods to make visible in the Interaction Wizard, and which methods to hide. Those methods are listed by declaring classes.

To expose some methods specific to a class, such as the borland.jbcl.appletwrappers.barchart.ChartWrapperclass, click on the class name and the screen below should appear:

Click on the arrow by the class name to see its public methods.

As the selected method is promoted to being exposed, it is automatically moved on top of the tree, just below "Actions". This allows you to quickly spot, and work on, exposed methods. Note that if from this point you chose to NOT expose the method, it won't go back to where it was. This allows you to easily toggle from exposed to not exposed without losing the method.

Modifying the selected method

Description:

The Description text field shows the corresponding "user friendly" description. The default description is the method name. You can replace this description by typing in the Description field, and then clicking the Change button.

Expression:

The Expression text field shows the expression which will, by default, be offered to the user of the Interaction Wizard for the value of this parameter. This could be a simple string value, for example for a string parameter, or, for a parameter that takes an object, this could be a code fragment that is an expression, a variable, or even a constructor invocation (for example, new ClassName()). Whatever you put here will be proposed to the user of the Interaction Wizard as the value for this parameter. The user may edit this, if necessary, unless you make the parameter read-only.

You can edit the expression by invoking the Expression Assistant. Click the ellipsis button at the right of the Expression text field, and the Expression Assistant will appear.

When you're finished editing the expression, click the OK button on the Expression Assistant to commit the changes and return to the Interaction Wizard Editor. Notice that the Interaction Wizard Editor now displays the new value in the Expression field of Step 3.

You could have entered that same expression directly into the Expression field, provided you know the correct syntax.

Signature

The Signature text field shows the method signature. This latter field is read-only, as you cannot change the signature of this method.

When you are finished with Step 3, click the Finish button to validate all the changes and store them in the Interaction Wizard knowledge base.

Viewing the changes in the Interaction Wizard

To see how the changes affect the Interaction Wizard,
  1. Switch to the UI Designer by clicking on the Design tab if necessary.
  2. Select the component in the Component Tree (in our example, the ChartWrapper component).
  3. Choose Wizards|Interaction Wizard from the menu. Step 2 appears with the component already selected.

  4. Click the Next button to move to the next step. On Step 3, you can see that the exposed events are the one you chose to expose previously, in the order and with the description you entered.

  5. Select chartWrapper1 as the target component of the interaction. You can also see that the proposed actions are the one you suggested before: "Set the value for Q2".
  6. Click the Next button.

    Step 4 proposes the correct wording and default value.

    The code that would be generated in interactions.ini for this component is as follows:

    adapter CHART_FOCUS_EVENTS java.awt.event.FocusListener {  
         "The chart got focus" focusGained(FocusEvent)  
         "Lost Focus" focusLost(FocusEvent)  
      }
    

    component borland.jbcl.appletwrappers.barchart.ChartWrapper
    generates CHART_FOCUS_EVENTS {
        "Set the value for Q2" void
        "setc2_label(java.lang.String #Value for Q2# = 100)"
      }