com.esri.arcgis.carto
Interface IUniqueValueRenderer

All Superinterfaces:
Serializable
All Known Implementing Classes:
UniqueValueRenderer

public interface IUniqueValueRenderer
extends Serializable

Provides access to members that control a renderer where symbols are assigned to features based on unique attribute values.

Description

IUniqueValueRenderer is a way to show the features of a layer based on the unique values of one or more attributes.

Remarks

Use IUniqueValueRenderer to work with the properties of a UniqueValueRenderer.

This interface is used to manage the list of categories and symbols. Each unique Value in your data can define a unique category, represented with a single Symbol, and values can also be combined by grouping so that more than one value is symbolized with the same symbol. To work with grouping use AddReferenceValue and ReferenceValue. Also, Headings can be used to organize categories in the table of contents and legend, use Heading to assign a value to a particular heading.

Unique value renderering is typically based on a single attribute Field, however up to 3 fields can be used. When more than one field is used, the combinations of the unique values from each field are used to define the categories. So, for example if two fields are used which store the values A and B; and X, Y, and Z respectively, then the initial categories will be defined as A|X, A|Y, A|Z, B|X, B|Y, and B|Z.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux


Method Summary
 void addReferenceValue(String value, String refValue)
          Adds a value to the renderer to be grouped with refValue, which has already been added to the renderer.
 void addValue(String value, String heading, ISymbol symbol)
          Adds a value and corresponding symbol to the list.
 String getColorScheme()
          Color scheme (user interface property only).
 String getDefaultLabel()
          Label used for unspecified values.
 ISymbol getDefaultSymbol()
          Symbol used to draw any unspecified values (may be NULL).
 String getDescription(String value)
          Desription for the specified label.
 String getField(int index)
          Field at the specified index that is used to categorize features.
 int getFieldCount()
          Number of fields used by the renderer (0-3).
 String getFieldDelimiter()
          Delimiter used to separate field values.
 String getHeading(String value)
          Heading that contains the specified value.
 String getLabel(String value)
          Label for the specified value.
 String getLookupStyleset()
          Style used for matching (user interface property only).
 String getReferenceValue(String value)
          Reference value for the specified value.
 ISymbol getSymbol(String value)
          Symbol associated with the specified value.
 String getValue(int index)
          Value at the specified index.
 int getValueCount()
          Number of unique values used to categorize the data.
 boolean isUseDefaultSymbol()
          Indicates if DefaultSymbol is used for drawing unspecified values.
 void removeAllValues()
          Removes all values from the renderer.
 void removeValue(String value)
          Removes a value from the renderer.
 void setColorScheme(String name)
          Color scheme (user interface property only).
 void setDefaultLabel(String label)
          Label used for unspecified values.
 void setDefaultSymbol(ISymbol symbol)
          Symbol used to draw any unspecified values (may be NULL).
 void setDescription(String value, String text)
          Desription for the specified label.
 void setField(int index, String field)
          Field at the specified index that is used to categorize features.
 void setFieldCount(int fieldCount)
          Number of fields used by the renderer (0-3).
 void setFieldDelimiter(String delimiter)
          Delimiter used to separate field values.
 void setFieldType(int index, boolean rhs2)
          Indicates if the field at the specified index is a string.
 void setHeading(String value, String heading)
          Heading that contains the specified value.
 void setLabel(String value, String label)
          Label for the specified value.
 void setLookupStyleset(String name)
          Style used for matching (user interface property only).
 void setSymbol(String value, ISymbol symbol)
          Symbol associated with the specified value.
 void setUseDefaultSymbol(boolean flag)
          Indicates if DefaultSymbol is used for drawing unspecified values.
 void setValue(int index, String value)
          Value at the specified index.
 

Method Detail

getField

String getField(int index)
                throws IOException,
                       AutomationException
Field at the specified index that is used to categorize features.

Product Availability

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

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

setField

void setField(int index,
              String field)
              throws IOException,
                     AutomationException
Field at the specified index that is used to categorize features.

Product Availability

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

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

setFieldType

void setFieldType(int index,
                  boolean rhs2)
                  throws IOException,
                         AutomationException
Indicates if the field at the specified index is a string.

Product Availability

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

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

getFieldDelimiter

String getFieldDelimiter()
                         throws IOException,
                                AutomationException
Delimiter used to separate field values.

Description

FieldDelimiter is the string that is inserted between the values of different fields, when more than one field is specified.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

setFieldDelimiter

void setFieldDelimiter(String delimiter)
                       throws IOException,
                              AutomationException
Delimiter used to separate field values.

Description

FieldDelimiter is the string that is inserted between the values of different fields, when more than one field is specified.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getFieldCount

int getFieldCount()
                  throws IOException,
                         AutomationException
Number of fields used by the renderer (0-3).

Description

FieldCount is the number of fields in the Field collection.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

setFieldCount

void setFieldCount(int fieldCount)
                   throws IOException,
                          AutomationException
Number of fields used by the renderer (0-3).

Description

FieldCount is the number of fields in the Field collection.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getDefaultSymbol

ISymbol getDefaultSymbol()
                         throws IOException,
                                AutomationException
Symbol used to draw any unspecified values (may be NULL).

Description

The symbol used to represent all attribute values that have not been added to the renderer.

Remarks

Values that have not been added to the renderer object can be drawn according to the symbol set for this property. To enable the drawing of this symbol you must also set UseDefaultSymbol = True. Access the label for the default symbol through DefaultLabel.

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

setDefaultSymbol

void setDefaultSymbol(ISymbol symbol)
                      throws IOException,
                             AutomationException
Symbol used to draw any unspecified values (may be NULL).

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

getDefaultLabel

String getDefaultLabel()
                       throws IOException,
                              AutomationException
Label used for unspecified values.

Description

DefaultLabel is the label used for the DefaultSymbol in the table of contents.
To change the DefaultLabel for an existing UniqueValueRenderer that is using a DefaultSymbol(has UseDefaultSymbol = True), you must set UseDefaultSymbol = False and then back to True to properly update the renderer's entry in the ArcMap table of contents.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

setDefaultLabel

void setDefaultLabel(String label)
                     throws IOException,
                            AutomationException
Label used for unspecified values.

Description

DefaultLabel is the label used for the DefaultSymbol in the table of contents.
To change the DefaultLabel for an existing UniqueValueRenderer that is using a DefaultSymbol(has UseDefaultSymbol = True), you must set UseDefaultSymbol = False and then back to True to properly update the renderer's entry in the ArcMap table of contents.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

isUseDefaultSymbol

boolean isUseDefaultSymbol()
                           throws IOException,
                                  AutomationException
Indicates if DefaultSymbol is used for drawing unspecified values.

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.

setUseDefaultSymbol

void setUseDefaultSymbol(boolean flag)
                         throws IOException,
                                AutomationException
Indicates if DefaultSymbol is used for drawing unspecified values.

Description

UseDefaultSymbol is the symbol used to represent all attribute values that have not been added using with the AddValue or AddReferenceValue methods.

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.

getValueCount

int getValueCount()
                  throws IOException,
                         AutomationException
Number of unique values used to categorize the data.

Description

The number of unique values defined for the renderer.

Remarks

To iterate through all of the renderer values, use the Value property and iterate from index 0 through index ValueCount - 1.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getValue

String getValue(int index)
                throws IOException,
                       AutomationException
Value at the specified index.

Product Availability

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

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

setValue

void setValue(int index,
              String value)
              throws IOException,
                     AutomationException
Value at the specified index.

Product Availability

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

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

getReferenceValue

String getReferenceValue(String value)
                         throws IOException,
                                AutomationException
Reference value for the specified value.

Product Availability

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

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

addReferenceValue

void addReferenceValue(String value,
                       String refValue)
                       throws IOException,
                              AutomationException
Adds a value to the renderer to be grouped with refValue, which has already been added to the renderer.

Description

Adds the specified value to an existing renderer category. Use this method to specify that the Value parameter will be assigned the same symbol as an existing renderer Value, corresponding to the RefVal parameter. In ArcMap values that are drawn with the same symbol are said to be grouped.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getSymbol

ISymbol getSymbol(String value)
                  throws IOException,
                         AutomationException
Symbol associated with the specified value.

Product Availability

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

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

setSymbol

void setSymbol(String value,
               ISymbol symbol)
               throws IOException,
                      AutomationException
Symbol associated with the specified value.

Product Availability

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

Parameters:
value - The value (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.

getLabel

String getLabel(String value)
                throws IOException,
                       AutomationException
Label for the specified value.

Product Availability

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

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

setLabel

void setLabel(String value,
              String label)
              throws IOException,
                     AutomationException
Label for the specified value.

Product Availability

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

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

getDescription

String getDescription(String value)
                      throws IOException,
                             AutomationException
Desription for the specified label.

Product Availability

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

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

setDescription

void setDescription(String value,
                    String text)
                    throws IOException,
                           AutomationException
Desription for the specified label.

Product Availability

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

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

getHeading

String getHeading(String value)
                  throws IOException,
                         AutomationException
Heading that contains the specified value.

Product Availability

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

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

setHeading

void setHeading(String value,
                String heading)
                throws IOException,
                       AutomationException
Heading that contains the specified value.

Product Availability

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

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

addValue

void addValue(String value,
              String heading,
              ISymbol symbol)
              throws IOException,
                     AutomationException
Adds a value and corresponding symbol to the list. For multivariate cases, the specified value is a delimitted list of individual values.

Description

Adds a value and symbol to the list of unique values.

Remarks

After setting FieldCount and setting at least one Field, use this method to add a unique value and corresponding symbol to the renderer. You can later retrieve and/or change the symbol for particular value using the Symbol property.

If you pass a Value that already exists in the renderer, then the existing symbol for the Value will be replaced by the object passed as the Symbol parameter.

If FieldCount > 1 then the Value you pass should be a list of values, one for each field, separated by the FieldDelimitter. By default this is a comma.

To add a value to the renderer, and have that value be drawn with the same symbol as another existing value or values, use AddReferenceValue instead of AddValue. When more than one value is drawn with the same symbol, the values are said to be grouped.

Null Values

At ArcGIS versions 8.2 and later, special behavior was added to the UniqueValueRenderer to handle Null values. If you add the special value "<Null>" to your renderer and your database supports Nulls, then features where Field = Null will be drawn with the "<Null>" symbol.

The "<Null>" symbol may also be used in table join situations. With joins that keep unmatched records, ArcMap inserts artificial Nulls into the virtual join table. Features with these values will also be drawn with the "<Null>" UniqueValueRenderer symbol.
International users working with a localized version of ArcGIS should add the localized version of the string "<Null>" to get the special behaviors described above.
See the associated Example to see how to scan a feature class for unique values and then add them to a UniqueValueRenderer.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
value - The value (in)
heading - The heading (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.

removeValue

void removeValue(String value)
                 throws IOException,
                        AutomationException
Removes a value from the renderer.

Description

Removes the value at the specified index from the list of values.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

removeAllValues

void removeAllValues()
                     throws IOException,
                            AutomationException
Removes all values from the renderer.

Description

Removes all the values from the renderer.

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.

getColorScheme

String getColorScheme()
                      throws IOException,
                             AutomationException
Color scheme (user interface property only).

Description

The name of the IRandomColorRamp that is associated with the renderer. This property does not alter any of the renderer symbols, nor does it affect how the renderer draws features. The property is only used by the user interface framework to indicate which color scheme was used to generate the symbols for the renderer.

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.

setColorScheme

void setColorScheme(String name)
                    throws IOException,
                           AutomationException
Color scheme (user interface property only).

Description

ColorScheme is the name of the IRandomColorRamp that is associated with the IUniqueValueRenderer . This property does not set or alter any of the symbols for the values in the IUniqueValueRenderer , it is only used by the user interface to indicate which color scheme was used.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getLookupStyleset

String getLookupStyleset()
                         throws IOException,
                                AutomationException
Style used for matching (user interface property only).

Description

The name of the Style shown on the LookupSymbolPropertyPage. This property is only used by the user interface framework when the 'Match to symbols in a style' layer symbology option is used. This is the name of the style containing the symbols that are matched to unique values in the data to create categories on the renderer. The logic to perform this matching is not exposed as a particular ArcObjects method or set of methods.

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.

setLookupStyleset

void setLookupStyleset(String name)
                       throws IOException,
                              AutomationException
Style used for matching (user interface property only).

Description

LookupStyleset is the name of a Style that is used by the IUniqueValueRenderer . This is only used by the user interface for display purposes. If you want to mimic the behavior of the user interface, you will have to open the style a database , and return its recordset and match the values in one of its name fields to the values in your IUniqueValueRenderer .

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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