December, 2010

[Note: This is the third in a series of blog posts that highlight some of the new members of the Visio VBA object model.]

In the first post in this series, I talked about the Page.DropConnected method. In the second post, I featured another new method on the Page object of the Visio 2010 VBA object model that you might not yet have encountered, the Page.LayoutChangeDirection method, which makes it possible to rotate or flip a set of two or more connected shapes on the page as a unit, without having to rotate or flip the individual shapes.

This post focuses on yet another new method on the Page object, the Page.AutoConnectMany method.

The syntax for this method is as follows:

Page.AutoConnectMany(FromShapeIDs(), ToShapeIDs(), PlacementDirs(), [Connector])

This method works in much the same way for multiple shapes that the existing Shape.AutoConnect method works for a single shape—the main differences being the object upon which it operates and the parameters it takes. The AutoConnect method operates on a single Shape object and takes another Shape object to which to connect, a constant representing the direction from the source shape in which to place the target shape, and an optional connector specification.

The AutoConnectMany method operates on a Page object and takes a series of arrays of Longs that represent:

• identifiers of the shapes on the page from which to draw a connection
• identifiers of the shapes on the page to which to draw a connection
• the directions in which to draw the connections. You pass a constant from the VisAutoConnectDir enumeration.

The items at the same array positions should all correspond to the same action.

The method also lets you specify the connector to use,  which can be a Master, MasterShortcut, Shape, or IDataObject object. This parameter is optional.

The method returns a Long that represents the number of shapes connected.

Here’s how this method works. Suppose you create a blank Visio drawing and drag the following shapes onto the page, in the order listed:

• Square
• Circle
• Rounded Rectangle
• Ellipse

Arrange the shapes like this:

Now paste the following code into the Visual Basic Editor code window (to open it, press ALT+F11) and then run it:

Public Sub AutoConnectMany_Example()

    Dim lngFromIDs(0 To 1) As Long
    Dim lngToIDs(0 To 1) As Long
    Dim lngPlacementDirs(0 To 1) As Long
    Dim lngConnectionsMade As Long
   
    lngFromIDs(0) = 1
    lngFromIDs(1) = 2
   
    lngToIDs(0) = 3
    lngToIDs(1) = 4
   
    lngPlacementDirs(0) = visAutoConnectDirDown
    lngPlacementDirs(1) = visAutoConnectDirUp
   
    lngConnectionsMade = ActivePage.AutoConnectMany(lngFromIDs, lngToIDs, lngPlacementDirs)
       
    Debug.Print lngConnectionsMade
   
End Sub

The diagram should now look like this:

Connectors are drawn from the first pair of shapes added to the page (square, circle) to the second pair (rounded rectangle, ellipse) in the directions specified. Note that in the case of the second connection, the ellipse is actually moved above the circle, because the connection direction specified is “up”.

Note also that the default connector is used, because no connector is specified (the optional connector parameter is omitted).

Visio prints the number of connections made, 2, in the Immediate window.