Label map features

Features and graphics in your ArcGIS Runtime SDK app can be labeled using a combination of attribute values and hard-coded text. Labeling properties allow you to specify placement options, label priority, and symbols for labels in your layer. You can define any number of label classes for a layer to set unique labels for distinct groups of features.

Define labels for features or graphics

Feature layers, graphics layers, and graphics overlays all have labeling properties that can be used to show or hide labels in the map and to control labeling behavior. A label class is used to specify what labels look like (font, size, color, angle, and so on), at which scales they should be visible, the text to display (which attributes, for example), as well as which features should be labeled. If you want to label all features in your layer the same way, you can define labeling with a single label class. If you want to display different labels for different types of features, you can add as many label classes as you need to define distinct sets of features for labeling.

The following example uses a single label class for all point features (United States cities). All labels use the same symbol and attribute (areaname).

<esri:FeatureLayer ID="Cities" >
    <esri:ServiceFeatureTable ServiceUri=""/>
        <esri:LabelProperties IsEnabled="True">
            <esri:AttributeLabelClass TextExpression="[areaname]" LabelPlacement="PointAboveCenter">
                <esri:TextSymbol Color="white">
                    <esri:SymbolFont FontFamily="Segoe" FontSize="14" FontWeight="Bold"/>

Attribute values in a labeling expression are identified by placing the attribute field name in square brackets.

Cities features labeled with one label class

There are several aspects of label behavior that you can control for a label class.

  • Text—A label expression can be used to determine the text to display for each feature in the label class. The label text can come from a combination of available attributes and hard-coded text. A label showing length in feet stored in an attribute named length_ft, for example, may look like this: [length_ft] CONCAT \" feet\". A feature with a length_ft value of 343 would result in a label of 343 feet.

    Label expressions are evaluated on the server and use the keywords and syntax described in the ArcGIS Server REST API documentation.

  • Symbol—The font, size, color, angle, and so on, used to display labels in the class. You can also provide a border or background for the label symbol.
  • Maximum scale—The largest scale at which labels in the class are shown. This value represents the scale denominator for the zoomed-in scale; a value of 0 means a maximum scale is not applied.
  • Minimum scale—The smallest scale at which labels in the class are shown. This value represents the scale denominator for the zoomed-out scale; a value of 0 means a minimum scale is not applied.
  • Placement—Labels can be placed at a specified position relative to the features they describe. There are different options for placement depending on the geometry of the feature being labeled. Line features, for example, may have labels placed above the center of the line, below the center of the line, above the end point, and so on.
  • Position—Logic for positioning labels can be controlled using a variety of options, such as whether they should be allowed to overlap with features in the layer.
  • Priority—A label class can be given a priority relative to other labels in the layer. If labels from different classes conflict in their placement, the label from the highest-priority class will be displayed.
  • WHERE clause—The features that belong in a label class are determined by evaluating an attribute expression. If using a single label class for a layer, there is no need to explicitly define this expression. When using multiple label classes, however, it's important to define WHERE clauses that uniquely assign features for each class.

Creating multiple label classes is useful when you want to distinguish labels for certain types of features on the map. When labeling cities, for example, you may want to display capital cities with a larger font or different color. The following example uses two label classes to make labels for state capitals stand out.

<esri:FeatureLayer ID="Cities" >
    <esri:ServiceFeatureTable ServiceUri=""/>
        <esri:LabelProperties IsEnabled="True">
            <esri:AttributeLabelClass WhereClause="capital = 'N'" TextExpression="[areaname]" LabelPlacement="PointAboveCenter">
                <esri:TextSymbol Color="OldLace">
                    <esri:SymbolFont FontFamily="Segoe" FontSize="14" FontWeight="Bold"/>
            <esri:AttributeLabelClass WhereClause="capital = 'Y'" TextExpression="[areaname]" LabelPlacement="PointAboveCenter">
                <esri:TextSymbol Color="white">
                    <esri:SymbolFont FontFamily="Segoe" FontSize="18" FontWeight="Bold"/>

Label classes for capital and noncapital cities

Label visibility can be controlled for individual label classes or for the entire layer (all label classes). Labels are not displayed when layer features are not visible.

Define labels for a dynamic layer

Labels for dynamic layers can be controlled in much the same way as labels for feature and graphics layers. Dynamic layers have drawing options that include label information for each layer displayed from the service. Dynamic label information can be used to define the symbol, labeling expression, placement options, and so on. You can also use WHERE expressions to define different groups of labels for the layer.

The following example displays labels for cities in the United States that have a population greater than 50,000.

<esri:ArcGISDynamicMapServiceLayer x:Name="dynamicLayer" ID="USA"
    <!-- city label info -->
            <esri:LayerDrawingOptions LayerID="0" ShowLabels="True">
                    <esri:DynamicLabelingInfo LabelExpression="[areaname]" LabelPlacement="PointAboveRight" Where="pop2000 > 50000">
                            <esri:TextSymbol Color="Beige">
                                    <esri:SymbolFont FontFamily="Arial" FontSize="12" FontStyle="Italic" FontWeight="Bold" />

ArcGISDynamicMapServiceLayer with labels

You can also work with the DynamicLabelingInfo class programmatically. The following example adds a new set of labels for cities with a population less than 50,000.

// Minor city label info
DynamicLabelingInfo minorCityLabelInfo = new DynamicLabelingInfo();
minorCityLabelInfo.LabelExpression = "[areaname]";
minorCityLabelInfo.LabelPlacement = LabelPlacement.PointAboveCenter;
minorCityLabelInfo.Symbol = new Esri.ArcGISRuntime.Symbology.TextSymbol()
    Color = Colors.Black,
    Font = new SymbolFont("Arial", 12, SymbolFontStyle.Normal, SymbolTextDecoration.None, SymbolFontWeight.Normal)
minorCityLabelInfo.Where = "pop2000 <= 50000";
minorCityLabelInfo.MaxScale = 0;
minorCityLabelInfo.MinScale = 5000000;

// Add minor city label info
var labelInfos = dynamicLayer.LayerDrawingOptions[0].LabelingInfos;

Related topics