com.esri.arcgis.carto
Interface IOverposter

All Superinterfaces:
Serializable
All Known Implementing Classes:
BasicOverposter

public interface IOverposter
extends Serializable

Provides access to members that place labels for features using conflict detection.

Superseded By

IOverposter3

Description

IOverposter is an interface for placing labels and symbols implemented by BasicOveposter (aka the ESRI Standard Label Engine). Follow this general sequence of steps when using this interface:

1. Call AddClass for each class to initialize properties for each class. (InsertClass, RemoveClass, and ResetClasses help manage the classes.)
2. Use Initialize to set up the current extent and display.
3. Call AddBarrier, AddLabel, and/or AddSymbol for each participating feature.
4. Call PlaceObjects to make sure all objects are placed.
5. Use NextPlaced, NextUnplaced, and/or NextUnused to get placed object locations. You will probably want to draw them as you get them.
6. Call ReleaseResources.

This interface is designed for low level access to the placement algorithms of the BasicOverposter. The labeling maps and features, use the AnnotateMap and AnnoateFeature objects. They wrap calls to the BasicOverposter into a more general form for use with layers and maps.

When To Use

The IOverposter interface is a low level interface for managing conflict detection when labeling features.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.


Method Summary
 void addBarriers(int weight, IGeometryCollection barriers)
          Adds a barrier object that placed objects must avoid.
 int addClass(IOverposterLayerProperties props)
          Adds a class to the overposter and specifies its properties.
 void addCurvedLabel(int classIndex, String label, Object widths, Object ascents, Object descents, double fontHeight, double fontDescent, IGeometry controlShape, int featureId, ISymbol symbol)
          Adds a curved label object to be placed.
 void addLabel(int classIndex, String label, double width, double height, IGeometry controlShape, int featureId, ISymbol symbol)
          Adds a label object to be placed.
 void addSymbol(int classIndex, ISymbol symbol, IGeometry geometry, int featureId)
          Adds a symbol to be placed.
 int getCapabilities(ILayer layer)
          Overposter capabilities for the specified layer.
 int getNumberOfPlacedLabels()
          The number of unplaced labels.
 int getNumberOfUnplacedLabels()
          The number of unplaced labels.
 int getNumClasses()
          The number of classes.
 void initialize(IEnvelope extent, IDisplay display)
          Initializes the overposter for drawing into the specified area of the map display.
 void insertClass(int index, IOverposterLayerProperties props)
          Inserts a class at a specific index, and specifies its peoperties.
 void nextPlaced(IPlacedObject[] object, ITrackCancel trackCancel, IStepProgressor stepProgressor)
          The next object that was successfully placed.
 void nextUnplaced(IPlacedObject[] object)
          The next object that was not successfully placed.
 void nextUnused(IPlacedObject[] object)
          The next object that was not used.
 void placeObjects()
          Places objects using the overposter.
 void releaseResources()
          Releases current objects from memory.
 void removeClass(int classIndex)
          Removes the class at the specified index from the overposter.
 void resetClasses()
          Removes all classes from the overposter.
 

Method Detail

getNumClasses

int getNumClasses()
                  throws IOException,
                         AutomationException
The number of classes.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Returns:
The count
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getCapabilities

int getCapabilities(ILayer layer)
                    throws IOException,
                           AutomationException
Overposter capabilities for the specified layer.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:
layer - A reference to a com.esri.arcgis.carto.ILayer (in)
Returns:
A com.esri.arcgis.carto.esriOverposterCaps constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

addClass

int addClass(IOverposterLayerProperties props)
             throws IOException,
                    AutomationException
Adds a class to the overposter and specifies its properties.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
props - A reference to a com.esri.arcgis.carto.IOverposterLayerProperties (in)
Returns:
The classIndex
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

insertClass

void insertClass(int index,
                 IOverposterLayerProperties props)
                 throws IOException,
                        AutomationException
Inserts a class at a specific index, and specifies its peoperties.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
index - The index (in)
props - A reference to a com.esri.arcgis.carto.IOverposterLayerProperties (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

removeClass

void removeClass(int classIndex)
                 throws IOException,
                        AutomationException
Removes the class at the specified index from the overposter.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
classIndex - The classIndex (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

resetClasses

void resetClasses()
                  throws IOException,
                         AutomationException
Removes all classes from the overposter.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

initialize

void initialize(IEnvelope extent,
                IDisplay display)
                throws IOException,
                       AutomationException
Initializes the overposter for drawing into the specified area of the map display.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
extent - A reference to a com.esri.arcgis.geometry.IEnvelope (in)
display - A reference to a com.esri.arcgis.display.IDisplay (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

addBarriers

void addBarriers(int weight,
                 IGeometryCollection barriers)
                 throws IOException,
                        AutomationException
Adds a barrier object that placed objects must avoid.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
weight - A com.esri.arcgis.carto.esriBasicOverposterWeight constant (in)
barriers - A reference to a com.esri.arcgis.geometry.IGeometryCollection (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

addLabel

void addLabel(int classIndex,
              String label,
              double width,
              double height,
              IGeometry controlShape,
              int featureId,
              ISymbol symbol)
              throws IOException,
                     AutomationException
Adds a label object to be placed.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
classIndex - The classIndex (in)
label - The label (in)
width - The width (in)
height - The height (in)
controlShape - A reference to a com.esri.arcgis.geometry.IGeometry (in)
featureId - The featureId (in)
symbol - A reference to a com.esri.arcgis.display.ISymbol (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

addCurvedLabel

void addCurvedLabel(int classIndex,
                    String label,
                    Object widths,
                    Object ascents,
                    Object descents,
                    double fontHeight,
                    double fontDescent,
                    IGeometry controlShape,
                    int featureId,
                    ISymbol symbol)
                    throws IOException,
                           AutomationException
Adds a curved label object to be placed.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
classIndex - The classIndex (in)
label - The label (in)
widths - A Variant (in)
ascents - A Variant (in)
descents - A Variant (in)
fontHeight - The fontHeight (in)
fontDescent - The fontDescent (in)
controlShape - A reference to a com.esri.arcgis.geometry.IGeometry (in)
featureId - The featureId (in)
symbol - A reference to a com.esri.arcgis.display.ISymbol (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

addSymbol

void addSymbol(int classIndex,
               ISymbol symbol,
               IGeometry geometry,
               int featureId)
               throws IOException,
                      AutomationException
Adds a symbol to be placed.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
classIndex - The classIndex (in)
symbol - A reference to a com.esri.arcgis.display.ISymbol (in)
geometry - A reference to a com.esri.arcgis.geometry.IGeometry (in)
featureId - The featureId (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

placeObjects

void placeObjects()
                  throws IOException,
                         AutomationException
Places objects using the overposter.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

nextPlaced

void nextPlaced(IPlacedObject[] object,
                ITrackCancel trackCancel,
                IStepProgressor stepProgressor)
                throws IOException,
                       AutomationException
The next object that was successfully placed.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
object - A reference to a com.esri.arcgis.carto.IPlacedObject (in/out: use single element array)
trackCancel - A reference to a com.esri.arcgis.system.ITrackCancel (in)
stepProgressor - A reference to a com.esri.arcgis.system.IStepProgressor (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

nextUnplaced

void nextUnplaced(IPlacedObject[] object)
                  throws IOException,
                         AutomationException
The next object that was not successfully placed.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
object - A reference to a com.esri.arcgis.carto.IPlacedObject (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

nextUnused

void nextUnused(IPlacedObject[] object)
                throws IOException,
                       AutomationException
The next object that was not used.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
object - A reference to a com.esri.arcgis.carto.IPlacedObject (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

releaseResources

void releaseResources()
                      throws IOException,
                             AutomationException
Releases current objects from memory.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getNumberOfUnplacedLabels

int getNumberOfUnplacedLabels()
                              throws IOException,
                                     AutomationException
The number of unplaced labels. Only valid after calling PlaceObjects.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Returns:
The count
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getNumberOfPlacedLabels

int getNumberOfPlacedLabels()
                            throws IOException,
                                   AutomationException
The number of unplaced labels. Only valid after calling PlaceObjects.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Returns:
The count
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.