Getting started with a custom feature renderer

In this topic

---

The ArcGIS framework allows visualization of maps through layers, renderers, map surrounds, labels and annotations. ArcGIS framework uses layers to represent geographic data and renderers to control how data shows (renders) on a map. Feature renderers display features of a feature layer on a map. ArcGIS supports nine out-of-the-box feature renderers. These feature renderers can be applied to a feature layer to meet aesthetic visualization requirements and to modify the symbology of the features to show additional information about other attributes of the layer. An example of an ArcGIS feature renderer is ClassBreaksRenderer. Use ClassBreaksRenderer to visualize features in a feature layer and to show quantitative data information for one of its attributes. The following illustration shows the African States feature layer rendered by ClassBreaksRenderer. The gradation of the states' color represents the population quantity information for African states. For more about ArcGIS feature renderers, see Exploring ArcGIS custom feature renderers.

You can create a custom feature renderer if none of the nine ArcGIS renderers meet your requirements. Use custom feature renderers to control how each feature in a layer is symbolized to show meaningful information about the data.

The following table shows some custom feature renderers:

Custom feature renderer	Explanation
	BivariateRenderer—Produces bivariate representations of a feature layer that exceeds the functionality of the standard biunique value renderer. The illustration shows the size and color of the state capitals' feature representation, which indicates population and elevation above sea level.
	MZRenderer—Shows measures or z-values at vertices of a line feature.
	Silver Polygon renderer—Shows specific symbols between polygons to indicate data errors.
	Valence renderer—Symbolizes network junctions with the number of network edges that meet at the junction.

Implement a custom feature renderer by developing a Java class that implements IFeatureRenderer. Annotate the Java class with @ArcGISExtension and deploy the annotation to ArcGIS. Once deployed, the custom feature renderer can be consumed in ArcGIS Desktop, ArcGIS Engine, and ArcGIS Server applications like other ArcGIS renderers. For more information about implementing custom feature renderers, see How to implement custom feature renderers and Building custom feature renderers in the Eclipse IDE. When implementing a custom Feature Renderer, you must consider the following criteria for your implementation.

Implementing persistence for a custom feature renderer is essential since it allows you to preserve the state of the renderer on a map document or layer (.lyr) file. When the map document is closed, the instance of the renderer is terminated. However, if the custom feature renderer implemented persistence for its renderer instance, the state of the renderer will be written to a persistent storage medium or a file when the map is saved and closed. When the document is reopened, the state of the rendered object will be recreated by the ArcGIS framework as it was preserved. For more information about persistence, see Implementing persistence and version compatibility.

Use version compatibility if your custom feature renderer can be persisted. The concept of version compatibility, introduced with ArcGIS 9.1 onwards, allows you to save (persist) map documents to previous ArcGIS versions. The saved documents can then be opened with a version of ArcGIS to which the document was saved.

However, custom feature renderers when saved (persisted) in documents before ArcGIS 9.3.1 cannot be rendered by ArcGIS and the corresponding feature layer will not be rendered in the map. To avoid such scenarios, implement version compatibility and provide an alternative ArcGIS feature renderer. The ArcGIS framework will persist the alternative ArcGIS feature renderer when saved to previous versions of ArcGIS 9.3.1. For more information about version compatibility, see Implementing persistence and version compatibility.

Custom feature renderers annotated with @ArcGISExtension and deployed to ArcGIS can be accessed in ArcGIS Desktop by developing custom property pages. Property page implementation provides the necessary user interface to allow you to set the properties of the custom renderer and apply the renderer to a feature layer. For more information about implementing property pages, see How to implement custom property pages for custom feature renderers.

Legends in the table of contents (TOC) provide textual descriptions of the symbology used in your custom renderer. Implement TOC legends to ensure the TOC and legends in your map documents (and in ArcMap) show a list of symbols, labels, and headings that correspond to your custom feature renderer. For more information about implementing TOC legends, see How to implement TOC legends for custom feature renderers.