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.

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.