Map statement - MapBasic - 2023

Purpose

Opens a new Map window. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Map From item [ , item ... ] 
	[ Position ( x, y ) [ Units paperunits ] ] 
	[ Width window_width [ Units paperunits ] ] 
	[ Height window_height [ Units paperunits ] ] 
	[ { Min | Max | Floating | Docked | Tabbed | AutoHidden | Hide} ] 
	[ Pen .... ] [ Brush ... ] [ Priority n ] [ Name framename ]
	[ Redraw { On | Off | Suspended } ]
	[ Into { Window layout_win_id } { ID empty_frame_id } ]

Where item is:

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

item is either the name of an open table, or a group layer.

friendly_name for each group layer is required but does not have to be unique, group layers may contain other group layers and/or tables, or be empty (no tables).

paperunits is the name of a paper unit (for example, "in").

Floating docking state makes the window floating.

Docked docking state docks the window to the default position.

Tabbed docking stae makes the window tabbed, in this state it is also callled as a document.

AutoHidden docking state auto hides the window.

x, y specifies the position of the upper left corner of the Map window, in paper units. For details about paper units, see Set Paper Units statement. With the Into Window clause, the position is relative to the upper left corner of the Layout window.

window_width and window_height specify the size of the Map window, in paper units. With the Into Window clause, this represents the width and height of the frame in the Layout window. If a valid width or height is not specified, then a value is generated for the frame.

n is an integer value indicating the Z-Order value of objects (frames) on the Layout window. When creating a clone statement or saving a workspace, MapInfo Pro normalizes the priority of frames to a unique set of values beginning with 1.

framename is a string representing the name for this map embedded in a Layout window. If a name is assigned to a frame in the Layout, it will be written to the WOR. When the Name clause is written to the WOR, the workspace version is updated to version 1500.

layout_win_id is a Layout window's integer window identifier.

empty_frame_id is an emptly Layout window's integer window identifier.

Description

The Map statement opens a new Map window. After you open a Map window, you can modify the window by issuing Set Map statement.

A GroupLayer keyword has been added to create nested group layers. Group layers are a special type of layer that allow users to organize other map layers into groups, similar to the way that folders and subfolders allow users to organize files. Group layers will make it easier to manage maps that have many layers. There are two main benefits to using groups:

1. Organizational benefits - layer lists are more manageable if they are organized into meaningful groups.
2. Efficiency benefits - once layers are organized into groups, subsequent operations such as "turn off all the street layers" can be performed in fewer clicks / fewer steps.

The table name specified must already be open. The table must also be mappable; in other words, the table must be able to have graphic objects associated with the records. The table does not need to actually contain any graphical objects, but the structure of the table must specify that objects may be attached.

The Map statement must specify at least one table, regardless of whether it is part of a group layer or not, since any Map window must contain at least one layer. Optionally, the Map statement can specify multiple table names (separated by commas) to open a multi-layer Map window. The first table name in the Map statement will be drawn last whenever the Map window is redrawn; thus, the first table in the Map statement will always appear on top. Typically, tables with point objects appear earlier in Map statements, and tables with region (boundary) objects appear later in Map statements.

The default size of the resultant Map window is roughly a quarter of the screen size; the default position of the window depends on how many windows are currently on the screen. Optional Position, Height, and Width clauses allow you to control the size and position of the new Map window. The Height and Width clauses dictate the window size, in inches. Note that the Position clause specifies a position relative to the upper left corner of the MapInfo Pro application, not relative to the upper left corner of the screen.

If the Map statement includes the optional Max keyword, the new Map window is maximized, taking up all of the screen space available to MapInfo Pro. Conversely, if the Map statement includes the Min keyword, the window is minimized immediately.

Each Map window can have its own projection. MapInfo Pro decides a Map window's initial projection based on the native projection of the first table mapped. A user can change a map's projection by choosing the Map Options command on the MAP tab. A MapBasic program can change the projection by issuing a Set Map statement.

Brush is a valid Brush clause. Only Solid brushes are allowed. While values other than solid are allowed as input without error, the type is always forced to solid. This clause is used only to provide the background color for the frame.

Pen is a valid Pen clause. This clause is designed to turn on (solid) or off (hollow) and set the color of the border of the frame.

The optional Redraw clause has three options, On, Off and Suspended. These options are the same as the Redraw options for the Set Map statement. This provides a way to create a map window that is initially in the specified redraw mode. Redraw disables or enables the automatic redrawing of the Map window. If you issue a 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). The Suspended keyword will draw a visual cue suggesting the state of map redraws, on the map window.

The Into Window clause creates a new frame within an existing Layout window. If no layout_win_id is specified, the new frame is added to the topmost Layout window.

Use the ID clause to insert open tables into an empty layout frame. A default view of the map displays, and the frame properties already set for the empty frame are retained (pen, brush, position, size, name, and z-order). An error results when the:

• From Window ID is not a map or browser: 1696 "Error: Expecting Map or Browser Window."
• Frame ID is not empty: 1698 "Layout frame ^0 must be empty."
• From Window does not close: 1697 "Unable to clone Window into empty frame."
• Map legends does not clone: 1708 "Unable to clone Legends for Map frame."

The following example creates a map for the open tables called World and World_Cities and inserts it into the empty frame in the Layout window.

Map From World, World_Cities Into Window layout_win_id ID empty_frame_id

To reuse a frame after it has been filled with content it needs to be emptied, see the Set Designer Frame statement. This leaves behind an empty frame of the same size and position as the content it just contained, and retains the name currently assigned to it.

Examples

The following example opens a Map window three inches wide by two inches high, inset one inch from the upper left corner of the MapInfo Pro application. The map has two layers.

Open Table "world"
Open Table "cust1994" As customers
Map from customers, world
	Position (1,1) Width 3 Height 2

The following example opens a Map window that has group layers, some of which are nested (assume all tables have been opened first).

Map From 
	GroupLayer (
		"Grid", 
		GroupLayer ("Tropics", Tropic_Of_Capricorn, Tropic_Of_Cancer),
		Wgrid15
	),
	GroupLayer (
		"World Places", WorldPlaces, WorldPlacesMajor, WorldPlaces_Capitals
	), 
	Airports,
	GroupLayer ("World Boundaries", world_Border), 
	GroupLayer (
		"Roads", Roads, US_Primary_Roads, US_Secondary_Roads, US_Major_Roads
	),
	GroupLayer ("Countries" Countries_small, Countries_large), 
	Ocean

Groups layers have unique IDs like layers. Layer IDs may be numeric or table names. When numeric, they represent the order (reverse draw order) of the layer in the list from the top down. Group layers have numeric IDs that are part of a different sequence, but will also increase sequentially from the top down. In the example above the group layer and layer IDs would be as follows:

See Also:

Add Map statement, Set Designer Frame statement, Remove Map statement, Set Map statement, Set Shade statement, Shade statement