DropMany[U] method

Microsoft Visio Developer Reference

DropMany[U] method

       

Creates one or more new Shape objects on a page, in a master, or in a group. It returns an array of the IDs of the Shape objects it produces.

Version added

4.5

Syntax

intRet = object.DropMany(ObjectsToInstance, xyArray, IDArray)

intRet

Integer. Number of entries in xyArray that processed successfully.

object

Required. An expression that returns a Page, Master, or Shape object in which to create new shapes.

ObjectsToInstance

Required Variant. Identifies masters or other objects from which to make shapes.

xyArray

Required Double. An array of alternating x and y values specifying the positions for the new shapes.

IDArray

Required Integer. An array that returns the IDs of the created shapes.

Remarks

Using the DropMany method is like using the Page, Master, or Shape object's Drop method, except you can use the DropMany method to create many new Shape objects at once, rather than one per method call. The DropMany method creates new Shape objects on the page, in the master, or in the group shape to which it is applied (this shape is called the "target object" in the following discussion).

ObjectsToInstance should be a one-dimensional array of n >= 1 variants. Its entries identify objects from which you want to make new Shape objects. An entry often refers to a Visio application Master object. It might also refer to a Visio application Shape object, Selection object, or even an object from another application. The application doesn't care what the lower and upper array bounds of the ObjectsToInstance entries are. Call these vlb and vub, respectively.

  • If ObjectsToInstance(i) is an unknown or dispatch (in Microsoft Visual Basic for Applications, a reference to a selection, shape, master, guide, or OLE object), then the object it is referencing is instanced. This is essentially equivalent to calling Drop(ObjectsToInstance(i),x,y).
  • If ObjectsToInstance(i) is the integer j, then an instance of the Master object in the document stencil of the target object's document whose 1-based index is j is made. The EventDrop cell in the Events section of the new shape is not triggered. Use the Drop method instead if you want the EventDrop cell to trigger.
  • If ObjectsToInstance(i) is the string s (or a reference to the string s), then an instance of the Master object with name s in the document stencil of the target object's document is made; s can equal either the Master object's UniqueID or Name property. The EventDrop cell in the Events section of the new shape is not triggered. Use the Drop method instead if you want the EventDrop cell to trigger.
  • For vlb < i <= vub, if ObjectsToInstance(i) is empty (Nothing or uninitialized in Microsoft Visual Basic), then entry i will cause ObjectsToInstance(j) to be instanced again, where j is the largest value < i such that ObjectsToInstance(j) isn't empty. If you want to make n instances of the same thing, only ObjectsToInstance(vlb) needs to be provided.

The xyArray argument should be a one-dimensional array of 2m doubles with lowerbound xylb and upper bound xyub, where m >= n. The values in the array tell the DropMany method where to position the Shape objects it produces. ObjectsToInstance(vlb + ( i - 1)) is dropped at (xy[(i - 1)2 + xylb],xy[(i - 1)2 + xylb + 1]) for 1 <= i <=n.

Note that m > n is allowed. For n < i <= m, the i'th thing instanced is the same thing as the n'th thing instanced. Thus to make m >= 1 instances of the same thing, you can pass an ObjectsToInstance array with one entry and an m entry xyArray array.

If the entity being instanced is a master, the pin of the new Shape object is positioned at the given xy. Otherwise, the center of the Shape objects is positioned at the given xy.

The value intRet returned by the DropMany method is the number of xy entries in xyArray that the DropMany method successfully processed. If all entries processed successfully, then m is returned. If some entries are successfully processed prior to an error occurring, then the produced Shape objects are not deleted and this raises an exception yet still returns a positive intRet.

Presuming all m xy entries process correctly, the number of new Shape objects produced by the DropMany method is usually equal to m. In rare cases (for example, if a Selection object gets instanced), more than m Shape objects may be produced. The caller can determine the number of produced Shape objects by comparing the number of shapes in the target object before and after the DropMany method executes. The caller can assert the new Shape objects are those with the highest indices in the target object's Shapes collection.

If the DropMany method returns zero (0), IDArray returns Null (Nothing). Otherwise, it returns a one-dimensional array of m integers indexed from 0 to m - 1. IDArray is an out argument that is allocated by the DropMany method and ownership is passed to the program that called the DropMany method. The caller should eventually perform the SafeArrayDestroy procedure on the returned array. (Visual Basic and Visual Basic for Applications take care of this for you.)

If IDArray returns non-Null (not Nothing), then IDArray(i - 1), 1 <= i <= intRet, returns the ID of the Shape object produced by the i'th xyArray entry, provided the i'th xyArray entry produced exactly one Shape object. If the i'th xyArray entry produced multiple Shape objects, then -1 is returned in the entry. All entries i, intRet <= i < m, return -1.

Note Beginning with Visio 2000, you can refer to Visio shapes, masters, styles, pages, rows, and layers using local and universal names. When a user names a shape, for example, the user is specifying a local name. Universal names are not visible through the user interface. As a developer, you can use universal names in a program when you don't want to change a name each time a solution is localized. Use the DropMany method to drop more than one shape when using local names to identify the shapes. Use the DropManyU method to drop more than one shape when using universal names to identify the shapes.