Map Scales and Scopes

In standard Maptitude you use commands and tools to set the center and scale of the map. With GISDK, you set the map scale and center using a scope. A scope is a compound variable with four parts that defines the portion of the world covered by a map:

Part	Contents
Center	A coord (another compound variable) containing the longitude and latitude of the the center of the area
Width	The horizontal extent of the area in world units (see SetMapUnits())
Height	The vertical extent of the area in world units
Projection	An array containing the projection name and other parameters

The following GISDK functions are used to create and use scopes:

GISDK Function	Summary
ClickEllipseScope()	Awaits user input from the system pointer, accepts an ellipse, and returns a scope
ClickRectScope()	Awaits user input from the system pointer, accepts a rectangle whose center is a valid world point, and returns a scope
ClickScope()	Awaits user input from the system pointer, accepts a rectangle, and returns a scope
ConstructSnapshot()	Converts a customized image file into a map snapshot
GetArrayScope()	Returns the scope of an array of coordinates
GetDBInfo()	Gets summary information about a geographic file
GetImageFileInfo()	Gets information about a raster image file
GetLayerScope()	Gets the scope of a layer
GetMapCorners()	Gets coordinates at the four corners of a map
GetMapDefaultScope()	Gets the default scope of a map
GetMapScope()	Gets the scope of a map
GetMapWindowScope()	Gets the scope of a map using the current window width and height
GetProjectionScope()	Returns a valid scope for a particular projection
GetRecordScope()	Gets the scope of a given record on the current layer
GetScopeCorners()	Gets coordinates at the four corners of a given scope
GetScopeRect()	Gets an array of two coordinates that define the rectangle of a scope
GetSetScope()	Gets the scope of the features in a selection set
GetViewScope()	Gets the scope of a view
Scope()	Creates a scope
SetMapDefaultScope()	Sets the default scope of a map
SetMapScope()	Sets the area covered by a map

The following functions are used to get information that can be used to create a scope for geographic file formats that can be displayed directly:

GISDK Function	Summary
GetArcViewShapeInfo()	Gets information about an Esri (ArcView) Shapefile
GetMITABInfo()	Collects summary information on the contents of a MapInfo TAB file
GetODBCLayerInfo()	Gets information about an ODBC layer
GetSDOInfo()	Gets information about an Oracle Spatial table

When you create a map using CreateMap(), you assign a scope to the map so that Maptitude knows which portion of the world the map covers. This becomes the default scope for the map. You can then use SetMapScope() to change the area covered by the map. You can also update the default scope of a map and retrieve this default scope using SetMapDefaultScope() and GetMapDefaultScope().

The following example creates a new map that shows an entire geographic file, and then zooms in on a particular map feature:

// First, get the scope of the Connecticut Sales Region geographic file

folder = RunMacro("G30 Tutorial Folder")

db = folder + "ctsales.cdf"

db_info = GetDBInfo(db)

db_scope = db_info[1]

// Now create a map...
map1 = CreateMap("My First Map", {	// the name of the map
	{"Scope", db_scope},
// the default scope
	{"Menu", default_menus}})
// what menus are attached to the window
AddLayer(map1, "Regions", db, "Regions")	// Add the region layer to the map

RedrawMap(map1)	// Draw the map at its initial scale...

qry = "Select where Name = 'Fairfield'"	// Select a particular sales region....
SelectByQuery("Selection", "several", qry)

set_scope = GetSetScope("Selection")	// Get the scope of the record(s) in the
	// selection set
SetMapScope(map1, set_scope)
RedrawMap(map1)	// Redraw the map once again

SetMapScope(map1, GetMapDefaultScope(map1))	// Restore the scope to the
	// original value
RedrawMap(map1)

You can also control the scale and center of a map using the following GISDK functions:

GISDK Function	Summary
CenterMap()	Centers a map at a particular location
ClickDragAndShow()	Allows the user to pan a map by dragging it to a new position
GetScale()	Gets the scale of a map
SetMapPrevious()	Sets the area covered by a map to be that shown before the last change in scale or scope
SetMapRedraw()	Controls whether map windows redraw automatically
SetScale()	Sets the scale of a map
ZoomAndCenterMap()	Changes the scale and center of a map
ZoomMap()	Changes the scale of a map

GISDK provides additional functions for comparing, merging, and testing the overlap of scopes and points. These GISDK functions are as follows:

GISDK Function	Summary
CoordInScope()	Checks to see if a coordinate is in a given scope
ScopeInScope()	Checks to see if one scope is completely contained within another
ScopeIntersect()	Creates a scope that is the intersection of the input scopes
ScopeOnScope()	Checks to see if one scope overlaps another
ScopeUnion()	Creates a scope that encompasses the entire area covered by two input scopes

Note that when you set the scope of a map, Maptitude makes sure that the entire scope you requested is shown on the screen. The exact scale that results depends upon the shape of the map window. For example, if your map window is very short and wide, but your scope has equal width and height, Maptitude automatically centers the scope in the window, and fills in the left and right sides of the map with geographic data that are outside the scope. The GetMapScope() GISDK function returns the last scope you set, regardless of the shape of the map window. Use GetMapWindowScope() when you want to determine the actual scope that is displayed in the map window.