Create Frame statement - MapBasic - 2023

Purpose

Creates a new frame in a layout. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Create Frame 
	[ Into { Window window_id | Variable var_name } ] 
	( x1, y1 ) ( x2, y2 ) 
	[ Pen... ] 
	[ Brush... ]
	[ Priority n ]
	[ Name framename ]
	[ Title title ] 
	[ From Window contents_win_id ] 
	[ FillFrame { On | Off } ] 
	[ Metadata SetKey keyname To keyvalue ]

window_id is an integer window identifier.

var_name is the name of an Object variable.

x1, y1 specifies one corner of the new frame to create.

x2, y2 specifies the other corner.

Pen is a valid Pen clause to specify a line style.

Brush is a valid Brush clause to specify fill style.

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 image frame in a layout designer. If a name is assigned to a frame in the Layout window, it will be written to the WOR. When the Name clause is written to the WOR, the workspace version is updated to version 1500.

title is a string identifying the frame contents (for example, "WORLD Map"); not needed if the From Window clause is used.

contents_win_id is an integer window identifier indicating which window will appear in the frame.

keyname is a string representing the name of a metadata key.

keyvalue is a string representing the value to assign to the key.

Description

The Create Frame statement creates a new frame within an existing layout window. This statement works with both Layout windows and the older (classic) Layout windows. If no window_id is specified, the new frame is added to the topmost layout window.

If you use non-Earth coordinate (X, Y) values to position the frame, an error displays. Before creating objects on a layout, you must issue a Set CoordSys Layout statement.

The window_id parameter specifies which layout window to add a new frame to and the contents_win_id parameter specifies which window will appear in the new frame. To obtain a window identifier, call the FrontWindow() function immediately after opening a window, or call the WindowID() function at any time after the window's creation.

Frames in a Layout window cannot be in a negative position past the top or past the left edge of the layout. MapInfo Pro adjusts a negative X or Y value to make it zero (0) when placing the frame. (The classic Layout window does allow negative position values.)

The Pen clause dictates what line style will be used to display the frame, and the Brush clause dictates the fill style used to fill the frame window.

The Title clause provides an alternate syntax for specifying which window appears in the frame. For example, to identify a Map window that displays the table WORLD, the Title clause should read Title "WORLD Map". If the title string does not refer to an existing window, or if title is an empty string (""), the frame will be empty. If you specify both the Title clause and the From Window clause, the latter clause takes effect.

Use the From Window clause to specify which window should appear inside the frame. For example, to make a Map window appear inside the frame, specify From Window id_map (where id_map is an integer variable containing the Map window identifier). A window must already be open before you can create a frame containing the window.

The FillFrame clause controls how the window fills the frame. If you specify FillFrame On, the entire frame is filled with an image of the window. If you specify FillFrame Off (or if you omit the FillFrame clause entirely), the aspect ratio of the window affects the appearance of the frame; in other words, re-sizing a Map window to be tall and thin causes the frame to appear tall and thin.

Between sessions, MapInfo Pro preserves layout window settings by storing Create Frame statements in the workspace file. To see an example of the Create Frame statement, create a layout, save the workspace, and examine the workspace file in a text editor.

The Metadata SetKey clause helps to manage the metadata stored in the layout frame.

Example

The following examples show how to create a frame for a Map window's thematic legend, or Cartographic Legend window.

Theme Legend windows are a special case. To create a frame for a Theme Legend window, you must use the Title clause instead of the From Window clause.

Dim i_layout_id, i_map_id As Integer 
Dim s_title As String 

' here, you would store the Map window's ID in i_map_id,
' and store the Layout window's ID in i_layout_id.
' To obtain an ID, call FrontWindow() or WindowID(). 

s_title = "Theme Legend of " + WindowInfo(i_map_id, WIN_INFO_NAME)
Set CoordSys Layout Units "in" 
Create Frame 
	Into Window i_layout_id
	(1,2) (4, 5)
	Title s_title 

To create a frame for a Map window's cartographic legend, you should use the From Window clause since there may be more than one cartographic legend window per map.

Dim i_cartlgnd_id As Integer

' here, you would store the Cartographic Legend window's ID 
' in i_cartlgnd _id,
' To obtain an ID, call FrontWindow() or WindowID(). 

Create Frame 
	Into Window i_layout_id
	(1,2) (4, 5)
	From Window i_cartlgnd_id

See Also: