Using Collection Objects

MapViewer groups most objects in collections. Although these collections contain different types of data, they can be processed using similar techniques.

Count

All collection objects have a read-only property named Count which gives the number of objects in the collection.

Item

Every collection also has a method called Item which retrieves one of the objects contained in the collection. The Item method accepts a single argument specifying either an index number or (for most collections) the name of the object to retrieve. An index number is a value between 1 and the value returned from the collection’s Count property. The name used to identify items in a collection varies:

In a Documents collection, the individual Document objects are identified by the file name (or the caption, if the document has not been saved in a file yet).
In a Windows collection, individual Window objects are identified by the window caption.
In collections containing objects derived from the Shape object (Shapes, Selection, and Layers collection objects), the individual Shape objects are identified by the object ID assigned to the object.

A shorthand syntax for retrieving items from a collection is to enclose the index or name of the desired object in parentheses immediately following the name of a collection object (similar to accessing an element in an array). Thus, the following two instructions have the same effect:

' Assume "docs" is a variable holding a reference to the Documents collection

docs.Item(1) ' retrieves the first object in the collection

docs(1) ' shorthand, retrieves the first object in the collection

Type

Objects contained in collections are typically derived from a base object. When you use the Item method to retrieve an object from a collection, the method returns a reference to the base object. To determine the actual type of the returned object, most base objects contain a Type method. For example, the Windows collection may contain PlotWindow or WksWindow objects. When you retrieve a window from the Windows collection, a reference to a generic Window object is returned. Use the Window.Type property to determine if the returned object is a PlotWindow or WksWindow object.

Add

Many collections have one or more Add methods for creating new items and adding them to the collection. For example, to add a rectangle to the Shapes collection, you would use the AddRectangle method:

Shapes.AddRectangle 2, 2, 4, 4

Close and Delete

The objects contained by collections are automatically removed when the contained object is deleted or closed. For example, call a Document object’s Close method to close a document or call the Shape object’s Delete method to remove any Shape-derived object.