Alter Designer Frame statement - MapBasic - 2023

Purpose

The Alter Designer Frame statement changes a frame's position, title, subtitle, and style for an existing legend created with the Create Designer Legend statement. (To change the size, position or title of the Legend window, use the Set Window statement.) This statement does not work with Thematic Map frames.You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Alter Designer Frame
[ Window legend_or_layout_window_id ]
Id { frame_id }
	[ Position ( x, y ) [ Units paper_units ] ] 
	[ Title [ frame_title ] [ Font... ] ]
	[ SubTitle [ frame_subtitle ] [ Font... ] ]
	[ Columns number_of_columns ] | 
	[ Height frame_height [ Units paper_units ] ]
	[ Width frame_width [ Units paper_units ] ]
	[ Name frame_name ]
	[ Region [ Height region_height [ Units paper_units ] ] ]
	[ Region [ Width region_width [ Units paper_units ] ] ]
	[ Line [ Width line_width [ Units paper_units ] ] ]
	[ Auto Font Size { On | Off } ]
	[ Bar [ Thickness t_value ] [ Length l_value ] 
		[ Units paper_units ] [ Horizontal | Vertical ] ]
	[ Order { Default | Ascending | Descending | 
		{ Custom id | id : id [ , id | id : id ... ] ... } } ]
	[ Style [ Font... ] [ Count { On | Off } ]
		[ ID { id } Text { style_name } ] 
		[Line Pen... | Region Pen... Brush... | Symbol Symbol... ] ]
		[ , ... ]
	[ Angle frame_angle ]
	[ Metadata SetKey keyname To keyvalue ]

legend_or_layout_window_id is an integer window identifier for the Legend or Layout window that you can obtain by calling the FrontWindow() function and WindowID() function.

frame_id is the ID of the frame. You cannot use a layer name. For example, three frames would have the successive ID's 1, 2, and 3.

paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in (inches), pt (points), and pica. For details about paper units, see Set Paper Units statement.

• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points

frame_title is a string which defines a frame title.

frame_subtitle is a string which defines a frame subtitle.

number_of_columns is the number of columns to show in a frame.

frame_height this is used in place of the column clause when the user resizes a legend or layout frame. The height of the frame in paper units. Written to the WOR when the frame has been manually resized.

frame_width is width of the frame in paper units. Written to the WOR when the frame has been manually resized. The width cannot be specified for a Legend frame.

frame_name is a string representing the name for a frame in a Layout window. The frame_name cannot be specified for a Legend frame. If a name is assigned to a frame in the Layout window, it is written to the workspace (WOR file) and the workspace version is updated to 1500.

region_height is a value representing the new height of a swatch in the map frame of the Lengend or Layout window. You can specify 8 to 144 points, 0.666667 to 12 picas, 0.111111 to 2 inches, 0.282222 to 5.08 millimeters, or 0.282222 to 5.08 centimeters. If not specified, then the default value of 32 points is used (which can be set as a preference).

region_width is a value representing the new width of a swatch in the map frame of the Legend or Layout window window. You can specify 8 to 144 points, 0.666667 to 12 picas, 0.111111 to 2 inches, 0.282222 to 5.08 millimeters, or 0.282222 to 5.08 centimeters. If not specified, then the default value of 32 points is used (which can be set as a preference).

line_width is a value representing the new width of a line segment in the map frame of a Legend or Layout window. You can specify 12 to 144 points, 1 to 12 picas, 0.666667 to 2 inches, 4.23333 to 50.8 millimeters, or 4.23333 to 50.8 centimeters. If not specified, then the default value of 36 points is used (which can be set as a preference).

t_value thickness of the default frame border of a raster legend.

l_value lenght of the default frame border of a raster legend.

id is the position within the style list for that frame. To get information about the number of styles in a frame, use the LegendFrameInfo() function with attribute FRAME_NUM_STYLES (13).

style_name is a string that displays next to each symbol for the frame specified in ID. The "#" character will be replaced with the layer name. The "%" character will be replaced by the text "Line", "Point, "Region", as appropriate for the symbol. For example, "% of #" will expand to "Region of States" for the frame corresponding to the STATES.TAB layer.

frame_angle is a float value indicating the angle of rotation for a text or image frame only (in degrees). For symbol frames it can be used to alter the rotation of TrueType symbols (in degrees).

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

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

Description

If you omit the Window clause, the statement operates on the frontmost window, or the frontmost Legend or Layout window as the case may be.

The Position clause controls the frame's position on the Legend or Layout window. The upper left corner of the window has the position 0, 0. Position values use paper units settings, such as "in" (inches) or "cm" (centimeters). MapBasic has a current paper units setting, which defaults to inches; a MapBasic program can change this setting through the Set Paper Units statement. An Alter Designer Frame statement can override the current paper units by including the optional Units subclause within the Position clause.

The Title and SubTitle clauses accept new text, new font clause or both.

The Columns clause is the number of columns to show within a frame.

The Region Height clause specifies a specific height for a swatch in the legend frame of the Legend window.

The Region Width clause specifies a specific width for a swatch in the legend frame of the Legend window.

The Line Width clause specifies a specific width for a line sample in the legend frame of the Legend window.

Auto Font Size enables or disables resizing the legend swatch based on the font size setting.

The Bar clause lets you change the bar thickness or length after it has been created. It must include at least one of these: Thickness, Length, or orientation (Horizontal | Vertical). The Units causes is optional, MapInfo Pro defaults to inches. Only including Units causes a run-time error (an invalid clause error). The Thickness and Length value is from 0.1 to 72.0 inches. MapInfo Pro ignores a value that is outside the range of other legend swatch sizes (and clips the bar to display it within the range).

The Order clause adds the ability to sort or customize the order of rows in map legends. You can sort map legends by style label or by defining your own order. The sort order options are Default, Ascending, Descending, or Custom. The Order clause is only written to a workspace if the map legend is sorted ascending, descending, or custom.

A Default sort order is the order the Create Legend wizard creates the legend rows. If you create a legend based on unique styles, this will be the order of those styles, which then display as rows in the map legend.

If specifying Custom sort order, the id values are row ids starting with 1, moving from top to bottom. When looking at the list of rows in the Legend Frame Properties dialog box, the first row in the list has id equal to 1 and so on down the list. For more details, see Custom Order Options for more details.

The Display clause controls the display of each row. Each row in MapBasic starts with the Style clause. At the end of each Style clause is the optional Display clause. Display On makes the row visible. Display Off makes the row invisible. If the Display clause is absent, then the row displays. The Display clause is only written to a workspace file for styles that are not visible in a frame.

The paper Units are cm (centimeters), mm (millimeters), in (inches), pt (points), and pica. Conversions between these units are:

• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points

The Style clause must contain a list of definitions for the styles displayed in frame. You can only update the Style type for a legend frame created with the NoRefresh keyword. You can update the Text of any style. There is no way to add or remove styles from any type of frame.

The Count { On | Off } clause controls whether record counts should be shown per row for raster legends. The default is Off. This is only applicable to classified raster legends. Continuous raster legends do not show counts and will ignore this parameter. MapInfo Pro saves the Count setting in the WOR file. When working with a WOR file, MapInfo Pro only shows counts when it is set.

The Count clause stores the count value for a particular row in the legend frame for raster legends. This should not be modified. Values are 64 bit integers, ranging from zero (0) to 9,223,372,036,854,775,807. If invalid values are specified, no value is set, so a query using LEGEND_STYLE_INFO_COUNT returns -1. Continuous raster legends do not display counts, see Count above.

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

Only the following clauses will be applied to thematic legends. Those are:

	[ Position ( x, y ) [ Units paper_units ] ] 

	[ Columns number_of_columns ] | 
		[ Height frame_height [ Units paper_units ] ]

Example

The following example alters Frame 1 style sample 1 from a Cities points layer. It updates the title, subtitle, and text shown next to its symbols.

Alter Designer Frame
	Window FrontWindow()
	ID 1
	Position (1, .5) Units "in"
	Title "Big Cities"
	Subtitle "125 Biggest Cities"
	Style Font ("Arial",2,12,255)
		ID 1 Text "City Points"

See Also:

Add Designer Frame statement, Create Designer Legend statement, Remove Designer Frame statement, Set Designer Legend statement