Supported with:
Additional library information: Contents, Object Model Diagram
See the following sections for more information about this namespace:
- Engine
- ArcGIS for Desktop Basic
- ArcGIS for Desktop Standard
- ArcGIS for Desktop Advanced
Additional library information: Contents, Object Model Diagram
The Maplex library contains objects that control the Maplex label placement engine. It is the main library of the Maplex for ArcGIS extension. It contains the principal object, MaplexOverposter, that represents the placement engine itself, and MaplexAnnotateMap that is used to create annotation and perform dynamic labeling. These objects should be used in conjunction with the Maplex placement property objects that are contained in the Carto library. In general, you should also refer to the Maplex objects in the Carto library to fully understand the Maplex object model.
See the following sections for more information about this namespace:
Maplex objects
The Maplex object model has been split between libraries to support the sharing of map documents and database annotation. Consider the scenario where you install the Maplex extension and create a map document using Maplex as the active placement engine. When you save the document, it contains placement property objects that are specific to Maplex. To ensure the successful opening of this document by another user without the Maplex extension, the user must have the placement property objects registered on their machine. The user does not need to run the text placement; nevertheless, the placement property objects are required. For this reason, the Maplex placement property objects are contained in the Carto library (as part of core software) so they are made available to all users. The truly optional part—the placement engine—is considered the extension.
The sharing of database annotation is a similar issue. When feature-linked annotation is created in the database, Maplex placement property objects are stored in the class extension associated with the annotation feature class. To share the annotation, users without the extension require that the core Maplex property objects be available on their machines. These users are able to view the annotation and perform editing; however, the mechanism that updates the annotation in response to events in the original feature class, such as reshaping a feature or adding a new feature, is affected. In this case, the standard placement engine is used instead of the Maplex engine since the user is not licensed to use the extension.
The Maplex objects are similar to the standard labeling objects, and there are many cases of one-to-one correspondence between the standard object and its Maplex counterpart. For example, the MaplexOverposter object is the equivalent of the BasicOverposter object, and both objects work in a similar way. Because the name Basic has been replaced with Maplex, a familiarity with the standard labeling conventions of objects is a good starting point for learning the Maplex object model.
Maplex components
Maplex components consist of the following:
The Maplex version of BasicOverposter provides a wrapper around the placement engine, hiding the details of the text placement algorithms. To use MaplexOverposter, initialize it with parameters such as the map extent, spatial reference, display object, track cancel object, and overposter properties. Then call AddFeature to add the feature geometries (with associated text) to the label engine. Call PlaceLabels to start processing, and when this method returns, retrieve the results using the PlacedLabels and UnplacedLabels properties.
MaplexOverposter differs from BasicOverposter in a number of ways. MaplexOverposter does not generate events to fire back labels as they are placed as BasicOverposter does. You retrieve all the placed labels at the end of a placement run. MaplexOverposter determines the font metrics for you, so you don't need to supply the label size.
This object represents the lowest level at which the placement engine can be controlled; however, there are few cases where you would need to deal with MaplexOverposter directly. In most cases, the aim is to create annotation, which is a complex task, and this is best suited to the higher-level MaplexAnnotateMap object.
MaplexAnnotateMap is the Maplex version of AnnotateMap. This object is used by the map to create annotation and perform dynamic labeling. It utilizes the overposter object internally and provides the "driver logic" for creating the appropriate type of labeling. In particular, this object hides the detail associated with the process of creating annotation, a process that has variants depending on whether the destination is the map or the database and whether it's standard annotation or feature-linked annotation. This object is the most useful to developers and is used by ArcMap during labeling and in the ConvertLabelsToAnnotation object.
The interfaces implemented by the MaplexAnnotateMap object are identical to those in the standard AnnotateMap object with the exception of the indicator interface IMaplexAnnotateMap. This interface has no methods or properties; it is simply used to identify the object as MaplexAnnotateMap rather than AnnotateMap.
The Draw method can be used to place labels on a Map Display, whereas the Label method is used to generate annotation. Both methods take a collection of IAnnotateLayerProperties as input. Each of the IAnnotateLayerProperties represents a label class and control, such as what features are given labels and the annotation target.
You get the MaplexAnnotateMap object from the AnnotationEngine property of the Map. The following code example shows how to do this and how to identify which label engine is enabled:
[C#]
static void LabelEngineDetection(IMap pMap)
{
IAnnotateMap pAnnotateMap = pMap.AnnotationEngine as IAnnotateMap;
// Detect using Name property.
string engineName;
engineName = pAnnotateMap.Name;
if (engineName == "ESRI Standard Label Engine")
{
Console.WriteLine("ESRI Standard Label Engine is selected for this map");
}
else if (engineName == "ESRI Maplex Label Engine")
{
Console.WriteLine("ESRI Maplex Label Engine is selected for this map");
}
// Detect using indicator interface.
IMaplexAnnotateMap pMaplexAnnotateMap = pAnnotateMap as IMaplexAnnotateMap;
if (pMaplexAnnotateMap != null)
{
Console.WriteLine("ESRI Maplex Label Engine is selected for this map");
}
else
{
Console.WriteLine("ESRI Standard Label Engine is selected for this map");
}
}
[VB.NET]
Shared Sub LabelEngineDetection(ByVal pMap As IMap)
Dim pAnnotateMap As IAnnotateMap = pMap.AnnotationEngine
' Detect using Name property.
Dim engineName As String
engineName = pAnnotateMap.Name
If engineName = "ESRI Standard Label Engine" Then
Console.WriteLine("ESRI Standard Label Engine is selected for this map")
Else If engineName = "ESRI Maplex Label Engine" Then
Console.WriteLine("ESRI Maplex Label Engine is selected for this map")
End If
' Detect using indicator interface.
If typeof pAnnotateMap Is IMaplexAnnotateMap Then
Console.WriteLine("ESRI Maplex Label Engine is selected for this map")
Else
Console.WriteLine("ESRI Standard Label Engine is selected for this map")
End If
End Sub
MaplexAnnotateFeature is the Maplex version of AnnotateFeature. This object is used to annotate a single feature and is primarily used by the feature-linked annotation update mechanism to update the annotation element associated with a feature in response to an event, such as reshaping the feature geometry. This process is performed in the database without the involvement of a map object. A subtle difference when comparing this situation to the usage of AnnotateMap is the spatial reference that is used in the labeling. When annotating the map, the feature geometries are in the spatial reference of the map, whereas annotating a feature is typically performed using the native spatial reference of the data.
MaplexPlacedLabel is the Maplex version of BasicPlacedObject. This object represents a label that is output from the labeling engine, and despite its name, it may represent an unplaced label as well as a placed label. An unplaced label is identical to a placed label except it has a different placement code. Developers only need to be concerned about this object when calling MaplexOverposter directly, which is rare.
A straight label is output on a geometry that is a two-point base line. The geometry type is a polyline; with one point for the start of the label text and one point for the end. If the label is stacked and straight, then the geometry represents the position of the last line in the stack, and the horizontal justification is also provided as an attribute. The vertical justification is always set to the base line.
A curved label is output on a geometry that depends on how many words are in the label. If the label consists of a single word, OverposterTextPath is used to describe the position of each character in the text. If the label consists of multiple words, WordTextPath is used. In this case, a geometry bag is used to hold a collection of multipoint geometries, one multipoint for each word in the label.
The text path type is available as an attribute on the placed label and is an enumeration that explicitly indicates whether the text path geometry is simple text path (straight labels), an overposter text path (single word curved), or a word text path (multiword curved).
If the label has a background symbol that has a callout, then the anchor point attribute in the placed label will be set. This represents the anchor point used by the callout and is calculated depending on the type of feature. The anchor point for a polygon feature is taken to be the centroid of the polygon, whereas the anchor point for a line is the nearest point to the label. In the case of a polygon, if the feature is clipped by the map extent, the centroid is calculated on the clipped polygon, not the original geometry.