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.

Supported Platforms

Windows, Solaris, Linux


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.