Surfer Object Model
Surfer provides ActiveX Automation objects which allow scripts to control practically every feature of Surfer. These objects can be accessed from Scripter or from any Automation-enabled environment, such as Visual BASIC, Windows Scripting Host, or Excel.
Accessing Surfer
The means of accessing Surfer Automation objects varies depending on the scripting tool and language being used. With the Golden Software Scripter program and other applications compatible with Visual Basic, the CreateObject function creates a Surfer Application object:
Set x = CreateObject("Surfer.Application")
In this sample, a variable named "x" is assigned the value returned by the VBCreateObject function. The CreateObject function finds the name Surfer.Application in the system registry, automatically activates Surfer, and returns a reference to the SurferApplication object. For an introduction to the Scripter programming language, see the Scripter BASIC Language help.
After creating an Application object, you can access other Surfer objects through the properties and methods of the Application object. Surfer supplies nearly 60 different kinds of ActiveX Automation objects. These objects are organized in a hierarchy, with the Application object at the root. This object hierarchy is known as an object model.
Methods and Properties
Objects have attributes associated with them. The Grid object, for example, has an attribute called "xMin" which represents the minimum X coordinate of the grid. An object’s properties, also known as its properties, may be examined and changed by scripts. Some properties may be examined, but may not be changed. These are called read-only properties.
In addition to having properties, many Automation objects perform services. A Grid object, for example, will perform the "SaveFile" service when a script instructs it to do so. The services that an object performs are called its methods . Methods often require parameters to control how their services are performed. The Grid object’s "SaveFile" method, for example, accepts two parameters: a file name and a file format code.
The way you access Surfer Automation objects’ properties and methods varies depending on the programming language you use. In the Golden Software Scripter language, properties and methods are accessed by typing the name of an object variable, followed by a period, and the name of the property or method:
Set x = CreateObject("Surfer.Application")
x.Visible = True
This sample creates an Application object and sets the Application object's "Visible" property to the special "True" value predefined by the Scripter language.
You can find all the properties and methods which are available for each of the Automation objects, as well as a description of the objects themselves, in the online help. To view the online help, select either the Help | Automation Help command from the Surfer menu, or the Help | Surfer Automation Help command in Scripter. The ActiveX Automation Members dialog also shows you the available objects, properties, and methods. To view this dialog, select the Debug | Browse command in Scripter.
Collections
Several non-visible objects, called collection objects, are used to organize the object hierarchy. Collection objects are containers for groups of other, related, objects. For example, the Overlays collection contains the objects in a composite map. An Overlays collection object could contain a BaseLayer object, Wireframe object, and a PostLayer object if these three objects were overlaid together.
All collection objects, regardless of what the collection contains, can be processed using similar techniques. Thus, you retrieve an object from a collection of maps (an Overlays collection) the same way you retrieve an object from a collection of axes (an Axes collection). Collection objects also provide methods to create new objects.
Object Model Chart
The object model chart shows you which objects provide access to other objects in the hierarchy. Although the Application object is at the top of the hierarchy, not all objects are directly accessible from the Application object. To access many objects you must traverse from the Application object through one or more layers of sub-objects. People often refer to "drilling" or "boring" through the object hierarchy to describe this traversal through several objects to obtain an object you want to use.
To "drill through" the object hierarchy you must know which properties and methods of an object provide access to the next level of objects. Overview of Surfer Objects, discusses the most commonly used objects and the properties and methods which provide access to other objects in the hierarchy.
Every object represents a specific part of Surfer. For example, the Wireframe object represents a wireframe, and the Axis object represents a map axis. Some objects do not represent a visible entity, but organize other objects into groups. The Shapes object, for example, provides the means to create new maps and new drawing primitives (rectangles, symbols, polygons, etc.), but the Shapes object itself is never visible.
See Also
Introduction to the Major Surfer Objects
PlotWindow, WksWindow, and GridWindow Objects