Changing the Behavior of the Entire Map - MapBasic - 2023

MapInfo MapBasic Reference
Product type
Software
Portfolio
Locate
Product family
MapInfo
Product
MapInfo > MapBasic
Version
2023
Language
English
Product name
MapBasic
Title
MapInfo MapBasic Reference
First publish date
1985
Last updated
2023-09-12
Published on
2023-09-12T16:32:32.686312

The following clauses affect the behavior of the map, such as units, clipping object behavior, and redraw behavior.

Syntax

Set Map 
	[ Window window_id ] 
	[ Time [ PROCESSING_CLAUSE ] | [ TIME_CLAUSE ] ]
	[ Clipping [ Object clipper ] [ { Off | On } ]  
		[Using { Display { PolyObj | All } | Overlay } ] ]
	[ Preserve { Scale | Zoom } ]
	[ Area Units area_unit ]
	[ Distance Units dist_unit ]
	[ Display { Scale [ Cartographic ] | Position | Zoom } ]
	[ Redraw { On | Off | Suspended } ] 
	[ Move Nodes { value | Default } ]

window_id is the integer window identifier of a Map window.

PROCESSING_CLAUSE suspends or restores time processing. When time processing is Off, all time settings changed are remembered and applied when restored. This allows time properties to be set individually without waiting for a possibly expensive recalculation. This happens whether time is enabled or not. 
Processing { On | Off }
TIME_CLAUSE
[ Enable_Clause ] [ Current_Clause ] [ Extents_Clause ] [ Interval_Clause ]  
	[ Step_Clause ] [ Snap_Clause ] [ Playback_Clause ] [ Format_Clause ]
  • Enable_Clause turns the display time filtering On or Off for any time enabled layers in the map. The current time period is used.
     [ On | Off ]
  • Current_Clause sets the current time period. If the value is less than one, an error is thrown. If map time is on, then the map’s display is updated to reflect the current time period.
    Current [ integerExpr [ Next | Prev ] ]
    • Next advances to next time period that is non-empty (has some data) starting from integerExpr.
    • Prev moves to the previous time period that is non-empty (has some data) starting from integerExpr.
  • Extents_Clause sets the beginning and ending time of the time series. These are used when calculating time periods.
    Extents [ Begin time_value End time_value ] | 
	[ Auto ] | [ Layer timeLayerIndex ]
    • Auto: The map extents are automatically calculated from all layers.
    • timeLayerIndex: The map extents are taken from the Nth time layer. timeLayerIndex is the index of time layer not the layer id.
  • Interval_Clause
    Interval Count time_unit [ Begin { Inclusive | Exclusive | Off } ] 
	[ End { Inclusive | Exclusive | Off } ]
    • time_unit is the number of time units in each time period. For example, 2 “week” and must be positive.

      When constructing the time query for each time based layer in the map, Interval is used to determine how much data should be queried in each time period. Fro Example, for a 1 month period: Where timecol1 >= "1/1/2019" and timecol1 < "2/1/2019".

    • Inclusive: Begin Inclusive is >=, End Inclusive is <=.
    • Exclusive: Begin Exclusive is >, End Exclusive is <.
    • Off : Begin Off means to not include a start condition. End Off means to not include an end condition.
  • Step_Clause
    Step Count time_unit
    time_unit is the number of time units to advance the start time of the next period from the start time of the previous period. For example, 1 “week” and it must be positive.
  • Snap_Clause
    { On time_unit | Off }
    • If snap is On, it is used to snap the extent begin to the start of the time unit and to snap the extent end to the end of the time unit. For example, 2/4/1996 -3/6/2006 snapped to “month” becomes 2/1/1996 - 3/31/2006
  • Playback_Clause
    Playback [ Repeat ] [ Reverse ] [ { Forward | Backward } ] [ Speed doubleValue ]
    • doubleValue is a positive value in milliseconds.
  • Format_Clause specifies the datetime format for representing time period.
    { Format [ Auto ] | [ String format [ Type Begin | End| Both ] ] }

clipper is an Object expression; only the portion of the map within the object will display. See the description in the Clipping section for more information.

area_unit is a string representing the name of an area unit used to display area calculations (for example, "sq mi" for square miles, "sq km" for square kilometers; see Set Area Units statement for a list of unit names). For example:

	Set Map Area Units "sq km"

dist_unit is a string expression, specifying the units for the map (such as "mi" for miles, "m" for meters; see Set Distance Units statement for a list of available unit names). This is an optional parameter. If not present, the distance units from the table's coordinate system are used.

value can be 0 or 1. If the value is 0, duplicate nodes are not moved. If the value is 1, any duplicate nodes within the same layer will be moved.

Description

Time sets the time related properties of the map.

Set Map Window FrontWindow() Time Off Current 1 Extents Begin "20000102000000000" 
	End "20180101000000000" Interval 1 "Year" Step 1 "Year" Snap Off Playback Forward 
	Speed 2000 

Set Map Window FrontWindow() Time On Extents Begin "20000102000000000" 
	End "20180101000000000" Interval 1 "Year" Step 6 "Month" Snap On "" 
	Playback Forward Speed 500
Clipping sets a clipping object for the Map window; corresponds to MapInfo Pro's Set Clip Region command (on the SPATIAL tab). Once a clipping region is set, enable or disable clipping by specifying Clipping On or Clipping Off. 
	Set Map Clipping Object obj_variable_name

There are three modes that can be used for Clipping. Using the Overlay mode will use the MapInfo Pro Erase Outside functionality to produce the clipping. Polylines and Regions will be clipped at the Region boundary. Points and Labels will be completely displayed only if the point or label point lie inside the Region. Text is always displayed and never clipped. Styles for all objects are never clipped. Using the Display All mode, the Windows display will provide the clip region functionality. All objects (including points, labels, and text) will be clipped at the Region boundary. All styles will be clipped at the region boundary. This is the default mode.

Using the Display PolyObj mode the Windows display will provide the clip region functionality for Polylines and Regions only. Styles for Polylines and Regions will be clipped at the region boundary. Points and Labels will be completely displayed only if the point or label point lie inside the Region. Text is always displayed and never clipped. Styles for points, labels and text are never clipped.

In general, the Windows display functionality found in Display All and Display PolyObj provides better performance than the Overlay functionality. For example:

	Set Map Clipping Object obj_variable_name Using Display All

Display dictates what type of information should appear on the status bar when the Map window is active: Display Scale displays the current scale in distance units, Display Scale Cartographic displays the current scale in paper units (shown as a value of 1 to a scale value, such as 1:10000), Display Position displays the position of the cursor (for example, decimal degrees of longitude/latitude), and Display Zoom displays the current zoom (the width of the area displayed). For details about paper units, see Set Paper Units statement.

	Set Map Display Position

Preserve controls how the Map window behaves when the user re-sizes the window. If you specify Preserve Zoom then MapInfo Pro redraws the entire Map window whenever the user re-sizes the window. If you specify Preserve Scale then MapInfo Pro only redraws the portion of the window that needs to be redrawn. These options correspond to settings in MapInfo Pro's Map Preferences dialog box (on the PRO tab, click Options, and then Map Window).

Redraw disables or enables the automatic redrawing of the Map window. If you issue a Set Map Redraw Off statement, subsequent statements can affect the map (for example, Set Map, Add Map Layer, Remove Map Layer) without causing MapInfo Pro to redraw the Map window. After making all necessary changes to the Map window, issue a Set Map Redraw On statement to restore automatic redrawing (at which time, MapInfo Pro will redraw the map once to show all changes).

Note: Some actions, such as panning and zooming, can cause MapInfo Pro to redraw a Map window even after you specify Redraw Off. If you find that the Redraw Off syntax does not prevent window redraws, you may want to use the Set Event Processing Off statement.

Redraw has three options, On, Off and Suspended. The Suspended keyword will draw a visual cue suggesting the state of map redraws, on the map window (see the following example). You can put the maps into a suspended state by clicking a button at the bottom of the Layer Control window.

Set Map Redraw Suspended

Move Nodes can be 0 or 1. If the value is 0, duplicate nodes are not moved. If the value is 1, any duplicate nodes within the same layer will be moved. If a Move Node value is specified, that window is considered to be using a custom value. To return to using the default (from the mapper preference), specify Move Nodes Default.

Once Set Map Move Nodes value has been used, that map has a custom setting. If a Map window has a custom setting, the Map window preference will not be used. The Map window preference will apply to new Map windows and any non-customized Map windows. The setting for an existing Map window can be customized by using the Set Map Move Nodes value MapBasic statement.

Example

The following program opens two tables, opens a Map window to show both tables, and then performs a Set Map statement to make changes to the Map window: 

Open Table "world"
Open Table "cust1993" As customers
Map From customers, world

Set Map 
	Center (-100, 40) 'center map over mid-USA
	Zoom 4000 Units "mi" 'show entire USA
	Preserve Zoom 'preserve zoom when resizing 
	Display Position 'show lat/long on status bar