Referencing collections

Understanding automation : How is automation coding structured? : Referencing collections

Referencing collections

Many objects are members of collections. A collection is similar to an array, except that it contains objects rather than values. However, members of collections can be accessed in the same way as arrays. For example, a collection that is used frequently is the collection of shapes on a layer: The object ActiveLayer references either the current layer or the layer that is selected in the Object Manager docker.

CorelDRAW contains many collections: A document contains pages, a page contains layers, a layer contains shapes, a curve contains subpaths, a subpath contains segments and nodes, a text range contains lines and words, a group contains shapes, and the application contains windows. All these collections are handled by VBA in the same way.

Referencing collection items

To reference the shapes on a layer, the collection of shapes for that layer is used: ActiveLayer.Shapes. To reference the individual shapes in the collection, the Item() property is used. Here is a VBA example:

Dim sh As Shape

Set sh = ActiveLayer.Shapes.Item(1)

Most elements of a collection start at 1 and increase. For the collection ActiveLayer.Shapes, Item(1) is the item at the “top” or “front” of the layer — in other words, it is the item that is in front of all other shapes. Furthermore, because each item in the ActiveLayer collection is an object of type Shape, you can reference any item in VBA merely by appending the appropriate dot-notated member:

ActiveLayer.Shapes.Item(1).Outline.ConvertToObject

Sometimes, individual items have names. If the item you are looking for has an associated name (and you know what the name is and which collection the item is in), you can use that name to reference the item directly, as in the following VBA example:

Dim sh1 As Shape, sh2 As Shape

Set sh1 = ActiveLayer.CreateRectangle(0, 5, 7, 0)

sh1.Name = "myShape"

Set sh2 = ActiveLayer.Shapes.Item("myShape")

Also, because an item is usually the implied or default member of a collection, it is not strictly required. For this reason, the last line of the preceding VBA code can be rewritten as follows:

Set sh2 = ActiveLayer.Shapes("myShape")

Counting collection items

All collections have a property called Count. This read-only property gives the number of members in the collection, as in the following VBA example:

Dim count As Long

count = ActiveLayer.Shapes.Count

The returned value is not only the number of items in the collection: Because the collection starts from 1, it is also the index of the last item.

Parsing collection items

It is often necessary to parse through the members of a collection to check or change the properties of each item.

By using the Item() and Count members, it is straightforward to step through a collection of items. With each iteration, it is possible to test the properties of the current item, or to call its methods. The following VBA code restricts all shapes on the layer to no wider than ten units:

Dim I As Long, count As Long

count = ActiveLayer.Shapes.Count

For I = 1 to count

If ActiveLayer.Shapes.Item(i).SizeWidth > 10 Then

ActiveLayer.Shapes.Item(i).SizeWidth = 10

End If

Next I

There is, however, a more convenient way of parsing a collection in VBA. Instead of using the Count property and a For-Next loop, this technique uses a For-Each-In loop:

Dim sh As Shape

For Each sh In ActiveLayer.Shapes

If sh.SizeWidth > 10 Then

sh.SizeWidth = 10

End If

Next sh

If you want to copy the selection and then parse it later when it is no longer selected, copy the selection into a ShapeRange object:

Dim sr As ShapeRange

Dim sh As Shape

Set sr = ActiveSelectionRange

For Each sh In sr

' Do something with each shape

Next sh