MapFrame Object

You create new maps using the Add<map type> methods of the Shapes collection (AddBasemap, 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.

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(GridFileName:=SurferApp.Path+"\Samples\demogrid.grd")

Set ContourLayer = 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

 

Dim SurferApp As Object

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(GridFileName:=SurferApp.Path+"\Samples\demogrid.grd")

 

'Get a ContourLayer object from the MapFrame

Set ContourLayer = MapFrame.Overlays(1)

'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(GridFileName:=SurferApp.Path+\Samples\demogrid.grd)

 

'Get a ContourLayer object from the MapFrame

Set ContourLayer = 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.

Derived from: Shape object (All methods and properties of Shape apply to this object.)

The following table provides the properties of the MapFrame object.

Property	Description
AmbientLightColor	Returns/sets the ambient light color as an RGB value.
Axes	Returns the axes collection. It is a read-only property.
BackgroundFill	Returns the background fill format. It is a read-only property.
BackgroundLine	Returns the background line format. It is a read-only property.
ColorModulation	Returns/sets the color modulation for OpenGL maps.
CoordinateSystem	Returns/sets the coordinate system for the map.
DiffuseLightColor	Returns/sets the diffuse light color as an RGB value.
LightAzimuth	Returns/sets the light source azimuth angle for OpenGL maps.
LightModel	Returns/sets the light model for OpenGL maps.
LightZenith	Returns/sets the light source zenith angle for OpenGL maps.
OverlayResolution	Returns/sets the texture map resolution for OpenGL maps.
Overlays	Returns the overlays collection. It is a read-only property.
Profiles	Returns the profiles collection. It is a read-only property.
ResampleMethod	Returns/sets the texture map resampling method for OpenGL maps.
ScaleBars	Returns the Scalebars collection. It is a read-only property.
ScalingRatio	Returns/sets the XY scaling as long as the ScalingRatio is greater than zero and as long as the ratio will not result in a map larger than the PlotSize.
SpecularLightColor	Returns/sets the specular light color as an RGB value.
ViewDistance	Returns/sets the 3D eye distance as a percent.
ViewFOV	Returns/sets the 3D field of view in degrees.
ViewProjection	Returns/sets the 3D projection type.
ViewRotation	Returns/sets the 3D rotation in degrees.
ViewTilt	Returns/sets the 3D tilt in degrees.
xLength	Returns/sets the X scale length.
xMapPerPU	Returns/sets the X scale factor (map units per page unit).
xMax	Returns the maximum map limit in the X direction. It is a read-only property.
xMin	Returns the minimum map limit in the X direction. It is a read-only property.
yLength	Returns/sets the Y scale length.
yMapPerPU	Returns/sets the Y scale factor (map units per page unit).
yMax	Returns the maximum map limit in the Y direction. It is a read-only property.
yMin	Returns the minimum map limit in the Y direction. It is a read-only property.
zLength	Returns/sets the Z scale length.
zMapPerPU	Returns/sets the Z scale factor (map units per page unit).

The following table provides the methods of the MapFrame object:

Method	Description
SetLimits	Set the limits of the map in map units.
SetLimitsToData	Set the limits of the map to the extents of all data.

Example

The following script demonstrates how the MapFrame object is used in reference to the Shapes collection.

Sub Main

 

'Declares SurferApp as an object

Dim SurferApp As Object

 

'Creates an instance of the Surfer Application object and assigns it to

'the variable named "SurferApp"

Set SurferApp = CreateObject("Surfer.Application")

 

'Makes Surfer visible

SurferApp.Visible = True

 

'Declares Plot as an object

Dim Plot As Object

 

'Creates a plot document in Surfer and assigns it to the variable named

'"Plot"

Set Plot = SurferApp.Documents.Add(srfDocPlot)

 

'Declares Shapes as an object

Dim Shapes As Object

 

'Assigns the Shapes collection to the variable named "Shapes"

Set Shapes = Plot.Shapes

 

'Declares MapFrame as an object

Dim MapFrame As Object

 

'Creates a contour map and assigns the map coordinate system to the

'variable named "MapFrame"

Set MapFrame = Shapes.AddContourMap(SurferApp.Path+"\Samples\demogrid.grd")

 

End Sub