Maplex


Supported with:
Library dependencies: System, SystemUI, Geometry, Display, Server, Output, Geodatabase, GISClient, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, DataSourcesNetCDF, GeoDatabaseDistributed, GeoDatabaseExtensions, Carto, NetworkAnalysis, Location, GeoAnalyst, Animation

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 principle object— MaplexOverposter—which represents the placement engine, and MaplexAnnotateMap, which is used to create annotation and perform dynamic labeling. Use these objects in conjunction with the Maplex placement property objects that are contained in the Carto library. 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 object model

The Maplex object model has been split between libraries to support the sharing of map documents and database annotation. Consider the scenario where a user installs the Maplex extension and creates a map document using Maplex as the active placement engine. When the document is saved, it contains placement property objects that are specific to Maplex. When the document is opened by another user, without the Maplex extension, the document must open successfully. To achieve this, the user must have the placement property objects registered on the machine. The user does not need to run the text placement, but nevertheless, the placement property objects are required. For this reason, the Maplex placement property objects are contained in the Carto Library (as part of the core software) so they are made available to all users, and optionally, the placement engine is considered to be 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 the core Maplex property objects to be available on their machines. These users will be 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 effected. 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. There are many cases where there is a one-to-one correspondence between the standard object and its Maplex counterpart. For example, the MaplexOverposter is the equivalent of the BasicOverposter object (both objects work similar). In terms of naming conventions, the name Basic has been replaced with Maplex. A familiarity with standard labeling objects is recommended to learn the Maplex object model.

MaplexOverposter

The Maplex version of BasicOverposter provides a wrapper around the placement engine hiding the details of the text placement algorithms. To use the overposter, initialize it with parameters, such as the map extent, spatial reference, display object, track cancel object, and overposter properties and 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 enumerators.
MaplexOverposter differs from the BasicOverposter in a number of ways. MaplexOverposter does not generate events to fire back labels as they are placed like the BasicOverposter does. You retrieve all of the placed labels at the end of a placement run. MaplexOverposter determines the font metrics, 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 very few cases where you need to directly deal with MaplexOverposter. In most cases the aim is to create annotation, which is a complex task (this is best suited to the higher level MaplexAnnotateMap object.

MaplexAnnotateMap

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, the database, is standard annotation or feature linked annotation. This is the object that is most useful to developers and is used by ArcMap during labeling in the ConvertLabelsToAnnotation object.
The interfaces implemented by MaplexAnnotateMap object are identical to those in the standard AnnotateMap object with the exception of the indicator IMaplexAnnotateMap interface. This interface has no methods or properties and is used to identify the object as a MaplexAnnotateMap rather than an AnnotateMap.
The Draw method can be used to place labels on a map display, whereas the Label method is used to generate annotation. These methods both take a collection of IAnnotateLayerProperties as input. Each of these IAnnotateLayerProperties represents a label class and control, features that are given labels, annotation target, and so on.
Get the MaplexAnnotateMap object from the AnnotationEngine property of the map. The following code example shows how this is done and how to identify which label engine is enabled:
[Java]
IAnnotateMap aMap = getMapBean().getMap().getAnnotationEngine();

// Detect using the name property.
String engineName = aMap.getName();
if (engineName.equals("ESRI Standard Label Engine")){
    System.out.println("ESRI Standard Label Engine is selected for this map");
}

else if (engineName.equals("ESRI Maplex Label Engine")){
    System.out.println("ESRI Maplex Label Engine is selected for this map");
}

// Detect using the indicator interface.
IMaplexAnnotateMap maplexAnnotateMap = new IMaplexAnnotateMapProxy(aMap);
if (maplexAnnotateMap != null){
    System.out.println("ESRI Maplex Label Engine is selected for this map");
}

else{
    System.out.println("ESRI Standard Label Engine is selected for this map");
}

MaplexAnnotateFeature

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

MaplexPlacedLabel is the Maplex version of PlacedObject. This object represents a label that is output from the labeling engine and despite its name, it can 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, one point for the start of the label text and one point for the end. If the label is stacked and straight, 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 baseline.
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, an OverposterTextPath is used to describe the position of each character in the text. If the label consists of multiple words, a 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, the anchor point attribute in the placed label will be set. This represents the anchor point used by the callout and is calculated differently 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.