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

Surfer Object Model

Overview of Surfer Objects

Introduction to the Major Surfer Objects

Using Surfer Objects

Derived Objects

PlotWindow, WksWindow, and GridWindow Objects

Object Hierarchy

Object List

Optional Arguments and Named Arguments