Create Adornment statement - MapBasic - 2023

Purpose

Creates and displays Adornments, such as a scale bar, on mapper window. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Create Adornment
	From Window map_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 defaults to the MapBasic Paper Unit. For details about paper units, see Set Paper Units statement.

win_position specify one of the following codes; codes are defined in the MAPBASIC.DEF file.

	ADORNMENT_INFO_MAP_POS_TL (0)
	ADORNMENT_INFO_MAP_POS_TC (1)
	ADORNMENT_INFO_MAP_POS_TR (2)
	ADORNMENT_INFO_MAP_POS_CL (3)
	ADORNMENT_INFO_MAP_POS_CC (4)
	ADORNMENT_INFO_MAP_POS_CR (5)
	ADORNMENT_INFO_MAP_POS_BL (6)
	ADORNMENT_INFO_MAP_POS_BC (7)
	ADORNMENT_INFO_MAP_POS_BR (8)

(x, y) in the Offset clause is measured from the anchor position. For example, if the win_position is ADORNMENT_INFO_MAP_POS_TL (top left), then the x is to the right and the y is down. If the win_position is ADORNMENT_INFO_MAP_POS_BR, then the x position is left and the y position is up. In the center left (ADORNMENT_INFO_MAP_POS_CL) and center right (ADORNMENT_INFO_MAP_POS_CR), the y offset is ignored. In the center position (ADORNMENT_INFO_MAP_POS_CC), the offset is ignored completely (both x and y). In the top center (ADORNMENT_INFO_MAP_POS_TC) and bottom center (ADORNMENT_INFO_MAP_POS_BC) positions, the x offset is ignored. For ADORNMENT_INFO_MAP_POS_ defines, see win_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 specify one of the following codes; codes are defined in the MAPBASIC.DEF file.

	SCALEBAR_INFO_BARTYPE_CHECKEDBAR  (0)
	SCALEBAR_INFO_BARTYPE_SOLIDBAR    (1)
	SCALEBAR_INFO_BARTYPE_LINEBAR     (2)
	SCALEBAR_INFO_BARTYPE_TICKBAR     (3)

0 Check Bar, 1 Solid Bar, 2 Line Bar, or 3 Tick Bar

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.

paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in (inches), pt (points), and pica.

• 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

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 relative to some anchor point on the mapper specified by win_position.

Offset is the amount the adornment will be offset from the mapper when using one of the docked win_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.

Offset is the amount the adornment will be offset from the mapper when using one of the docked win_positions.

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

Example

If the paper_length is 1 and the paper_unit is inches, then the scale bar displays as 1 inch. It is labeled in the distance_unit for the current amount that paper_unit spans, and it dynamically updates as the map changes (e.g., zoom and pan). The default distance_unit is the current distance unit in the mapper. The paper_height determines how tall the scale bar displays. The Pen and Brush define the style to draw the scale bar with and Font defines the text style for scale bar labeling and annotation. The Scale parameter displays a cartographic scale.

The following example shows creating a scalebar with default settings :

create adornment 
	from window 261763624 
	type scalebar 
	position 6 offset (0.000000, 0.000000) units "in" 
	background Brush (2,16777215,16777215)  Pen (1,2,0)  
	bartype 0 ground units "mi" display units "in" 
	barlength 1.574803 barheight 0.078740 
	barstyle Pen (1,2,0)  Brush (2,0,16777215)  Font ("Arial",0,8,0) 
	scale on 

create adornment 
	from window 261727232
	type smarttextadornment
	position 7 offset (0.2, 0.2)
	background Brush (1,16777215,16777215) Pen (1,2,0)  
	Text "$mb{FormatDateTime$(CurDateTime())}"
	Font ("Arial",0,10,0) 

create adornment from window frontWindow() type smarttextadornment Text "ABC and XYZ"

create adornment from window frontWindow() type smarttextadornment Text 
	"$mb{FormatDateTime$(CurDateTime())}" Font("Arial",0,10,0) 
	Justify Center

Create Adornment  Type SmartTextAdornment Background Brush (17,16711680,65280) 
	Pen (3,2,16711935) Size Width 1.469980 Height 0.305556 Units "in" 
	Position 1 Offset (0.000000, 0.000000) Units "in" 
	Layout Fixed Position Geographic Text "Hello" Font ("Arial",0,10,0) 
	Justify Center

create adornment from window frontWindow() type smarttextadornment 
	position 7 offset (0.2, 0.2) background Brush (1,16777215,16777215) 
	pen (1, 0, 0) Text "$mb{FormatDateTime$(CurDateTime())}" 
	Font ("Arial",0,10,0)

Removing an Adornment

Close Window MapperInfo(<window_id>, 201)

The window_id parameter specifies which Map window to query. 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.

201 is the MapperInfo() attribute id as defined in MapBasic.def.

See Also:

Set Adornment statement, AdornmentInfo() function