| Prev | Next | Start of Chapter | End of Chapter | Contents | Glossary | Index | Comments | (9 out of 13)

Using Actions with Connections

Several actions exist that manipulate connections. Following is a description of each action, along with an example.

Changing a Connection's Stripe-color

When you define regions for the cross-section pattern of a connection class, you can refer to those regions.

To refer to connection regions:

change the connection-region stripe-color of connection-class-name 
    to {color-name | symbolic-expression}

Creating Transient Connections

Connections can be of any connection class and may be orthogonal or diagonal, with or without direction, and located at an existing stub or in an entirely new position. G2 creates stubs for connections newly locating it at some location on an object; otherwise, G2 requires that a stub already exist at the specified position (locating it at).

You can create a connection with a port name or without, by specifying with portname none. You can create a connection on one object (connected to) with the other end of the connection left free, or between two objects (connected between). The create action fails if one or both objects has a configuration statement specifying not manual-connections.

Transient connections are orthogonal by default. When the connection is orthogonal, G2 places a bend at the end of each specified distance. If the connection is diagonal, G2 places a bend after each two distances, with a segment connecting bends. You can think of a diagonal connection as connecting odd-numbered bends in an imaginary orthogonal connection.

To create a connection using the create action:

create a connection [local name]  [of {class connection-class-name | 
 the class named by symbolic-expression}  ] connected
 {between-spec | to-spec} connection-spec [, ...]

The between-spec and to-spec uses this syntax:

{between item from-position and item to-position | 
    to end-position}


Element	Description
`from-position`	The item from which the connection is being drawn.
`to-position`	The item to which the connection is connecting.
`end-position`	See the following syntax description.

The end-position uses this syntax:

{  [at port-name] [  [newly] locating it at 
    {  {left | top | right | bottom} | the side named by side-expression}  } {integer | 
    at the position given by quantity-expression} [at {port-name | 
    the port named by port-name-expression}  ]  ]

The connection-spec uses this syntax:

{with style {diagonal | orthogonal} | 
    with the style named by symbolic-expression | with vertices integer [,...]   | 
    with the vertices given by integer-g2-list | 
    with direction {input | output} | 
    with the direction named by direction-expression |
    with portname port-name }

Several examples are:

The next sections illustrate several ways of creating connections and explain the statements.

Creating a Connection on One Side of an Object

This action creates a transient system-defined connection on the right side of the D1 object.

Note: To create a connection without direction, omit the with direction statement completely, as in this example. You cannot use the statement with direction none.

The newly locating it at statement indicates that no stub currently exists at the given location. If you omit this statement in any create action by stating only the position (at right 15), G2 requires that a stub exist at the location you specify.

Creating a Directional Connection

This action connects two objects with a transient connection located at existing stub locations of both items:

In this case, the statement also specifies a user-defined connection class, km-connection, to use and a direction (input).

You can make transient connections only to transient stubs, not to permanent stubs. If you create a connection to a stub, and the stub already has a connection on it with the other end free, G2 deletes both the old connection and the old stub, and creates a new stub.

Creating a Connection with Vertices

This action creates a connection, with specific vertices, on one side of an object, D1, as the example illustrates.

Specifying Connection Vertices

You specify vertices (bends) for a connection with a list of numbers, which determine how G2 draws the segments and vertices of a connection. Separate vertex numbers with a space character, not a comma (,).

Vertex numbers are relative to the starting point of the connection (top, bottom, right, or left). Positive numbers extend upwards and to the right of an icon, negative number extend downwards or to the left. The second number in a vertex specification determines in which direction the connection continues. After the second vertex, the pairs of values determine how G2 draws the remaining segments and vertices of the connection.

For example, in the previous diagram, the first number specifies the distance (20 workspace units) that G2 extends the connection from the icon before creating the first vertex. Both right and top connections require a positive first number to extend away from the object. Connections beginning at the left and bottom of an icon require a negative value first number to extend outwards from the object.

For connections that begin on the left or right side of an icon, the odd number vertices (1, 3, 5, etc.) always indicate a horizontal part of the connection, while even number vertices (2, 4, 6, etc.) specify the vertical connections. This rule reverses for connections that begin at the top or bottom of an icon - odd number vertices specify vertical connections, even numbers horizontal directions.

To illustrate this, the next two diagrams show how to specify the vertices for the same connection, starting first on the left and right sides of an icon, and starting second at the top and bottom of an icon, extending in different directions.

Recreating an Existing Connection Programmatically

A common requirement in KBs is to obtain the connections of an existing item and recreate them elsewhere on other items.

G2 provides the g2-get-connection-vertices system procedure for this purpose. The system procedure populates an integer list with the lengths of the connection segments and vertices of an existing connection. Positive values specify a segment extending upwards or to the right of an object or vertex, and negative numbers specify a segment extending downwards or to the left. Once populated, you can then use the list as the vertices specification for the create connection action and its given by integer-list grammar.

The integer list that the system procedure populates contains a minimum number of connection segments and vertices, typically one or two less than those of the original connection. When creating a new connection between two objects, the create action uses the vertices contained in the list, and then determines the last one or two vertices based on the location of the item to which the newly-created connection is being attached.

Note: The g2-get-connection-vertices system procedure has changed in recent G2 releases and currently returns the minimum number of vertices that the create action requires, rather than the exact number of vertices from the original connection. For KBs that may have relied on the previous behavior, a backward compatibility option exists to revert the system procedure to its previous behavior. For information about that option, see Changing the Backward Compatibility.

The following gds-get-connection-vertices procedure illustrates one way to use the system procedure in conjunction with the create connection action. This procedure creates a new object with connections identical to those of an existing item, which is passed to the procedure as an argument.

Making a Transient Connection Permanent

Use the make action to make a transient connection permanent. The next example appends the make permanent action to the create action:

Deleting a Connection

The delete action deletes a transient connection. You can delete a permanent connection by using the without permanence checks grammar. Deleting a connection leaves the stubs, unless you specify the optional removing connection stubs phrase, shown here:

Making an item with connections transient, and then deleting that item, automatically deletes the connection stubs.

Hint: Transient connections and their stubs are deleted whenever you reset the KB.

| Prev | Next | Start of Chapter | End of Chapter | Contents | Glossary | Index | Comments | (9 out of 13)

Copyright © 1997 Gensym Corporation, Inc.