Working with labels and annotation

---

Labeling features on a map is a key factor in creating a usable map. Labeling is the placement of text near a feature to provide information about that feature. Usually, the label is based on attribute values of the feature, but it doesn't have to be.

ArcGIS labeling objects offer a wide variety of methods to label features and to resolve conflicts when labels overlap each other. Labeling behavior includes the ability to specify which features are to be labeled (for example, all features, features identified by a Structured Query Language [SQL] query, and so on); the expression used to label (expressions can be simple or complex based on VBScript and JScript); placement options and weights for placements; and priority specifications of one layer versus another. Depending on your requirements, it is also possible to label one layer with multiple expressions.

Objects in this model provide the ability to access all parameters associated with the labeling of features. Advanced developers can also create expression parsing engines to be used in the labeling process.

Labeling is performed by a label engine. Two label engines are available for use with ArcGIS. The ESRI Standard Label Engine is the default label engine. The ESRI Maplex Label Engine is an additional label engine for high-end cartographic label placement that is available for use via the Maplex for ArcGIS extension.

Drawing labels is significantly different from drawing features where you don't want overlapping text on maps. This requirement is the reason why label placement in ArcGIS is performed after feature drawing in the ArcGIS drawing pipeline. Also, for this reason, label placement is not performed on a layer-by-layer basis; instead, it is performed for the entire map at once. This allows the label engine to consider labels from multiple layers together to optimize the text placement. With each map refresh, label placement is run to achieve the best placement for the current map extent.

The labeling process is shown in the following steps in a label placement run:

A map contains labeling properties. The most significant labeling property is the Annotation Engine property, which is accessible via IMap.AnnotationEngine. This property designates the label engine used for labeling in the map. Set the AnnotateMap class to use the ESRI Standard Label Engine or set the MaplexAnnotateMap class to use the ESRI Maplex Label Engine.

Each label engine has a unique set of labeling properties; therefore, when a label engine is switched on a map, all layer-level labeling properties are converted to properties of the current label engine. This ensures that all labeling properties on the map are properties of the current label engine and not a mix of properties. This conversion is performed by the MaplexAnnotationPropertiesConverter class.

The map also implements IMapOverposter, which provides access to the OverposterProperties property, which implements IOverposterProperties, which implements for the current label engine. These are general properties that affect labeling of the map. Each label engine has its own OverposterProperties object. IOverposterOptions is implemented by BasicOverposterProperties and MaplexOverposterProperties and provides access to general properties, such as whether or not to lock the labels (EnableLabelCache property) or to draw unplaced labels (EnableDrawUnplaced property).

Feature layers store labeling properties that define the rules for label placement, as well as the text string and TextSymbol to use. Feature layers also have a layer level property that tells the label engine whether or not to place labels for the layer. IGeoFeatureLayer.DisplayAnnotation is set to true when labels are needed. 

Since it is common to place labels differently for different types of features in a single layer, the labeling framework supports multiple sets of labeling properties per layer. These properties are commonly known as "label classes" and are stored in the AnnotateLayerPropertiesCollection of the layer. The collection can be created, but it is typically retrieved from the IGeoFeatureLayer.AnnotationProperties property on a feature layer. The IAnnotateLayerPropertiesCollection interface allows for the manipulation of the label classes (objects implementing IAnnotateLayerProperties) held within the collection.

Each label engine has an object that implements IAnnotateLayerProperties. The ESRI Standard Label Engine uses the LabelEngineLayerProperties object, while the ESRI Maplex Label Engine uses the MaplexLabelEngineLayerProperties object.

The IAnnotateLayerProperties interface is implemented by the LabelEngineLayerProperties and MaplexLabelEngineLayerProperties objects and determines which features to label and at what scale. Through this interface, you can specify the priority of the labels, a where clause to apply to the feature layer, and what to do with unplaced elements.

The FeatureLinked, LabelWhichFeatures, and GraphicsContainer properties apply only when the set of labels is being converted to annotation. You can use the GraphicsContainer property to specify where the converted labels are placed.

The FeatureLayer property is used internally during the labeling process. If you need to set this property, set it back to null after labeling is completed.

The ILabelEngineLayerProperties2 interface is implemented by the LabelEngineLayerProperties and MaplexLabelEngineLayerProperties objects and provides access to the expression, symbol, and overposting properties of the label engine object. Use this interface to access the AnnotationExpressionEngine and OverposterLayerProperties objects associated with the label engine object. Each label engine has an OverposterLayerProperties object that stores the properties unique to that label engine.

By default, the ExpressionParser property returns the AnnotationVBScriptEngine object. Do not change this property unless you want to switch to JScript for labeling. In this case, an AnnotationJScriptEngine object is created, and the ExpressionParser property is set to this. The expression to use is always set through the Expression property.

The IsExpressionSimple property identifies whether a complex expression is being used in the Expression property. Complex expressions involve a parser object (ExpressionParser property) to parse the string.

The SymbolID property is used during the conversion of labels to annotation when a symbol collection in AnnotationFeatureClassExtension is referenced.

More precise control of the labeling properties can be obtained by accessing OverposterLayerProperties of the LabelEngineLayerProperties or MaplexLabelEngineLayerProperties objects. There are two OverposterLayerProperties objects—the BasicOverposterLayerProperties object for the ESRI Standard Label Engine and the MaplexOverposterLayerProperties object for the ESRI Maplex Label Engine. For more information on the large range of labeling properties available for each label engine, see the developer help for each object.

While labeling dynamically with each map refresh is a common way to manage text on a map, often it is necessary to refine the placement of labels via editing. Since labels are dynamically placed, they are not editable. To edit text, you need to convert labels to annotation. To aide with the conversion of labels to annotation, a helper object (ConvertLabelsToAnnotation) exists to make the process simpler. For more information on how to use this object for various conversion operations, see the following topics:

ArcGIS provides an annotation feature type for the storage of text in the geodatabase. Storing text in the geodatabase provides the ability to edit the text and more efficient drawing speeds than dynamic labeling since the text positions are fixed. Geodatabase annotation should not be confused with the similar map annotation, which is text stored in the map's BasicGraphicsLayer. For more information on the map's BasicGraphicsLayer, see Working with the map.

Annotation in ArcGIS is enabled through the use of a feature class extension and a special feature type. The AnnotationFeatureClassExtension object is used to configure the drawing properties and symbology for annotation features. AnnotationFeature controls the storage and communication of feature level operations. Annotation feature classes are created using methods on the IAnnotationLayerFactory interface on the FDOGraphicsLayerFactory object.

The ArcGIS annotation model was upgraded significantly at ArcGIS 9. If you're working with existing annotation feature classes that have not been updated to this model, update them as soon as you can. For more information, see Update Annotation Feature Class.

Annotation features persist and draw text or graphic elements stored in the geodatabase. An annotation feature class can be feature linked or standard. Feature linking allows the text of the annotation to be derived from the value of a related feature. The lifetime of the annotation is also controlled by the lifetime of the related feature. Feature-linked annotation is defined by proper setup of label placement properties in AnnotationFeatureClassExtension and the existence of a composite relationship class linking the two feature classes together. Feature-linked annotation is created by converting labels to annotation and specifying that feature-linked annotation is desired or by creating feature-linked annotation with FDOGraphicsLayerFactory. The IAnnotationClassExtension interface is used to access the properties of the annotation feature class extension. Commonly accessed properties are AnnotationLayerProperties and SymbolCollection.

Annotation features can persist an entire symbol inline or reference a symbol in a symbol collection. These two persistence mechanisms balance performance with flexibility. Storing the symbol inline allows the modification of the symbol on a feature-instance basis. Unfortunately, this method increases the size of a row dramatically and can cause performance degradation when drawing large numbers of features in a multiuser environment.

A more efficient alternative is to use symbols in the SymbolCollection of AnnotationFeatureClassExtension. There, symbols are stored as a property of AnnotationFeatureClassExtension. The annotation feature stores an ID that references a symbol in the extension’s SymbolCollection. TextElements are linked to symbols in the symbol collection by using the ISymbolCollectionElement interface on TextElement. A small number of commonly changed attributes can be overridden with minimal performance penalties using the ISymbolCollectionElement interface. Once an annotation feature has an element with a collection symbol, it is important that the symbol is not removed or modified in the SymbolCollection.

The IAnnoClassAdmin3 interface is used to update the properties of the class. In a versioned geodatabase, these properties apply to all versions and are not versioned. After creating an annotation feature class, modifying these properties may cause problems with the drawing and selection of annotation features. Adding new symbols to the SymbolCollection or changing the AutoCreate, UpdateOnShapeChange, OverposterProperties, and RequireSymbolID properties are the only recommended modifications. Deleting or modifying symbols in the SymbolCollection requires updating all annotation features whose elements reference the group symbol. When adding new symbols to the SymbolCollection, use the AddSymbol method of ISymbolCollection2, which automatically assigns a unique ID to the symbol. As with any schema related change, an exclusive schema lock must be obtained before calling the UpdateProperties method.

The OverposterProperties property indicates the label engine to be used by the annotation feature class to generate and update feature-linked annotation. If the annotation utilizes the ESRI Maplex Label Engine and the annotation is shared with a client without the Maplex for ArcGIS extension, the annotation downgrades to the ESRI Standard Label Engine when labeling operations are run.

The RequireSymbolID property indicates if annotation features are required to reference a symbol in the symbol collection. Referencing a symbol in the symbol collection is the most efficient way to store annotation features. If a symbol does not reference a symbol in the symbol collection, the text symbol is inefficiently stored inline with the feature in the feature’s binary large object (BLOB) field. Setting this property ensures that features reference a symbol in the symbol collection and are efficiently stored. To avoid separating annotation features from their referenced symbol, modify the properties of each annotation element using ISymbolCollectionElement. This interface allows access to the properties of an annotation feature class that can be overridden.

The AllowSymbolOverrides property indicates if an annotation can override a symbol property even though it references the symbol collection. If set to false, only the AnchorPoint, Background, and TextPath properties of the text symbol can be modified. Modification of these properties should be performed using ISymbolCollectionElement. This interface is best used in conjunction with RequireSymbolID and is used to limit the properties of an annotation feature that can be edited for either database efficiency or institutional reasons. Setting AllowSymbolOverrides to false greatly reduces the number of properties that can be overridden. In most cases, it is not recommended that this property be set to false.

The AnnotationFeature object persists and draws GraphicElements that are stored in the geodatabase. Typically, annotation stores TextElements and much of the behavior is optimized for TextElements. Annotation features can be linked to features in a related FeatureClass.

The IAnnotationFeature interface is used for relating AnnotationFeatures to other features or updating the graphic of the annotation. The Annotation property accepts any GraphicElement. If a TextElement is used, a group symbol can be assigned by using the IGroupSymbol interface. A TextElement that does not reference a symbol in the symbol collection will have a group symbol ID of –1.

To relate an AnnotationFeature to another feature (a RelationshipClass must already exist), assign the object identifier (OID) of the related feature to the LinkedFeatureID property. If the AnnotationFeature is not linked, the LinkedFeatureID property is –1. After updating either of these properties, call the IFeature.Store method.

The IAnnotationFeature2 interface provides access to the AnnotationClassID and Status properties of the annotation feature. You can update the status of an annotation feature from unplaced to placed after altering it.

The annotation feature class also has a series of fields that mirror properties stored in the annotation features Element field (where GraphicElements are stored). Updating the field values via the Geodatabase application programming interface (API) causes the annotation BLOB and, consequently, the annotation feature to update. This is a simple way to perform batch updates to an annotation feature.