Managing Individual Label Properties - MapBasic - 2023

The following clauses affect label properties for a layer. This set of clauses apply to a layer. For layer clauses, see Managing Individual Layer Properties and Appearance.

Syntax

Set Map
	[ Window window_id ]
	[ Layer layer_id
		[ Label
			[ Line { Simple | Arrow | None } ]
			[ Position [ Center ] [ { Above | Below } ] [ {Left | Right } ] ]
			[ Auto Retry { On | Off } ]
			[ Font... ] [ Pen... ]
			[ With label_expr ] [ Parallel { On | Off } ] 
			[ Follow Path [ BestPosition { On | Off } ] [ Percent Over percent ] [ Fallback { On | Off } ] ]
			[ Visibility { On | Off | Zoom ( min_vis, max_vis ) 
				[ Units dist_unit ] } ]
			[ Auto  { On | Off }  ]
			[ Overlap  { On | Off }  ]
			[ PartialSegments { On | Off } ]
			[ Duplicates  { On | Off }  ]
			[ Max [ number_of_labels ] ]
			[ Offset offset_amount ]
			[ Default ]
			[ LabelAlpha alpha_value ]
			[ AutoPosition { On | Off } ]
			[ AutoSizes { number_font_sizes | Default } ]
			[ AutoSizeStep percentage_value ]
			[ SuppressIfNoFit { On | Off } ]
			[ AutoCallout { On | Off } ] 				
			[ Abbreviation { On | Off } Abbreviate with { field_expression } ]
			[ LABEL_OVERRIDE_CLAUSE ] ]
		[ Object bD
			[ Table alias ]
			[ Visibility { On | Off } ]
			[ Anchor ( anchor_x, anchor_y ) ]
			[ Text text_string ]
			[ Position [ Center ] [ { Above | Below } ] [ { Left | Right } ] ]
			[ Font... ] [ Pen... ]
			[ Line { Simple | Arrow | None } ]
			[ Angle text_angle ] [ Follow Path ]
			[ Offset offset_amount ]
			[ Callout ( callout_x, callout_y ) ]
			[ , Object... ] ] ]

window_id is the integer window identifier of a Map window.

layer_id identifies which layer to modify; can be a SmallInt (for example, use 1 to specify the top map layer other than Cosmetic) or a string representing the name of a table displayed in the map.

label_expr is the expression to use for creating labels.

min_vis, max_vis are numbers specifying the minimum and maximum zoom distances within which the labels will display.

dist_unit is a string expression, specifying the units for the map (such as "mi" for miles, "m" for meters; see Set Distance Units statement for a list of available unit names). This is an optional parameter. If not present, the distance units from the table's coordinate system are used.

number_of_labels is an integer representing the maximum number of labels MapInfo Pro will display for the layer. If you omit the number_of_labels argument, there is no limit.

offset_amount is a number from zero to 200 (representing a distance in points), causing the label to be offset from its anchor point.

alpha_value is a SmallInt that represents the alpha value of the labels in this layer. It is a value between 0-255 where 0 is completely transparent and 255 is completely opaque. Values in between display labels translucently.

number_font_sizes is a number from 1 to 10 that represents font size steps to use when fitting labels within regions. If not specified, the default value is 4.

percentage_value is a number from 1 to 99 that represents the smallest percentage decrease of the font size when resizing the label font to make labels fit when resizing the map. The default value is 50.

field_expression is the column name in the table that contains the abbreviations.

LABEL_OVERRIDE_CLAUSE is a shorthand notation, not a MapBasic keyword, see Adding Overrides for Layer Labels.

ID is an integer that identifies an edited label; generated automatically when the user saves a workspace. A label's ID equals the row ID of the object that owns the label.

alias is the name of a table that is part of a seamless map. The Table alias clause generates an error if this layer is not a seamless map.

anchor_x, anchor_y are map coordinates, specifying the anchor position for the label.

text_string is a string that will become the text of the label.

text_angle is an angle, in degrees, indicating the rotation of the text.

callout_x, callout_y are map coordinates, specifying the end of the label call-out line.

Description

The Label clause controls a map layer's labeling options. The Label clause has the following sub-clauses:

Line sets the type of call-out line, if any, that should appear when a label is dragged from its original location. You can specify Line Simple, Line Arrow, or Line None. For example:

Set Map Layer 1 Label Line Arrow

Position controls label positions with respect to the positions of object centroids. For example, the following statement sets labels above and to the right of object centroids.

Set Map Layer 1 Label Position Above Right

Auto Retry lets users to apply a placement algorithm that will try multiple label positions until a position is found that does not overlap any other label, or until all positions are exhausted.

• When Writing Workspaces, if the Auto Retry feature is On, we write Auto Retry On to the workspace after the Position clause (but the order isn't important), and increase the workspace version to 9.5 or later. If the feature is Off, we do not write anything to the workspace and do not increase the version number. A version 9.5 or later workspace can have Auto Retry Off in it, but we do not explicitly write it out, to avoid increasing the version unnecessarily.
• When Reading Workspaces If Auto Retry On or Auto Retry Off is in the workspace, it must be a version 9.5 or later workspace, otherwise a syntax error occurs. If Auto Retry is On, different positions are tried to place the label. If Auto Retry is Off, no retry is attempted―this is the default behavior. Overlap must be Off to enable the Auto Retry feature. If Overlap is On and Auto Retry On/Off are in the same LABELCLAUSE, the Auto Retry mechanism is initialized but ignored, so overlapping labels are allowed.

Font is a valid Font clause to specify a text style used in labels.

Pen is a valid Pen clause to specify the line style to use for call-out lines. Call-out lines only appear if you specify Line Simple or Line Arrow, and if the user drags a label from its original location.

Set Map Layer 1 Label Line Arrow Pen( 2, 1, 255)

With specifies the expression used to construct the text for the labels. For example, the following statement specifies a labeling expression which uses the Proper$( ) function to control capitalization in the label.

Set Map Layer 1 Label With Proper$(Cityname)

Parallel controls whether labels for line objects are rotated, so that the labels are parallel to the lines. Set to Off for horizontal labels that are not rotated with the line segment, and set to On for labels rotated with the line segment.

Set Map Layer 1 Label Parallel On

Follow Path is used when creating curved labels. Path is automatically calculated once and then stored until the curved label location is edited.

The BestPosition option attempts to find a more suitable location along a polyline when the polyline bends too sharply to place a label. The best three positions are located. If the label cannot be drawn at one of these positions, then it falls back to the normal curved label location and then to a rotated label if the Fallback option is on. The default value is Off.

Set Map Window 145919584 Layer 1 Label Follow Path BestPosition On

Percent Over only applies to curved labels. It applies when curved labels are longer than the geometry they name, this is the amount (expressed as a percentage) of overhang permitted. For example, a sample entry might be:

Set Map Layer 1 Label Follow Path Percent Over 40

Fallback only applies to curved labels. When a polyline is very jagged (not smooth or gently curved) it is difficult to place characters along it to create a curved label. Set Fallback to On to create a straight label when a curved label cannot be created. It rotates the straight label to match a segment near to where the curved label would have been placed. MapInfo Pro does not prevent a rotated label from crossing a polyline. Setting this option displays more labels on your map. By default, this option is set to Off. When MapInfo Pro cannot draw a curved label and draws a straight label instead (as a fallback), the overhang percent is ignored.

Visibility controls whether labels are visible for this layer. Specify Visibility Off to turn off label display for both default labels and user-edited labels. Specify Visibility Zoom... to set the labels to display only when the map is within a certain zoom distance. The following example sets labels to display when the map is zoomed to 2 km or less.

Set Map Layer 1 Label Visibility Zoom (0, 2) Units "km" 

Auto controls whether automatic labels display. If you specify Auto Off, automatic labels will not display, although user-edited labels will still display.

Overlap controls whether MapInfo Pro draws labels that would overlap existing labels. To prevent overlapping labels, specify Overlap Off.

PartialSegments controls whether MapInfo Pro labels an object when the object's centroid is not in the visible portion of the map. If you specify PartialSegments On (which corresponds to selecting the Label Partial Objects check box in MapInfo Pro), MapInfo Pro labels the visible portion of the object. If you specify PartialSegments Off, an object will only be labeled if its centroid appears in the Map window.

Duplicates controls whether MapInfo Pro allows two or more labels that have the same text. To prevent duplicate labels, specify Duplicates Off.

Max sets the maximum number of labels that MapInfo Pro will display for this layer. If you omit the number_of_labels argument, MapInfo Pro places no limit on the number of labels.

Offset specifies an offset distance, so that MapInfo Pro automatically places each label away from the object's centroid. The offset_amount argument is an integer from zero to 50, representing a distance in points. If you specify Offset 0 labels appear immediately adjacent to centroids. If you specify Offset 10 labels appear 10 points away. The offset setting is ignored when the Position clause specifies centered text. The following statement allows overlapping labels, placed to the right of object centroids, with a horizontal offset of 10 points:

Set Map Layer 1 Label Overlap On Position Right Offset 10 

AutoPosition turns on or off the advanced region labeling option. The AutoSizes, AutoSizeStep, and SuppressIfNoFit clauses are active when this is set to On. The default value for this clause is Off.

AutoSizes defines the number of decreasing font sizes that can be used when attempting to fit labels within regions. The value range is 1 to 10, and the default value is 4. Setting this to 1 uses the current font size. Setting a number greater than 1 reduces the font down to the minimum font size calculated using AutoSizeStep. Specifying Default causes MapInfo Pro to define the number of font sizes to use (between 1 and 10).

AutoSizeStep defines a percentage for reducing font size to make labels fit when resizing a map. The value range is 1 to 99. As an example, if the original font size is 24pt and the number_font_sizes is 66, then the smallest font is 66 percent smaller than 24pt, so the smallest font will be 8pt. The default value is 50.

When SuppressIfNoFit is set to On, then only the labels that still fit after resizing the map display. If a label does not fit in a region, then it is not drawn. This clause is set to On by default.

The AutoCallout clause turns on or off the rendering of callouts for advanced region labeling. The default value is Off. The AutoPosition and SuppressIfNoFit options must both be set to On to use the AutoCallout clause.

Abbreviation only applies to labels. When set to On, the abbreviation field expression, field_expression, is used for labels that cannot be drawn, because they overlap other labels or do not fit within a region. When set to On, you must also specify the Abbreviate with clause.

The Abbreviate with clause is used with the Abbreviation clause. This clause specifies the abbreviation field expression, field_expression, to use in the layer table.

Set Map Window 145919584  Layer 1 Label Abbreviation On

Set Map Window 145919584  Layer 1 Label Abbreviate with ShortName

Default resets all of the labels for this layer to their default values. The following statement deletes all edited labels from the top layer in the Map window, restoring the layer's default labels:

Set Map Layer 1 Label Default

The Object clause allows you to edit labels. For example, if you edit labels in MapInfo Pro and then save a workspace, the workspace contains Object clauses to represent the edited labels. The Set Map statement contains one Object clause for each edited label.

To see examples of the Object clause, edit a map's labels, save a workspace, and examine the workspace in a text editor.