A Brief Introduction to the Major Surfer Objects
The following will introduce some of the most important Surfer automation objects. This is by no means comprehensive. Please see Objects, Properties, and Methods for a complete list.
Application Object
The Application object represents the Surfer program. All navigation through the Surfer object model begins with the Application object. The Application object is a single instance of Surfer and it is the root of all objects in Surfer. External programs will typically create an instance of the Application object during initialization. In VB this is done using the function as in:
Set SurferApp = CreateObject("Surfer.Application")
The CreateObject function activates a new instance of Surfer, and returns a reference to the Application object to your script. If Surfer is already running, and you do not want to start a new instance of Surfer, use the VB GetObject function instead of CreateObject:
Dim SurferApp As Object
Set SurferApp = GetObject(,"Surfer.Application")
The GetObject function obtains the Application object from the currently running instance of Surfer. If Surfer is not already running, the function will fail. Call the Application object’s Quit method to close Surfer from a script.
When Surfer is started by a script, its main window is initially hidden. To make the Surfer window visible, you must set the Application object’s Visible property to True:
Set SurferApp = GetObject(,"Surfer.Application")
SurferApp.Visible = True
Most of the gridding-related operations are methods of the Application object. Use the GridData, GridFunction, GridMath, GridFilter, GridSplineSmooth, GridAssignNoData, GridConvert, GridVolume, GridSlice, GridTransform, GridExtract, and GridCalculus methods to create new grids and perform computations with grids.
Other methods and properties of the Application object let you move and resize the Surfer window, adjust the main window state (maximized, minimized, hidden), change the window caption, and modify preference settings.
The Application object provides two important collections that allow access to the next level of objects in the hierarchy. Use theDocumentsproperty to obtain a reference to the Documents collection object, and use the Windows property to obtain a reference to the Windows collection object. The Documents and Windows collection objects provide access to the other objects in the object hierarchy. You can access the currently active document and window objects with the Application object’s ActiveDocument and ActiveWindow properties.
Set the ScreenUpdating property to False to disable screen updating and make your scripts execute more quickly. Turning off screen updating can greatly increase the performance of Automation when you want to perform a number of actions that cause screen redraws.
See Application Object for additional information.
Documents Collection
The Documents collection contains all open documents. The Documents collection provides the means to access plot and worksheet documents. Use the Add method to create new plot or worksheet documents. Surfer provides the pre-defined values srfDocPlot and srfDocWks for specifying the type of document to create:
Set srf = CreateObject("Surfer.Application")
srf.Documents.Add srfDocPlot ' Create a new, blank plot document
srf.Documents.Add srfDocWks ' Create a new, blank worksheet document
The Add method returns a reference to the Document object that was created. New grid documents are not created with the Documents collection Add method. You can create grid files by calling the Application object’s grid-related objects.
Use the Open method to open existing plot, worksheet, and grid files. The Open method returns a reference to the opened document.
Use the Item method to retrieve a reference to an open plot or worksheet document object. When iterating through a collection of documents, the document Type and Index properties can be used to determine the type and position of the document within the collection.
See Documents Collection for additional information.
Windows Collection
The Windows collection provides access to all windows within Surfer. The Windows collection returned by the Application object contains all the windows in the application, including the plot window, the worksheet window, and the grid editor views. To create new Window objects, call a Document object’s NewWindow method.
See Windows Collection for additional information.
PlotDocument Object
A PlotDocument object corresponds to an SRF file. PlotDocument objects are created by the Documents.Add or Documents.Open methods of the Application object. All drawing objects within the document are stored in the Shapes collection. All selected objects are part of the Selection collection.
The PlotDocument provides access to all the drawing and map objects. Use methods and properties in the PlotDocument object to save Surfer files [.SRF], to import and export files, to print, and to change the default line, fill, font, and symbol for a plot.
Use the Shapes, Selection, and Window properties to access the collection objects having the same names. These collection objects provide access to the next layer of objects in the object hierarchy. Use the Shapes collection object to create new drawing and map objects.
See PlotDocument Object for additional information.
WksDocument Object
The WksDocument object represents a worksheet document. WksDocument objects are created by the Documents.Add or Documents.Open methods. Cells within a worksheet are accessed through the Cells, Rows, and Columns methods. The active cell and current selection are accessed through a WksWindow object. You can perform a mathematical transformation on worksheet cells and merge files together with the WksDocument object. The WksRange object can be accessed using the Cells, Rows, Columns, and UsedRange properties.
See WksDocument Object for additional information.
PlotWindow, WksWindow, and GridWindow Objects
It is important to distinguish between windows and documents. Document objects represent a file on disk containing the actual data to be represented. Windows are used to view that data. There can be multiple windows viewing the same document at once.
The Window object encapsulates all the methods and properties associated with a Surfer window. Methods exist to open, close, move and size the window.
When a document is closed, all windows viewing that document are closed as well. The reverse relationship exists as well. When the last window viewing a document is closed the document is closed.
See PlotWindow, WksWindow, and GridWindow Objects for additional information.
Shapes Collection
Within Automation, graphic drawing and map objects are called Shapes. The Shapes collection contains all of the drawing and map objects in a document. This object is also used to create new shapes and add them to the collection. Methods exist to enumerate all the shapes in the collection, add objects to the Selection collection, and create new drawing and map shapes.
One of the most common uses of the Shapes collection is to create new shapes. There is a unique method to create each type of shape. For example, to create a contour map use the AddContourMap method, as in:
Sub Main
Set SurferApp = CreateObject("Surfer.Application")
SurferApp.Visible = True
'Create a new, empty plot document
Set Doc = SurferApp.Documents.Add srfDocPlot
'Get the Shapes collection
Set Shapes = Doc.Shapes
'Create the contour map
Set MapFrame = Shapes.AddContourMap(Demogrid.grd)
End Sub
See Shapes Collection for additional information.
Selection Collection
The Selection collection contains all the properties and methods associated with the collection of selected shapes. The Selection collection defines methods that operate on one or more selected shapes. Most commands within Surfer that require selected objects are part of the Selection collection.
To select a particular shape, set the shape’s Selected property to True. When a Shape object is selected, it is added to the Selection collection. When it is deselected, it is removed from the Selection collection. Note that the shape is neither created nor destroyed by selection operations. It is merely added or removed from the Selection collection.
The Selection collection allows all selected shapes to be enumerated, and contains most methods that operate on multiple objects. This includes moving and sizing one or more shapes; cut, copy, and paste; and overlaying and stacking multiple maps.
See Selection Collection for additional information.
MapFrame Object
You create new maps using the Add<map type>Map methods of the Shapes collection (AddVectorBaseMap, AddReliefMap, AddContourMap, and so forth). These methods return a reference to a MapFrame object - not, as you might expect, a reference to the object of the specific map type that was created. The MapFrame object contains the coordinate system, axes, and all properties common to the maps contained within it. The MapFrame defines the coordinate system and axes for one or more overlays.
You add layers to an existing MapFrame object with the Add<map type>Layer methods (such as AddContourLayer). These methods return a reference to the specific map layer that has been created.
When a new map object is created, usually the MapFrame object is returned rather than the contained overlay. For example, Shapes.AddContourMap returns the containing MapFrame object rather than the contour map overlay. To access the overlay within the MapFrame, use the Overlays collection as in:
Set MapFrame = Shapes.AddContourMap(demogrid.grd)
Set ContourMap = MapFrame.Overlays(1)
Use the Overlays property of the MapFrame to obtain the Overlays collection object. The Overlays collection contains all the individual map objects associated with a map frame. When a new map frame is created, the Overlays collection contains just one map item. To obtain a reference to a newly created map, access the first item of the collection:
Sub Main
Set SurferApp = CreateObject("Surfer.Application")
SurferApp.Visible = True
'Create a blank plot
Set plot = SurferApp.Documents.Add srfDocPlot
'Add a new contour map. This will return a MapFrame object
Set mapframe = plot.Shapes.AddContourMap demogrid.grd
'Get a ContourMap object from the MapFrame
Set contourmap = mapframe.Overlays(1)
End Sub
Use the MapFrame object to set map limits, adjust the three-dimensional view, adjust the scale, and change the size of the map. Access the Axes collection with the MapFrame object’s Axes property. Use the Axes collection object to obtain the individual Axis objects associated with a map. Access the ScaleBars collection through the MapFrame object’s ScaleBars property. Use the ScaleBars collection to add scale bars to a map and to access the ScaleBar objects associated with a map.
See MapFrame Object for additional information.
See Also
Parent and Application Properties