Syntax for connections

The build instructions for samples that use visual construction contain a syntax for describing connections.

The following information is provided in the syntax:

There are three types of features: property, event, or method.

To make a connection either from the Visual Composition Editor or from the Beans List:

  1. Place the cursor over the source bean and click mouse button 2
  2. Select Connect from the pop-up menu
  3. Select the appropriate feature from the list, or select Connectable features to see all of the available features and make your selection
  4. Move the cursor to the target bean and click mouse button 1
  5. Select the target feature from the list, or select Connectable features to select the appropriate feature
There are three types of connections which are described below:

Property-to-Property connections

In most cases, you would make property-to-property connections to achieve the result of property values staying in sync.  If properties are defined as "bound", they fire an event when they change.  If both properties in a property-to-property connection are bound, a change in one results in a change in the other.  The following connection between bound properties of Address1 and Customer1 results in the street property of Address1 being set to the value in the street property of Customer1 when Customer1's street changes.  It would also result in the street property of Customer1 being set to the value in Address1 if Address1's street changes. Some properties are not defined as "bound", which means that they do not fire an event when they change.  In a property-to-property connection, the firing of the event when a change occurs is what causes one property to be set to the value of another.  In the case of a property that is not bound, you need to identify an event to be used to trigger the change in property value.  In the connection syntax, a "source event" or a "target event" is specified where needed.

In the following connection, the street property of Address1 will change to the value in the text property of TextField1 only when the textValueChanged event occurs.

To associate a target event with a connection, double-click on the connection in the Beans List.  In the property sheet for the connection, use the Target event pulldown to select the event.

Event-to-Code

In some cases you want to invoke a method you have written when an event occurs.  You use an event-to-code connection in this case.  The syntax will identify the target with the word "CODE" and the name of the method to be invoked. For the following connection, the setButtonState method will be invoked when the UpdateButton is clicked. To make an event-to-code connection: See the description of handling parameters and results in the section on event-to-method connections

Event-to-method

In many cases you want to invoke a feature of a bean that is a method when an event occurs, and you can use an event-to-method connection for this purpose.

Methods can take parameters and provide results.  Connections can be made to provide input for the parameter, or to use the result from a method. The syntax identifies connections made to these connection features.  In the following example, the connection between the WindowOpened event and the getMessageBoxInstance method has a parameter called buttonSpec and a result called normalResult:

To make these parameter and result connections
  1. Place the cursor over the connection that the parameter or result is related to
  2. Click mouse button 2
  3. Select the parameter or result from the list
  4. Move the cursor to the target
  5. Press mouse button 1
  6. Select the target feature from the list, or select Connectable features to select the appropriate feature.
The syntax identifies the target name, the feature name, and the feature type.

A parameter can be provided from the return value of another method.  In turn, that method might also take a parameter, which could also be provided by a return value.  A large number of parameter connections could be made from one source and target connection.  Nesting is used in the syntax to illustrate these additional connections.  In the following example, when the actionPerformed event occurs for Bean1, the doSomething  method of Bean2 will be invoked.  The MyComponent parameter will be provided by the return value from the getMyComponent method.  Bean2 will be provided as the parameter to the getMyComponent method.

To make these connections
  1. Place the cursor over the connection that the parameter or result is related to
  2. Click mouse button 2
  3. Select the feature from the list
  4. Move the cursor to the target
  5. Click mouse button 1
  6. Select the target feature from the list, or press Connectable features to select the appropriate feature.
For example, in the previous connection the connection for comp is made by placing the cursor over the connection between value and Bean3 getMyComponent, selecting comp from the list, then moving to Bean2 and selecting "this".

In some cases you want to pass a constant to a method.  In the following connection example, the int parameter named status will be a constant set to 0.

To set a parameter to a constant:
  1. Place the cursor over the connection involving the method
  2. Click mouse button 2
  3. Select Properties
  4. Click Set parameters
  5. Select a parameter
  6. Enter a constant value
You might want to invoke a method that is not a feature of your bean to provide the input to a parameter.  In the following example, when the actionPerformed event occurs for Bean1, the doSomething  method of Bean2 will be invoked.  The MyComponent parameter will be provided by the return value from the findMyComponent method. To set a parameter from the return value of a method that is not a feature:
  1. Place the cursor over the connection that the parameter or result is related to
  2. Click mouse button 2
  3. Select the parameter from the list
  4. Move the cursor to the free-form surface
  5. Click mouse button 1
  6. Select Parameter from Code
  7. Enter your method name, source code, and parameter constants as appropriate
For more information about connections, see the product documentation.