EDN: ESRI Developer Network
Supported with: ArcGIS Engine with Maplex, ArcGIS Desktop with Maplex
Library dependencies: System, SystemUI, Geometry, Display, Server, Output, GeoDatabase, GISClient, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, GeoDatabaseDistributed, Carto, NetworkAnalyst, Schematic, Location, NetworkAnalysis, Controls, GeoAnalyst, 3DAnalyst, GlobeCore, SpatialAnalyst, Framework, GeoDatabaseUI, DisplayUI, OutputUI, Catalog, CatalogUI, CartoUI, DataSourcesRasterUI, ArcCatalogUI, ArcCatalog, ArcMapUI, Editor, LocationUI, ArcMap, EditorExt, SchematicUI, GeoDatabaseDistributedUI, Geoprocessing, GeoprocessingUI, NetworkAnalystUI, OutputExtensions, OutputExtensionsUI, SpatialAnalystUI, 3DAnalystUI, ArcScene, GlobeCoreUI, ArcGlobe, ArcScan, ArcReaderControl, Publisher, PublisherUI
Additional library information: Contents, Object Model Diagram
This content is also available in versions that specifically target .NET and Java developers. Click on the appropriate link to view either version.
.NET overview of the Maplex assembly
Java overview of the Maplex package
The Maplex library contains objects that control the Maplex text placement engine. It contains the principle object, the 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.
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 off it will contain placement property objects that are specific to Maplex. When this document is opened by another user, without the Maplex extension, the document must open successfully, and 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 core software) so they are made available to all users, and the truly optional part - the placement engine itself - 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. In order 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 very similar to the standard labeling objects, and 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, and both objects work in a very similar way. In terms of naming convention, the name 'Basic' has been replaced with 'Maplex'. So a familiarity with the standard labeling objects is a good starting point for learning the Maplex object model.
The Maplex version of BasicOverposter, provides a wrapper around the placement engine, hiding the details of the text placement algorithms. To use the overposter first 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 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. You retrieve all of 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 maybe controlled, however there are very 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 object AnnotateMap.
The Maplex version of AnnotateMap. This object is used by the map to create annotation and perform dynamic labeling. It utilises 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 the object that is used by ArcMap in the dialog that converts labels to annotation.
The interfaces implemented by 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 a MaplexAnnotateMap rather than an AnnotateMap.
You get the MaplexAnnotateMap object from the AnnotationEngine property of the map. Here's an example which shows how to do this and also how to identify which label engine is enabled.
Sub LabelEngineDetection() Dim pMxDoc As IMxDocument Dim pMap As IMap Set pMxDoc = Application.Document Set pMap = pMxDoc.FocusMap Dim pAnnotateMap As IAnnotateMap Set pAnnotateMap = pMap.AnnotationEngine ' detect using Name property If pAnnotateMap.Name = "ESRI Standard Label Engine" Then MsgBox "ESRI Standard Label Engine is selected for this map" End If If pAnnotateMap.Name = "ESRI Maplex Label Engine" Then MsgBox "ESRI Maplex Label Engine is selected for this map" End If ' detect using indicator interface If TypeOf pMap.AnnotationEngine Is IMaplexAnnotateMap Then MsgBox "ESRI Maplex Label Engine is selected for this map" Else MsgBox "ESRI Standard Label Engine is selected for this map" End If End Sub
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. This usually means that AnnotateFeature takes feature geometries in decimal degrees, whereas AnnotateMap takes geometries in projected space.
The Maplex version of PlacedObject. This object represents a label that is output from the labeling engine, and despite its name, 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.
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, then the geometry represents the position of the last line in the stack, and the horizontal justification is also provided as an attribute. Note that 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, then an overposter text path is used that describes the position of each character in the text. If the label consists of multiple words then a word text path 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 (multi-word 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 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, then the centroid is calculated on the clipped polygon, not the original geometry.