Set Adornment statement - MapBasic - 2023

Purpose

Modifies the adornment created by the Create Adornment statement. You can change the adornment position, its dimensions, and specify a border for it. For the scale bar adornment, you can change its display style, the bar type, units, dimensions, and display a cartographic scale with it. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Set Adornment
Window window_id
	[ Type adornment_type ]
	[ Position {
		[ Fixed [ ( x, y ) [ Units paper_units ] ] ] |
		[ win_position [ Offset ( x, y ) ] [ Units paper_units ] ]
	} ]
	[ Layout Fixed Position { Frame | Geographic } ]
	[ Size [ Width win_width ] [ Height win_height  ] [ Units paper_units ] ]
	[ Background [ Brush ... ] [ Pen ... ] ]
	[ < SCALEBAR_CLAUSE > ]
	[ < SMART_TEXT_CLAUSE > ]

Where SCALEBAR_CLAUSE is:

	[ BarType type ]
	[ Ground Units distance_units ]
	[ Display Units paper_units ]
	[ BarLength paper_length ]
	[ BarHeight paper_height ]
	[ BarStyle [ Pen .... ] [ Brush ... ] [ Font ... ] ]
	[ Scale [ { On | Off } ] ]
	[ Auto [ { On | Off } ] ]

	[ Text text_expression ]
	[ Font... ]
	[ Spacing { 1.0 | 1.5 | 2.0 } ]
	[ Justify { Left | Center | Right } ]

adornment_type can be scalebar or smarttextadornment.

(x, y) in the Fixed clause is position measured from the upper left of the mapper window, which is (0, 0). Using this version of adornment placement, the adornment will be at that position in the mapper as the mapper resizes. For example, a position of (3, 3) inches would be toward the bottom right of a small sized mapper but in the middle of a large sized mapper. As the mapper changes size, the adornment will try to remain completely within the displayed mapper.

paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in (inches), pt (points), and pica. This value defaults to the MapBasic 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

win_position specifies one of the adornment position codes, which are defined in the MAPBASIC.DEF file and listed in the following Description.

(x, y) in the Offset clause is measured from the anchor position.

win_width and win_height define the size of the adornment. MapInfo Pro ignores these parameters if this is a scale bar adornment, because scale bar adornment size is determined by scale bar specific items, such as BarLength.

type specifies one of the scale bar codes, which are defined in the MAPBASIC.DEF file and listed in the following Description.

distance_units a unit of measure that the scale bar is to represent:

paper_length a value in paper_units to specify how long the scale bar will be displayed. Specify the length of the scale bar to a maximum of 34 inches or 86.3 cm on the printed map.

paper_height a value in paper_units to specify how tall the scale bar will be displayed. Specify height of the adornment to a maximum of 44 inches or 111.76cm on the printed map.

text_expression could be a simple text expression or a MapBasic expression to evaluate a value and display it as text on a map. It is a string value and can be up to 2047 characters long,

Description

The scale bar displays as a paper_length bar in the paper_units.

Position can be Fixed relative to the mapper upper left regardless of the size of the mapper, or it can be relative to an anchor point on the mapper that is specified by win_position.

Offset is the amount the adornment will be offset from the mapper when using one of the docked win_position settings. For example, if the win_position is ADORNMENT_INFO_MAP_POS_TL (Top Left), then the Offset x value will be to the right of the top left position and the y value will be down from the top left position.

Layout Fixed Position determines how an adornment is positioned in a layout when the adornment is using Fixed positioning. If this is set to Geographic, then the adornment is placed on the same geographic place on the map frame in the layout as it is in the mapper. If the layout frame changes size, then the adornment will move relative to the frame to match the geographic position. If this is set to Frame, then the adornment will remain at a fixed position relative to the frame, as designated in the Position clause. If the Position clause positions the adornment at (1.0, 1.0) inches, then the adornment will be placed 1 inch to the left and one inch down from the upper left corner of the frame. Changing the size of the frame will not change the position of the adornment. The default is Geographic.

The Background clause when used with Brush denotes the fill pattern to be used in the background while creating or modifying a scale bar. When used with the Pen clause, this denotes the border to be used in the background while creating or modifying a scale bar.

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 adornment.

Pen is a valid Pen clause. Due to window clipping (the adornment is a window within the mapper), Pen widths other than 1 may not display correctly. Also, Pen styles other than solid may not display correctly. This clause is designed to turn on (solid) or off (hollow) and set the color of the border of the adornment.

Font is a valid Font clause.

The Auto clause set to On shows values that have been automatically rounded in the scale bar. If the clause is set to Off, the values will not be rounded and will be shown like they had been in earlier versions. The default is Auto Off, if not already specified.

Use Scale set to On to include a representative fraction (RF) with the scale bar. (In MapInfo Pro, a map scale that does not include distance units, such as 1:63,360 or 1:1,000,000, is called a cartographic scale.)

When specifying BarType the type is a code that sets what type of scale bar to display: 0 Check Bar, 1 Solid Bar, 2 Line Bar, or 3 Tick Bar.

The codes are defined in the MAPBASIC.DEF file and are:

Example

set adornment 
	window 261727232 
	type scalebar 
	position 6 
	background Brush (2,16777215,16777215)  Pen (1,2,0)  
	bartype 0 ground units "km" display units "cm" 
	barlength 0.978478 barheight 0.078740 
	barstyle Pen (1,2,0)  Brush (2,0,16777215)  Font ("Arial",0,8,0) 
	scale on 

set adornment 
	window 261727232
	type smarttextadornment
	position 7 offset (0.2, 0.2)
	background Brush (1,16777215,16777215)  Pen (1,0,0)  
	Text "$mb{FormatDateTime$(CurDateTime())}"
       Font ("Helvetica",1,12,16711680,16777215)

See Also: