SetLabels()

Summary

Enables or disables, and sets options for, labeling for a layer or selection set.

Changes

In Version 6.0/2012 added options for angle, callouts, extra colors, halos, leading, overlap, shadows, and skipping partial labels.

Syntax

SetLabels(string lyr_set_name, string label_expr, array options)

Argument	Contents
lyr_set_name	The name of the layer or selection set
label_expr	A field name, or an expression whose result is used as the label

Option	Type	Contents
Alignment	String	Desired label position relative to the feature, expressed as a compass direction ("NW", "N", "NE", "W", "C", "E", "SW", "S," "SE") or "Auto" for automatic positioning
Alternate Field	String	A field name, or an expression whose result is used as the label if using the primary field would cause an overlap but using this alternate would not
Angle	Real or String	If real then a value between -90 and 90 to specify the slope of the labels, else the string "Automatic" to align with latitudes
Callout Color	Color	Color of callout lines
Callout Line Style	Linestyle	Style of callout lines
Callout Style	Integer	1=straight line, 2=straight line with vertical bar, 3=bent line, or 4=bent line with vertical bar, corresponding to the four styles displayed on the callout tab
Callout Width	Real	Width of callout lines
Color	Color	Label color
Extra Colors	Array of colors	Colors for second, third, etc. lines of multi-line labels
Font	String	Font name, size, and style
Format	String	Format to use when labeling a numeric field
Frame Border Style	Linestyle	Style of the frame border
Frame Border Color	Color	Color of the frame border
Frame Border Width	Real	Width of the frame in points
Frame Fill Color	Color	Color of the interior of the frame
Frame Fill Style	Fillstyle	Style used for the interior of the frame
Frame Shield	Array	The highway shield definition (string font_name, array of (integer index, color))
Frame Type	String	Shape of the frame ("ellipse", "rectangle", "rounded rectangle", or "shield")
Framed	Boolean	Whether frames should be displayed around each label
Halo Color	Color	Color used for halo
Has Halo	Boolean	If "True" display halos on labels; the default is "False"
Has Shadow	Boolean	If "True" display shadows on labels; the default is "False"
Kern To Fill	Boolean	Whether label text should be stretched, by inserting extra spaces, to fit the feature being labeled
Leading	Integer	Percentage of regular line spacing (100, the default, is normal)
Left/Right	Boolean	If "True" look for a corresponding BA field matching the AB field in the input field name, and label both the left and the right sides of lines; the default is "False"; line layers only
Line Length Limit	Integer	Maximum number of characters
Overlap	Boolean	If "True" labels can be overlapped by other labels; the default is "False"
Priority Expression	String	Expression whose value indicates the relative label priority among features in the layer or selection set
Rotation	Boolean	Whether line labels should be rotated to align with line features
Scale	2 Reals	Autoscale settings (real minimum scale, real maximum scale)
Set Priority	Integer	Label priority for this layer or selection set
Shadow Color	Color	Color used for shadow
Skip Partial	Boolean	If "'True" then labels which cannot be fit fully on-screen will not be displayed; the default is "False"
Smart	Boolean	Whether special label locating logic should be used to place a label in a more aesthetically pleasing location
Uniqueness	String	Boolean value ("On" or "Off") to control whether unique labels are displayed (duplicate labels are not allowed), or a real value in a string to give the spacing in page units
Visibility	Boolean	Whether labels are displayed ("On") or hidden ("Off")

Notes

To turn off labels, call SetLabelOptions() with the Visibility option set to Off.
To turn off labels for all currently displaying layers, call HideMapLabels().
Label settings for a selection set override the corresponding settings for the layer as a whole.
Label settings for a layer or selection set in one map do not change settings for the same layer or selection set in other maps.
The alignment, rotation, and uniqueness options apply to an entire layer, and cannot be set differently for a selection set than for the layer as a whole.
When the automatic alignment option is selected, Maptitude tries to place the label in the upper right position. If it doesn't fit there because of a collision with another label, Maptitude tries to place the label in the lower right position, then upper left, lower left, centered above, centered below, to the right, and finally to the left.
Smart placement attempts, for example, to place an area label as near to the centroid as possible, while allowing the entire label to fit within the feature; or, for line features, smart placement attempts to find the segment nearest the middle segment that has a long enough straight section to accommodate placing the label without cutting across other line feature segments.
When using Priority Expression, features with lower values are labelled before features with higher values. To label features with higher values first, negate the expression; e.g., "-Population" will list more populous features first.
If a label string has more characters than the line length limit, then the first word of the string beyond that limit will be placed on a new line.

Examples

SetLabels("U.S. States|", "Name", {

{"Font", "Arial|Bold|16"},

{"Color", ColorRGB(50000,50000,0)},

{"Priority Expression", "Population"}

})

SetLabels("NY|City|Under 250,000", "Name", {{"Visibility", "Off"}})

Error Codes

Error Type	Meaning
Error	The label expression or an option is invalid
NotFound	There is no such layer or selection set

Function	Summary
GetLabelExpression()	Gets the label expression for a layer or selection set
GetLabelOptions()	Gets the label option settings for a map
GetLabelOverlapStatus()	Gets the status of whether labels can be drawn on top of point icons
SetLabelOptions()	Changes the option settings for labels
SetLabelOverlapStatus()	Sets the status of whether labels can be drawn on top of point icons