Set Layout statement - MapBasic - 2023

Purpose

Modifies an existing layout. You can use this statement with a classic Layout window and with a Layout window. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Set Layout
	[ Window window_id ] 
	[ Page page_number ] 
	[ Center ( center_x, center_y ) ] 
	[ Extents { To Fit | ( pages_across , pages_down ) } ] 
	[ Pagebreaks { On | Off } ] 
	[ Frame Contents { Active | On | Off } ]
	[ Ruler { On | Off } ] 
	[ Zoom { To Fit | zoom_percent } ]
	[ { Objects Alpha alpha_value } | 
		{ Objects Translucency translucency_percent } ] 
	[ Selection { All | Clear | [ Add | Remove ] Frame ID frame_id, frame_id, frame_id,… } ]
	[ Grid [ Visibility { On | Off } ]
		[ Snap { On | Off } ]
		[ Size distance { Units paper_unit  } ] ]
	[ Smart Guides { On | Off } ]

window_id is the window identifier of a layout window.

page_number is the number of the page to go to (1 or greater).

center_x is the horizontal layout position currently at the middle of the layout window.

center_y is the vertical layout position currently at the middle of the layout window.

pages_across is the number of pages (one or more) horizontally that the layout should span.

pages_down is the number of pages (one or more) vertically that the layout should span.

zoom_percent is a percentage indicating the layout window's size relative to the actual page.

alpha_value is an integer value representing the alpha channel value for translucency. Values range from 0-255 where 0 is completely transparent and 255 is completely opaque. Values between 0-255 make the objects in the layout display translucently.

translucency_percent is an integer value representing the percentage of translucency for the objects in a layout. Values range between 0-100. 0 is completely opaque. 100 is completely transparent.

frame_id is the ID of the frame(s) on the layout. For example, three frames on a layout would have successive IDs, 1, 2, and 3. If the ID is out of bounds an error is generated, "Invalid frame id n", where n is the ID parsed from the command. If a duplicate ID is parsed an error is generated, "Duplicate frame id n", where n is the ID parsed from the command. If the frame is already selected, no error is generated.

distance is the size or spacing of the grid lines on a Layout window.

paper_unit is an optional value and it is the unit in which the distance is specified. The paper_unit is the standard MapInfo Pro paper unit abbreviation in quotes (For example, "in"). If the value is not specified, it defaults to the current paper unit. If the unit specified is not a paper unit, the statement will produce an error.

Description

The Set Layout statement controls the settings of an existing layout window. It works with both classic Layout windows and with Layout windows. However, Layout windows ignore all clauses except for Center, Zoom zoom_percent and Selection. The Zoom To Fit syntax works with classic Layout windows only. For background on classic Layout windows, see Working with Classic Layout Windows.

If no window_id is specified, the statement affects the topmost layout window. This statement allows a MapBasic program to control those options that a user would set through MapInfo Pro's Layout menu.

Use the Page clause to set the current page in a multi-page Layout window. An invalid page number generates an ERR_FCN_ARG_RANGE (644) error. Valid numbers are 1 or higher and the page must exist.

The Center clause specifies the location on the layout that is currently at the center of the layout window.

The Extents clause controls how many pages (for example, how many sheets of paper) will constitute the page layout. The following clause:

Set Layout Extents To Fit

configures the layout to include however many pages are needed to ensure that all objects on the layout will print. Alternately, the Extents clause can specify how many pages wide or tall the page layout should be. For example, the following statement would make the page layout three pages wide by two pages tall:

Set Layout Extents (3, 2)

If the layout consists of more than one sheet of paper, the Pagebreaks clause controls whether the layout window displays page breaks. When page breaks are on (the default), MapInfo Pro displays dotted lines to indicate the edges of the pages.

The Frame Contents clause controls when and whether MapInfo Pro refreshes the contents of the layout frames. A page layout typically contains one or more frame objects; each frame can display the contents of an existing MapInfo Pro window (for example, a frame can display a Map window). As you change the window(s) on which the layout is based, you may or may not want MapInfo Pro to take the time to redraw the layout window. Some users want the layout window to constantly show the current contents of the client window(s); however, since layout window redraws take time, some users might want the layout window to redraw only when it is the active window.

The following statement tells MapInfo Pro to always redraw the layout window, when necessary, to reflect changes in the client window(s):

Set Layout Frame Contents On

The following statement tells MapInfo Pro to only redraw the layout window when it is the active window:

Set Layout Frame Contents Active 

The following statement tells MapInfo Pro to never redraw the layout window:

Set Layout Frame Contents Off

When Frame Contents are set Off, each frame appears as a plain rectangle with a simple description (for example, "World Map").

The Ruler clause controls whether MapInfo Pro displays a ruler along the top and left edges of the layout window. By default, Ruler is On.

The Zoom clause specifies the magnification factor of the page layout; in other words, it enlarges or reduces the window's view of the layout. For example, the following statement specifies a zoom setting of fifty percent:

Set Layout Zoom 50.0

When a page layout is displayed at fifty percent, that means that an actual sheet of paper is twice as wide and twice as high as it is represented on-screen (in the layout window). Note that the page layout can show extreme close-ups, for the sake of allowing accurate detail work. Accordingly, a layout window displayed at 200 percent will show a magnification of the page. The Zoom clause can specify a zoom value anywhere from 6.25% to 800% for classic Layout windows, or 5% to 400% for Layout windows . The Zoom clause does not need to specify a specific percentage. The following statement tells MapInfo Pro to set the zoom level so that the entire page layout will appear in the layout window at one time:

Set Layout Zoom To Fit

The Selection clause controls the selection of frames in a Layout window only. If the window_id refers to a legacy layout, the Selection clause will be compiled, but the following runtime error will occur: "Error: Expecting Layout Window".

• All, selects all frames in the layout. No error is generated if all frames are already selected, or there are no frames in the Layout.

  Set Layout Selection All

• Clear deselects all frames in the layout. No error is generated if no frames are currently selected, or there are no frames in the Layout.

  Set Layout Selection Clear

• Add is an optional token before the list of frame IDs. If Add is included, then the frames listed are selected and added to the current frame selection.Without it, any frames previously selected are first deselected, and the list of frame IDs listed in the clause becomes the new collection of selected frames. No error is generated if a frame ID referenced in the list is already selected.

  Set Layout Selection Add Frame ID 4 // adds frame with ID 4 to current selection

• Remove is an optional token before list of frame IDs. The IDs listed in the clause are removed from the current selection. No error is generated if a frame ID referenced in the list is not currently selected. It cannot be used in conjunction with Add.

  Set Layout Selection Remove Frame ID 3 // frame with ID 3 is removed from the current selection

The Grid clause controls the grid lines in a layout window.

The Smart Guides clause, by default is not enabled. The Smart Guides clause controls whether smart guide behavior is enabled or not. If the Guides token is missing there will be a syntax error. If the On or Off tokens are missing, the default is On. Smart guides are used to align an edge of a frame being moved to the edges of other non-selected frames on the current page, or to the page's current margins.

To change the width, height, or position of a layout window, use the Set Window statement.

Examples

The following makes the first page (1) the current page in a Layout window that has multiple pages.

Set Layout  Window FrontWindow( )  Page 1 

The following ensures that all objects on a layout will print. It also hides rules in the classic Layout window.

Set Layout
	Zoom To Fit Extents To Fit
	Ruler Off
	Frame Contents On

The following statements zoom a Layout window to 200% and recenters the layout.

Set CoordSys Layout Units “in” 
Set Layout Window FrontWindow() Center (4.25, 5.5) Zoom 200

See Also:

Alter Object statement, Create Frame statement, Layout statement, Run Menu Command statement, Set Window statement