Add Map statement - MapBasic - 2023

Purpose

Adds one or more graphic layers, or a group layer, to a Map window. You can also select a destination group layer and/or position to insert the new layers.

Syntax 1

Add Map 
	[ Window window_id ] [ Auto ]  
	Layer table [ , table  [ Animate ] ...  ]
	[ [ DestGroupLayer group_id ]  Position position ]

window_id is the window identifier of a Map window.

table is the name of a mappable open table to add to a Map window.

group_id is the identification for a group layer, either as a integer value (the group number) or as a string value (the group name).

position is the 1-based index within the destination group where to insert the new list of layers.

Syntax 2

Add Map 
	[ Window window_id ] [ Auto ]  
	GroupLayer ( "friendly_name" [ , item ... ] )
	[ [ DestGroupLayer group_id ]  Position position ]

where:

item = table | [ GroupLayer ( "friendly_name" [ , item ... ])

Description

The Add Map statement adds one or more open tables, or a group layer, to a Map window, but not both within the same statement. The group layer may contain any number of nested group layers. MapInfo Pro then automatically redraws the Map window, unless you have suppressed redraws through a Set Event Processing statement Off statement or Set Map statement Redraw Off statement.

The window_id parameter is an integer window identifier representing an open Map window; you can obtain a window identifier by calling the FrontWindow() function and WindowID() function. If the Add Map statement does not specify a window_id value, the statement affects the topmost Map window.

If you include the optional Auto keyword, MapInfo Pro tries to automatically position the map layer, or group layers at an appropriate place in the set of layers. A raster table or a map of region objects would be placed closer to the bottom of the map, while a map of point objects would be placed on top.

If you omit the Auto keyword, the specified table becomes the topmost layer in the window; in other words, when the map is redrawn, the new layer, or group layers will be drawn last. You can then use the Set Map statement to alter the order of layers in the Map window.

If a DestGroupLayer is specified the Auto keyword will be ignored and the list of layers, or the group layer will be inserted into the layer list, in the group specified, at the position specified. A group id of 0 is the top level list. If the DestGroupLayer is omitted the group ID defaults to 0.

The position is the 1-based index within the destination group of where to insert the new list of layers. If the position is omitted it is assumed to be the first position in the group (position = 1). If the position given exceeds the number of items in the destination group, the new layers and/or groups will be inserted at the end of the destination group.

Layer and group IDs may be the numeric ID or name. Group IDs range from 0 to the total number of groups in the list.

Adding Layers of Different Projections

If the layer added is a raster table, and the map does not already contain any raster map layers, the map adopts the coordinate system and projection of the raster image. If a Map window contains two or more raster layers, the window dynamically changes its projection, depending on which image occupies more of the window at the time.

If raster re-projection is turned on, then MapInfo Pro retains the coordinate system of the map even if you add a raster table to the map.

If the layer added is not a raster table, MapInfo Pro continues to display the Map window using whatever coordinate system and projection were used before the Add Map statement, even if the table specified is stored with a different native projection or coordinate system. When a table's native projection differs from the projection of the Map window, MapInfo Pro converts the table coordinates "on the fly" so that the entire Map window appears in the same projection.

Using Animation Layers to Speed Up Map Redraws

If the Add Map statement includes the Animate keyword, the added layer becomes a special layer known as the animation layer. When an object in the animation layer is moved, the Map window redraws very quickly, because MapInfo Pro only redraws the one animation layer.

For an example of animation layers, see the sample program ANIMATOR.MB.

The animation layer is useful in real-time applications, where map features are updated frequently. For example, you can develop a fleet-management application that represents each vehicle as a point object. You can receive current vehicle coordinates by using GPS (Global Positioning Satellite) technology, and then update the point objects to show the current vehicle locations on the map. In this type of application, where map objects are constantly changing, the map redraws much more quickly if the objects being updated are stored in the animation layer instead of a conventional layer.

The following example opens a table (Vehicles) and makes the table an animation layer:

Open Table "vehicles" Interactive 
Add Map Layer vehicles Animate

In general, the last table to be followed by the Animate keyword will be the animation layer. Only one layer at a time can be the Animation layer.

To terminate the animation layer processing, issue a Remove Map statement Layer Animate statement.

Animation layers have special restrictions. For example, users cannot use the Info tool to click on objects in an animation layer. Also, each Map window can have only one animation layer. For more information about animation layers, see the MapBasic User's Guide.

Example

Open Table "world"
Map From world
Open Table "cust1992" As customers
Open Table "lead1992" As leads
Add Map Auto Layer customers, leads

Add a group layer example:

Open Table world
Open Table worldcap
Add Map Auto GroupLayer("new group", worldcap, world)
Open Table ocean
Add Map Layer ocean DestGrouplayer "new group" position 3

See Also:

Map statement, Remove Map statement, Set Map statement