Understanding automation : How is automation coding structured? : 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.
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") |
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.
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 |
Copyright 2013 Corel Corporation. All rights reserved.