Page.DropManyLinkedU Method (Visio)

Creates multiple new shapes on the drawing page that are linked to multiple data rows in a data recordset. Returns the number of shape instances created and an array of IDs of those shapes.

Version Information

Version Added: Visio 2007

Syntax

expression .DropManyLinkedU(ObjectsToInstance(), XYs(), DataRecordsetID, DataRowIDs(), ApplyDataGraphicAfterLink, ShapeIDs())

expression An expression that returns a Page object.

Parameters

Return Value

Long

Remarks

When you want to create shapes already linked to data on a drawing page that either does not contain any shapes or contains shapes other than the ones you want to link, you can use the Page.DropLinked and Page.DropManyLinkedU methods to create one or more additional shapes already linked to data. These methods resemble the existing Page.Drop and Page.DropManyU methods in that they create additional shapes at a specified location on the page; but in addition, they create links between the new shapes and specified data rows in a specified data recordset.

For the ObjectsToInstance() parameter, pass an array of objects to instance into shapes linked to data. While these objects are typically Visio objects such as Master, Shape, or Selection objects, they can be any OLE objects that provide an IDataObject interface.

For the XYs() parameter, pass an array of type Double. Each consecutive pair of array-index-position values should correspond to the x- and y- page coordinates where you want the instance of the object in the corresponding positon in the ObjectsToInstance() array to be positioned. For example, if you want the instance of the object in the first array index position in ObjectsToInstance() to be positioned at page coordinate (2,4), place the value 2 in the first array index position in XYs(), and place the value 4 in the second array index positon in that array, and so on for the rest of the objects and coordinates.

When an object you pass in the ObjectsToInstance() array is a shape, the center of the shape's width-height box is positioned at the coordinates you specify in XYs().

When an object you pass in the ObjectsToInstance() array is a master, the pin of the master is positioned at the coordinates you specify in XYs(). A master's pin is often, but not necessarily, at its center of rotation.

For the DataRowIDs() parameter, pass an array of Long values that represent the IDs of the data rows in the data recordset that you want to link to the shape instances created from the objects in the corresponding array index positions in the ObjectsToInstance() array.

For the ShapeIDs() parameter, pass an empty, dimensionless array of type Long. The method will return the array filled with the IDs of the newly created and linked shapes.

Example

The following Microsoft Visual Basic for Applications (VBA) macro shows how to use the DropManyLinkedU method to create several shapes on the active drawing page, centered at specified coordinates, and linked to a data rows in the data recordset most recently added to the active document. It prints the number of shapes created and their ID numbers to the Immediate window.

The shapes passed to the DropManyLinkedU method are simple forms from the Basic Shapes (US units) stencil. Before running this macro, use the DataRecordsets.Add method or another means to add at least one data recordset to the DataRecordsets collection, and make sure that the Basic Shapes (US units) stencil is open in the Visio drawing window.

Sub DropManyLinkedU_Example() 
 
    Dim avarObjects(0 To 2) As Variant 
    Dim adblXYs(0 To 5) As Double   
    Dim alngDataRowIDs(0 To 2) As Long 
    Dim alngShapeIDs() As Long 
    Dim vsoDataRecordset As Visio.DataRecordset 
    Dim intRecordesetCount As Integer 
    Dim lngReturned As Long 
    Dim intCounter As Integer 
     
    intRecordsetCount = Visio.ActiveDocument.DataRecordsets.Count 
    Set vsoDataRecordset = Visio.ActiveDocument.DataRecordsets(intRecordsetCount) 
     
    Set avarObjects(0) = Visio.Documents("Basic_U.VSS").Masters("Rectangle") 
    Set avarObjects(1) = Visio.Documents("Basic_U.VSS").Masters("Triangle") 
    Set avarObjects(2) = Visio.Documents("Basic_U.VSS").Masters("Circle") 
     
    adblXYs(0) = 2 
    adblXYs(1) = 2 
    adblXYs(2) = 4 
    adblXYs(3) = 4 
    adblXYs(4) = 6 
    adblXYs(5) = 6 
         
    alngDataRowIDs(0) = 1 
    alngDataRowIDs(1) = 2 
    alngDataRowIDs(2) = 3 
         
    lngReturned = ActivePage.DropManyLinkedU(avarObjects, adblXYs, vsoDataRecordset.ID, alngDataRowIDs, True, alngShapeIDs) 
    Debug.Print lngReturned 
     
    For intCounter = 0 To lngReturned - 1 
        Debug.Print alngShapeIDs(intCounter) 
    Next 
     
End Sub