Connecting beans

In Building your first applet, you learned about making connections. In this section, you explore the different types of connections and what you can do with them. It is best to follow along in the Visual Composition Editor as the different connection types are described and to try any examples discussed. Creating and experimenting with connections is an excellent way to learn how to use them.

Note:
In Property-to-property connections, you create a new applet. You can reuse this applet to follow along with all of the examples in this section.

There are six types of connections:

Property-to-property
Property-to-property connections link two data values together so that if both source and target events are specified in the connection's Property window, the two values stay in sync.
Event-to-method
Event-to-method connections call a method when an event occurs.
Event-to-code
Event-to-code connections run some code when an event occurs.
Parameter-from-property
Parameter-from-property connections use the value of a property as the parameter for a connection.
Parameter-from-code
Parameter-from-code connections run a code when a connection parameter is required.
Parameter-from-method
Parameter-from-method connections use the result of a method as a parameter to a connection.

Event-to-code and parameter-from-code connections enable you to connect to methods of the composite bean.

A connection has a source and a target. The point at which you start the connection is called the source. The point at which you end the connection is called the target. For information on connection properties, see Changing the properties of connections.

Note:
If a particular bean method, property, or event does not appear in the bean's preferred feature list in its bean or connection pop-up menu, you can select Connect and then Connectable Features from the bean pop-up or connection pop-up menu to display a complete list. The list of methods, properties, and events displayed in a window opened by selecting Connectable Features represents a bean's complete public interface.

Property-to-property connections

Property-to-property connections tie two data values together. The color of this connection type is blue. A simple example of a property-to-property connection follows:

  1. Create a new applet using the Create Applet SmartGuide:
  2. When the Visual Composition Editor opens on your new applet, place a JTextField bean and a JLabel bean within the default Applet bean.
  3. Connect the text property of the JTextField bean to the text property of the JLabel bean:
  4. Select the new connection you just created and click mouse button 2. Select Properties in the pop-up menu that appears. The Property-to-property connection Properties window appears.

  5. In the Properties window, select text for the Source event and select OK.

The free-form surface should look like this:

When you run the applet that contains these beans, the JLabel text becomes JTextField1.

For property-to-property connections, either endpoint can serve as the source or target. The only time it matters which property is the source and which is the target for a connection is at initialization. During initialization, the value of the target is updated to match the value of the source.

A property-to-property connection is initiated from the source bean's Connect choice in the pop-up menu and is terminated by selecting the appropriate target bean's feature.

Event-to-method connections

Event-to-method connections cause a method to be called when a certain event takes place. The color of this connection type is green.

For event-to-method connections, the event is always the source and the method is always the target. A simple example of an event-to-method connection follows:

  1. Place a JButton bean within the default JApplet bean in the Visual Composition Editor. Change the text of this button to Open Window.
  2. Place a JFrame bean on the free-form surface of the Visual Composition Editor.
  3. Connect the actionPerformed event of the JButton to the show method of the JFrame bean. To do this connection, click the title bar of JFrame (not inside the box itself). The frame appears when the Button is selected.

The free-form surface should look like this:

te2mcon1.gif (1272 bytes)

Properties can also be used to call a method, and events can be used to change the value of a property. This behavior is possible because VisualAge for Java can associate an event with a change in property value. As a result, you can make the following connections with properties:

Connecting an event to a property

In addition to calling a method, an event can also be used to set a property value. In this case, a parameter must be used with the connection to supply the property value. A simple example of an event-to-property connection follows:

  1. Place a JLabel bean within the default applet bean in the Visual Composition Editor and change its text property in the Properties window to the string This is a JFrame title.
  2. Place a JButton bean within the applet bean in the Visual Composition Editor.
  3. Place a JFrame bean on the free-form surface of the Visual Composition Editor.
  4. Connect the actionPerformed event of the JButton to the show method of the JFrame bean. Remember to click the title bar of JFrame to see the show method.
  5. Connect the componentShown event of the applet bean to the title property of the JFrame bean.
  6. Now, to provide the parameter for the event-to-property connection you just created, connect the text property of the JLabel bean to the value property in the connection pop-up menu.

The free-form surface should look like this:

te2pcon1.gif (1775 bytes)

When you run the applet and select the button, the title text of the frame is set to This is a JFrame title. This example is rather contrived, but it conveys the idea. For more information, see Connection parameters.

Event-to-code connections

Event-to-code connections run a given method when a certain event takes place. This provides a way to implement or alter applet behavior directly through the use of the Java language. The target of an event-to-code method can be any method in the class that you are manipulating in the Visual Composition Editor.

Note:
An event-to-method connection is made between two beans. An event-to-code connection is made between a bean and a method in the composite bean. The method in the composite been does not have to be public.

The color of an event-to-code connection is green. To create an event-to-code connection:

  1. Select the source bean (for example, a JButton). Click mouse button 2 to display the bean's pop-up menu. Select Connect and then select an event, such as actionPerformed. The mouse pointer changes.
  2. Move the mouse pointer to any open area of the free-form surface. It cannot be over any bean, including the default Applet bean. Click mouse button 1 and select Event to Code from the pop-up menu.
  3. The resulting window allows you to pick from the list of available methods, or to create a new method.
  4. Once you've selected a method, select OK to complete the connection.

The connection is drawn between the source bean and a movable text box that contains the name of the method.

te2scon1.gif (1115 bytes)

Parameter connections

The last three types of connections supply a parameter to a connection from various sources:

  1. Parameter-from-property
  2. Parameter-from-code
  3. Parameter-from-method

The color for a parameter connection line is purple.

Parameter-from-property

Parameter-from-property connections use the value of a property as the parameter to a connection. As with other connection types, a parameter-from-property connection is initiated from the source bean's Connect choice in the pop-up menu and is terminated by clicking mouse button 1 over the target connection line requiring the parameter. You then select the appropriate property from the pop-up menu for the connection.

A parameter-from-property connection was used in building the To-Do List sample. When we connected the JTextField bean's text property to the connection between the JButton bean and the DefaultListModel bean, we were making a parameter-from-property connection. Refer to Connecting beans for the specific connection details for the To-Do List sample. The following example also illustrates the use of the parameter-from-property connection:

  1. Place a JLabel bean, a JTextField bean, and a JButton bean within the applet bean in the Visual Composition Editor.
  2. Connect the actionPerformed(awt.java.event.ActionEvent) event of the JButton bean to the text property of the JLabel bean.
  3. Now, make the parameter-from-property connection by connecting the text property of the JTextField bean to the value property of the connection pop-up menu.

The free-form surface should look like this:

tprmfprp.gif (857 bytes)

When you run the applet and type text into the text field and select the button, the label text is set to match the text in the text field.

Parameter-from-code

Parameter-from-code connections run a method whenever a parameter to a connection is required. This connection is much the same as a parameter-from-property connection, except that the value supplied to the connection is returned from a Java method instead of a bean property value.

For the sake of illustration, assume that we have created a simple method called stringFromCode in the applet class that returns the text this is a string. An example of a parameter-from-code connection follows. Unlike other connection types, a parameter-from-code connection is initiated from the parameter name in the connection's pop-up menu and is terminated as follows:

  1. Place a JLabel bean and a JButton bean within the default JApplet bean in the Visual Composition Editor.
  2. Connect the actionPerformed event of the JButton to the text property of the JLabel bean.
  3. Now, create the parameter-from-code connection by connecting the value property in the connection pop-up menu to the method as follows:

Parameter-from-method

Parameter-from-method connections use the result of a method as a parameter to a connection. An example of how to use a parameter-from-method connection follows:

  1. Place a JButton bean and a JTextField bean within the default applet bean in the Visual Composition Editor.
  2. Connect the actionPerformed event of the JButton bean to the text property of the JButton bean. (Yes, connecting an event to a property for the same bean does make sense in the right situation.)
  3. Then, make the parameter-from-method connection by connecting the getText() method of the JTextField bean to the value property in the connection's pop-up menu. This provides the needed connection parameter and causes the connection line to become solid in color.

When you test the applet, type a string into the text field and then select the Button. The string becomes the label for the Button.

tprmfmtd.gif (743 bytes)

Changing the properties of connections

Connections, like beans, have properties. To open the properties for a connection, select Properties from the connection's pop-up menu. Or, just double-click on the connection.

The following figure shows the Properties window for a property-to-property connection:

tjgscpro.gif (6167 bytes)

You can use a connection's Properties window to change the source or target property of the connection. To do this, select a different source or target property from the appropriate list. To display the current source and target properties of the connection, select Reset.

If you want the source property of a property-to-property connection to be the target property, and vice versa, you can change the source and target properties by selecting Reverse in the connection's Properties window.

When you have finished changing the connection's properties, select OK.

Connection parameters

Event-to-method and event-to-code connections sometimes require parameters (or arguments). The method's parameters are available as properties of the connection. Therefore, to specify a parameter, you simply make a connection to the parameter property of the event-to-method connection itself.

When a connection requires parameters that have not been specified, it appears as a dashed line, indicating that the connection is not complete.

In the To-Do List applet, you connected the JButton bean's actionPerformed event to the DefaultListModel bean's addElement(java.langObject) method, and a dashed line resulted:

* Figure jgscdash not displayed.

The parameters that methods require are indicated by the items inside parentheses () in the method name. For example, the addElement(java.lang.Object) method takes one parameter, an Object. A method named insert ElementAt(java.lang.Object, int) takes two parameters, an Object and an int.

When you have specified all of the necessary parameters, the connection line becomes solid, indicating the connection is complete. If you do not supply enough parameters for a connection, the connection continues to appear as a dashed line.

To specify parameters you can use properties or constants.

Properties as parameters

Most of the time, the parameters you need are properties of other beans you are working with in the Visual Composition Editor. To use a bean's property as a parameter:

  1. Make a new connection using the bean's property as the source.
  2. For the target, click mouse button 1 on the connection line that requires the parameter, and then from its connection menu, select the particular parameter property you are specifying.

    While making a connection to a connection line, you will see a small visual cue in the middle of the connection line when the mouse pointer is directly over the connection line, indicating the pointer is positioned correctly.

    * Figure jgscbox not displayed.

In the To-Do List applet, the text entered in the JTextField bean is used as the parameter of the event-to-method connection between the Add Button and the DefaultListModel bean.

tjgscpar.gif (1420 bytes)

In this example, you provided the parameter of the event-to-method connection by making a property-to-property connection between the JTextField bean's text property and the event-to-method connection's obj property. The connection's obj property is the name of the first and only parameter of the addElement(java.lang.Object) method.

Constants as parameters

Parameter values can also be constants. You specify a constant value for a parameter in the Properties window for the connection.

For example, to specify a constant value for the parameter for an event-to-method connection:

  1. Double-click on the event-to-method connection.

    The Properties window for an event-to-method connection opens:

    tjgsprop.gif (6848 bytes)

  2. In this window, select Set parameters. The Constant Parameter Value Settings window opens:

    tjgscons.gif (2435 bytes)

  3. In the Constant Parameter Value Settings window, type the constant values for the parameters you want to add.
  4. When you finish, select OK, and then select OK in the Properties window for the event-to-method connection.

Manipulating connections

Like beans, once connections are made, you can manipulate them in many different ways.

Selecting and deselecting connections

You select and deselect connections the same way you select and deselect beans. You can select multiple connections. The information about the currently selected connection is displayed in the information area at the bottom of the Visual Composition Editor.

Note:
You cannot select beans and connections at the same time.

Deleting connections

To delete a connection, select Delete from its pop-up menu. You can also delete a connection by selecting the connection and pressing the Delete key.

To delete several connections, select the connections you want to delete, and then select Delete from the pop-up menu of one of the selected connections.

Reordering connections

When you make several connections from the same event or property of a bean, the connections run in the order in which they were made. However, if you create the connections in a different order than the order in which you want to run them, you can reorder them. Add a JButton and two JFrame containers. Connect an actionPerformed event from the button to a show method at one frame. Make the same connection to the second frame. You now have two connections to open frames. When you run the applet, one frame will appear followed by the second after you click the button.

ttodofcn.gif (1982 bytes)

If you need to change the order of connections, simply reorder the connections from the bean by doing the following:

  1. From the bean's pop-up menu, select Reorder Connections From.

    The Reorder connections window appears:

    tjgsreor.gif (3404 bytes)

    The Reorder connections window contains all of the connections for the bean you selected. In this example, the (JButton1, actionPerformed -> JFrame2, show() connection is the first one that runs.

  2. In the Reorder connections window use the appropriate mouse button to reverse the frame appearance order. In OS/2, use mouse button 2; in Windows, use mouse button 1.

    As you drag a connection through the list, a dark line appears to indicate where the connection will be inserted when you release the mouse button. Rerun your applet to see the effect.

Showing, hiding, and browsing connections

You can show and hide connections by using the Hide Connections tool and the Show Connections tool from the tool bar.

* Figure HIDECONN not displayed.  * Figure HIDECONN not displayed.

These tools show and hide all connections to and from the selected bean or beans. If no beans are selected, these tools will show and hide all the connections in the Visual Composition Editor.

You can selectively show and hide a bean's connections by selecting Browse Connections from the bean's pop-up menu and then selecting one of the following:

Show To
Shows all connection lines extending to the bean
Show From
Shows all connection lines extending from the bean
Show To/From
Shows all connection lines extending to and from the bean
Show All
Shows all connection lines
Hide To
Hides all connection lines extending to the bean
Hide From
Hides all connection lines extending from the bean
Hide To/From
Hides all connection lines extending to and from the bean
Hide All
Hides all connection lines

Arranging connections

When you select a connection, selection handles are displayed at both ends and along the connection line. You can then drag the mid-point selection handle to a new position. This makes the connection line draw in a different area of the free-form surface, which can help you distinguish among several connection lines that are close together. When additional selection handles appear, you can then drag the middle selection handle to a new position to bend the connection line even further.

You can restore a connection line to its original shape. From the pop-up menu for the connection line, select Restore Shape.

Changing connection endpoints

VisualAge for Java gives you the ability to change the endpoint bean of a connection, meaning that you can change the source or target bean of the connection. It is quicker than deleting the connection and creating a new one.

For event-to-method and property-to-property connections, you can move either end of the connection. For event-to-code connections, you can only move the event end of the connection.

To change either end of a connection:

  1. Select the connection whose endpoint you want to change. Selection handles appear along the connection line.
  2. Move the mouse pointer over the selection handle at the end of the connection you want to change. Using the appropriate mouse button, drag the selection handle to the new bean. In OS/2, use mouse button 2; in Windows, use mouse button 1.

    If you move the endpoint of a connection to a bean that does not have the same property available as in the original connection, the bean's connection pop-up menu appears so you can specify a new property to connect to.