com.esri.arcgis.carto
Interface ISymbolSubstitution

All Superinterfaces:
Serializable
All Known Implementing Classes:
FDOGraphicsLayer

public interface ISymbolSubstitution
extends Serializable

Provides access to members that control dynamic symbol substitution for display.

Remarks

ISymbolSubstitution provides access to the properties which control the display of annotation using Symbol Substitution. Unlike FeatureLayers, Annotation Layers (FDOGraphicsLayers) use symbology stored in the geodatabase for drawing. Typically, the data needs to be edited in order to change the appearance of an annotation. To help with this issue, Symbol Substitution allows for the alteration of text symbology used when displaying annotation layers (FDOGraphicsLayers ). Symbol Substitution properties are layer based and persisted with the layer, therefore no editing of the data is needed.

There are four types of Symbol Substitution:
esriSymbolSubstituteNone - Do not substitute symbols (the default).
esriSymbolSubstituteColor - Substitute only the color.
esriSymbolSubstituteIndividualSubordinate - Substitute individual symbols in the collection with overrides taking precedence to symbols.
esriSymbolSubstituteIndividualDominant - Substitute individual symbols in the collection with the symbol taking precedence to overrides.

The type of Symbol Substitution used can be set using ISymbolSubstitution::SubstituteType. Substitution type esriSymbolSubstituteColor uses the color set as the MassColor property to draw all text in the layer with that color. Substitution types esriSymbolSubstituteIndividualSubordinate and esriSymbolSubstituteIndividualDominant use a SymbolCollection set in the SubstituteSymbolCollection property to draw annotation features that references a symbol in the symbol collection with a different base symbol. Text that does not reference a symbol in the symbol collection can optionally be drawn with a color when an color is set using the InlineColor property.

The difference between Symbol Substitution types esriSymbolSubstituteIndividualSubordinate and esriSymbolSubstituteIndividualDominant is in how the substitution is performed when the annotation feature contains TextSymbol overrides. When substitution type esriSymbolSubstituteIndividualSubordinate is chosen, the text is drawn with the symbol from the substitute symbol collection and the overrides are applied to this symbol. When substitution type esriSymbolSubstituteIndividualDominant is chosen, the text is drawn just with the symbol from the substitute SymbolCollection and the overrides are ignored.

To properly create a substitute SymbolCollection, the collection must contain symbols at the same index as the symbol that you wish to substitute. For instance, if an annotation feature class has a SymbolCollection with 3 symbols indexed from 1 to 3. To substitute only symbol number 2, a new SymbolCollection should be cocreated, the substitute TextSymbol should be stored at position 2 in the SymbolCollection, and the collection should be set as the SubstituteSymbolCollection for the annotation layer.

For more on the concept of text symbol overrides, consult the documentation for Interface ISymbolCollectionElement which contains a more thorough explanation of the concept.


Product Availability

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

Supported Platforms

Windows, Solaris, Linux


Method Summary
 IColor getInlineColor()
          The color used for substituting symbols that do not reference the symbol collection.
 IColor getMassColor()
          The color used for substituting only the color.
 ISymbolCollection getSubstituteSymbolCollection()
          The substitute symbol collection when substituting the entire collection.
 int getSubstituteType()
          The type of symbol substitution.
 void setInlineColorByRef(IColor color)
          The color used for substituting symbols that do not reference the symbol collection.
 void setMassColorByRef(IColor color)
          The color used for substituting only the color.
 void setSubstituteSymbolCollectionByRef(ISymbolCollection symbolCollection)
          The substitute symbol collection when substituting the entire collection.
 void setSubstituteType(int substituteType)
          The type of symbol substitution.
 

Method Detail

getMassColor

IColor getMassColor()
                    throws IOException,
                           AutomationException
The color used for substituting only the color.

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.IColor
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setMassColorByRef

void setMassColorByRef(IColor color)
                       throws IOException,
                              AutomationException
The color used for substituting only the color.

Product Availability

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

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

getInlineColor

IColor getInlineColor()
                      throws IOException,
                             AutomationException
The color used for substituting symbols that do not reference the symbol collection.

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.IColor
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setInlineColorByRef

void setInlineColorByRef(IColor color)
                         throws IOException,
                                AutomationException
The color used for substituting symbols that do not reference the symbol collection.

Product Availability

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

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

getSubstituteSymbolCollection

ISymbolCollection getSubstituteSymbolCollection()
                                                throws IOException,
                                                       AutomationException
The substitute symbol collection when substituting the entire collection.

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.ISymbolCollection
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSubstituteSymbolCollectionByRef

void setSubstituteSymbolCollectionByRef(ISymbolCollection symbolCollection)
                                        throws IOException,
                                               AutomationException
The substitute symbol collection when substituting the entire collection.

Product Availability

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

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

getSubstituteType

int getSubstituteType()
                      throws IOException,
                             AutomationException
The type of symbol substitution.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A com.esri.arcgis.carto.esriSymbolSubstituteType constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSubstituteType

void setSubstituteType(int substituteType)
                       throws IOException,
                              AutomationException
The type of symbol substitution.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
substituteType - A com.esri.arcgis.carto.esriSymbolSubstituteType constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.