Using Collection Objects
Surfer groups most objects in collections. Although these collections contain different types of data, they can be processed using similar techniques.
Count Property
All collection objects have a read-only property named Count which gives the number of objects in the collection.
Item Method
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, Axes, ScaleBars, and Overlays collection objects), the individual Shape objects are identified by the object ID assigned to the object.
-
In the Levels collection, individual Level objects may be retrieved by their index number only. The Level objects cannot be retrieved by name.
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
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, WksWindow, or GridWindow objects. When you retrieve a window from the Windows collection, a reference to a generic Window object is returned. Use the Window.Typeproperty to determine if the returned object is a PlotWindow, WksWindow, or GridWindowobject.
Add Method
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 Methods
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.
See Also
Parent and Application Properties
Introduction to the Major Surfer Objects