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.