com.esri.arcgis.carto
Interface ILegendItem

All Superinterfaces:

Serializable

All Known Implementing Classes:

HorizontalBarLegendItem, HorizontalLegendItem, NestedLegendItem, VerticalLegendItem

public interface ILegendItem
extends Serializable

Provides access to members that control how a layer appears in a legend. Can be stored in a style.

Superseded By

ILegendItem3

Remarks

The Legend can be seen as a collection of map layers each layer being represented by a LegendItem.
The ILegendItem interface controls all the properties of a legend item:

CanDisplay will be true if the type of the LegendItem is compatible with the rendering of the layer. NestedLegendItem for instance, cannot be used by all renderers.

The Layer property returns the layer this LegendItem is associated with

Columns is the number of columns it should span. Height and Width control the size of the legend item.

ILegendItem also gives access to the graphic elements used to draw the legend item - Graphics property - to the symbols specific to this legend item - HeadingSymbol, LayerNameSymbol - and to the legend items LegendClassFormat object.

NewColumn controls whether the LegendItem should be displayed starting a new column. KeepTogether indicates if it can be split over different columns. A number of properties control whether the label, description, heading, and layer name should be displayed.

Horizontal and Vertical legend items use the esriLegendItemArrangement enumeration which can be set with IHorizontalLegendItem::Arrangement and IVerticalLegendItem::Arrangement to specify the position of the label, patch, and description. The default is esriPatchLabelDescription, which translates to the patch on the far left, label to the right of the patch, then the description, if available, on the far right.
There are currently four types of legend items: HorizontalLegendItem, VerticalLegendItem, HorizontalBarLegendItem, and NestedLegendItem with corresponding interfaces.

Horizontal legend items are the default and most commonly used class of legend items.

Product Availability

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

Method Summary

void	createGraphics(IDisplay display, ILegendFormat legendFormat) Rebuilds the list of graphics.
short	getColumns() Number of columns in the legend item.
IEnumElement	getGraphics() List of graphics that represent the legend item.
int	getGroupIndex() Zero-based index of the legend group shown by this item.
ITextSymbol	getHeadingSymbol() Text symbol used to draw the heading.
double	getHeight() Height of the item in points.
ILayer	getLayer() Associated layer.
ITextSymbol	getLayerNameSymbol() Text symbol used to draw the layer name.
ILegendClassFormat	getLegendClassFormat() Default formatting information for the legend classes.
String	getName() Name of the style.
double	getWidth() Width of the item in points.
boolean	isCanDisplay(ILayer layer) Indicates if the style is compatible with the specified layer.
boolean	isKeepTogether() Indicates if classes must appear in a single column or whether they can be split across multiple columns.
boolean	isNewColumn() Indicates if the item starts a new column in the legend.
boolean	isShowDescriptions() Indicates if descriptions are visible.
boolean	isShowHeading() Indicates if heading is visibile.
boolean	isShowLabels() Indicates if labels are visible.
boolean	isShowLayerName() Indicates if layer name is visibile.
void	setColumns(short columns) Number of columns in the legend item.
void	setGroupIndex(int index) Zero-based index of the legend group shown by this item.
void	setHeadingSymbol(ITextSymbol symbol) Text symbol used to draw the heading.
void	setKeepTogether(boolean flag) Indicates if classes must appear in a single column or whether they can be split across multiple columns.
void	setLayerByRef(ILayer layer) Associated layer.
void	setLayerNameSymbol(ITextSymbol symbol) Text symbol used to draw the layer name.
void	setLegendClassFormat(ILegendClassFormat format) Default formatting information for the legend classes.
void	setNewColumn(boolean flag) Indicates if the item starts a new column in the legend.
void	setShowDescriptions(boolean showDescriptions) Indicates if descriptions are visible.
void	setShowHeading(boolean showHeading) Indicates if heading is visibile.
void	setShowLabels(boolean showLabels) Indicates if labels are visible.
void	setShowLayerName(boolean showLayerName) Indicates if layer name is visibile.

Method Detail

getName

String getName()
               throws IOException,
                      AutomationException

Name of the style.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The name

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isCanDisplay

boolean isCanDisplay(ILayer layer)
                     throws IOException,
                            AutomationException

Indicates if the style is compatible with 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:

The result

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getLayer

ILayer getLayer()
                throws IOException,
                       AutomationException

Associated layer.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

A reference to a com.esri.arcgis.carto.ILayer

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setLayerByRef

void setLayerByRef(ILayer layer)
                   throws IOException,
                          AutomationException

Associated layer.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

layer - A reference to a com.esri.arcgis.carto.ILayer (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isNewColumn

boolean isNewColumn()
                    throws IOException,
                           AutomationException

Indicates if the item starts a new column in the legend.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The flag

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setNewColumn

void setNewColumn(boolean flag)
                  throws IOException,
                         AutomationException

Indicates if the item starts a new column in the legend.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

flag - The flag (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getColumns

short getColumns()
                 throws IOException,
                        AutomationException

Number of columns in the legend item.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The columns

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setColumns

void setColumns(short columns)
                throws IOException,
                       AutomationException

Number of columns in the legend item.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

columns - The columns (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isKeepTogether

boolean isKeepTogether()
                       throws IOException,
                              AutomationException

Indicates if classes must appear in a single column or whether they can be split across multiple columns.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The flag

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setKeepTogether

void setKeepTogether(boolean flag)
                     throws IOException,
                            AutomationException

Indicates if classes must appear in a single column or whether they can be split across multiple columns.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

flag - The flag (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isShowLayerName

boolean isShowLayerName()
                        throws IOException,
                               AutomationException

Indicates if layer name is visibile.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The showLayerName

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setShowLayerName

void setShowLayerName(boolean showLayerName)
                      throws IOException,
                             AutomationException

Indicates if layer name is visibile.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

showLayerName - The showLayerName (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getLayerNameSymbol

ITextSymbol getLayerNameSymbol()
                               throws IOException,
                                      AutomationException

Text symbol used to draw the layer name.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

A reference to a com.esri.arcgis.display.ITextSymbol

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setLayerNameSymbol

void setLayerNameSymbol(ITextSymbol symbol)
                        throws IOException,
                               AutomationException

Text symbol used to draw the layer name.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

symbol - A reference to a com.esri.arcgis.display.ITextSymbol (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getGroupIndex

int getGroupIndex()
                  throws IOException,
                         AutomationException

Zero-based index of the legend group shown by this item. Use -1 to show all legend groups using this item.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The index

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setGroupIndex

void setGroupIndex(int index)
                   throws IOException,
                          AutomationException

Zero-based index of the legend group shown by this item. Use -1 to show all legend groups using this item.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

index - The index (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isShowHeading

boolean isShowHeading()
                      throws IOException,
                             AutomationException

Indicates if heading is visibile.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The showHeading

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setShowHeading

void setShowHeading(boolean showHeading)
                    throws IOException,
                           AutomationException

Indicates if heading is visibile.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

showHeading - The showHeading (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getHeadingSymbol

ITextSymbol getHeadingSymbol()
                             throws IOException,
                                    AutomationException

Text symbol used to draw the heading.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

A reference to a com.esri.arcgis.display.ITextSymbol

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setHeadingSymbol

void setHeadingSymbol(ITextSymbol symbol)
                      throws IOException,
                             AutomationException

Text symbol used to draw the heading.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

symbol - A reference to a com.esri.arcgis.display.ITextSymbol (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getLegendClassFormat

ILegendClassFormat getLegendClassFormat()
                                        throws IOException,
                                               AutomationException

Default formatting information for the legend classes. Renderer may override.

Description

The layer can provide legend class formatting information via ILegendClass.Format. This makes it possible to store legend formatting information with layers in metadata-like fashion. However, layers normally do not provide a LegendClassFormat object. Rather, legend formatting information usually comes from the legend. ILegendItem.LegendClassFormat is used and some patch settings can come from ILegend.LegendFormat .

So, when a legend is created, the code follows this logic:

1. Check if ILegendClass.Format exists for the layer. If not, use ILegendItem.LegendClassFormat.
2. For the patch settings, if a setting in ILegendItem.LegendClassFormat is null, then use the default value in ILegend.LegendFormat.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

A reference to a com.esri.arcgis.carto.ILegendClassFormat

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setLegendClassFormat

void setLegendClassFormat(ILegendClassFormat format)
                          throws IOException,
                                 AutomationException

Default formatting information for the legend classes. Renderer may override.

Description

The layer can provide legend class formatting information via ILegendClass.Format. This makes it possible to store legend formatting information with layers in metadata-like fashion. However, layers normally do not provide a LegendClassFormat object. Rather, legend formatting information usually comes from the legend. ILegendItem.LegendClassFormat is used and some patch settings can come from ILegend.LegendFormat .

So, when a legend is created, the code follows this logic:

1. Check if ILegendClass.Format exists for the layer. If not, use ILegendItem.LegendClassFormat.
2. For the patch settings, if a setting in ILegendItem.LegendClassFormat is null, then use the default value in ILegend.LegendFormat.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

format - A reference to a com.esri.arcgis.carto.ILegendClassFormat (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isShowLabels

boolean isShowLabels()
                     throws IOException,
                            AutomationException

Indicates if labels are visible.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The showLabels

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setShowLabels

void setShowLabels(boolean showLabels)
                   throws IOException,
                          AutomationException

Indicates if labels are visible.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

showLabels - The showLabels (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isShowDescriptions

boolean isShowDescriptions()
                           throws IOException,
                                  AutomationException

Indicates if descriptions are visible.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The showDescriptions

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setShowDescriptions

void setShowDescriptions(boolean showDescriptions)
                         throws IOException,
                                AutomationException

Indicates if descriptions are visible.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

showDescriptions - The showDescriptions (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

createGraphics

void createGraphics(IDisplay display,
                    ILegendFormat legendFormat)
                    throws IOException,
                           AutomationException

Rebuilds the list of graphics. Call whenever the associated layer changes.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

display - A reference to a com.esri.arcgis.display.IDisplay (in)

legendFormat - A reference to a com.esri.arcgis.carto.ILegendFormat (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getWidth

double getWidth()
                throws IOException,
                       AutomationException

Width of the item in points. Must call CreateGraphics first.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The width

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getHeight

double getHeight()
                 throws IOException,
                        AutomationException

Height of the item in points. Must call CreateGraphics first.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The height

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getGraphics

IEnumElement getGraphics()
                         throws IOException,
                                AutomationException

List of graphics that represent the legend item. Must call CreateGraphics first.

Description

Graphics are measured in points. The lower left corner is (0, 0). Put elements in groups to keep the legend from flowing them across columns.

Remarks

Each element in the graphic list should be flowable, i.e,. can be moved to a new column in the legend if necessary. Implement "keep together" by putting the elements that need to stay together in a group. The top level elements must be put in the list in top to bottom order.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

A reference to a com.esri.arcgis.carto.IEnumElement

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.