How to implement custom feature renderers

• About implementing custom feature renderers
• Developing custom feature renderers
• IFeatureRenderer methods
• canRender
• isRenderPhase
• setExclusionSetByRef
• prepareFilter
• draw
• getSymbolByFeature
• What's Next

About implementing custom feature renderers

Developing custom feature renderers

//Step 2: Annotate the class with @ArcGISExtension. 
@ArcGISExtension 
//Step 1: Create Java class that implements IFeatureRenderer.
public class FirstCustomRenderer implements IFeatureRenderer{
    //Step 3: Implement methods.
}

IFeatureRenderer methods

canRender

• Significance—canRender lets you enforce conditions based on the feature class and display properties of the feature layer to apply the custom renderer . If the specified conditions of the custom renderer are not met, the method will not return a value of true and the renderer will not be applied to the feature layer by the ArcGIS framework. For example, a custom renderer designed for networks can verify the layer's feature class contains a particular type of network feature by checking its IFeatureClass.getFeatureType() property in its canRender method. In the following code example, the canRender method implementation verifies the shape feature of the feature class is a point feature. If your custom renderer is designed for point features, this method's implementation prevents it from being applied to feature layers with line or polygon shape types. 

public boolean canRender(IFeatureClass fc, IDisplay display)throws IOException,
    AutomationException{
    if (fc.getShapeType() == esriGeometryType.esriGeometryPoint)
        return true;
    else
        return false;
}

isRenderPhase

• Significance—The feature layer can be rendered in any or all of the three draw phases (that is, esriDPGeography, esriDPAnnotation, and esriDPSelection). Allowing the renderer to draw in all phases slows the rendering of the feature layer. Typically, all renderers are drawn in the geography phase (esriDPGeography). However the feature rendering can be manipulated to be rendered in multiple phases too. For example, the ArcGIS renderer, ProportionalSymbolRenderer, draws the background fill symbol during the geography phase and the proportionally sized marker symbol during the annotation phase. If there are selected features in the layer being rendered, all feature layer will be rendered for the selection phase by default irrespective of the value returned by the isRenderPhase() method. The following code example shows the isRenderPhase() method implementation where the renderer is restricted to be drawn only in the esriGeography phase:

public boolean isRenderPhase(int drawPhase){
    if (drawPhase == esriDrawPhase.esriDPGeography)
        return true;
    else
        return false;
}

setExclusionSetByRef

• Significance—The significance of providing exclusion data to the framework is to eliminate erroneous values from rendering. For example, you might exclude features with values less than or equal to zero from drawing. Also, you might exclude other special values, such as null values. If applicable, you can choose to draw these excluded features with a unique symbol, and have that symbol labeled in the TOC and legend.
  

prepareFilter

• Significance—The prepareFilter method lets you specify the fields your renderer needs to draw. It is recommended to create specific fields for rendering since ArcMap renders data faster when the rendering is based on its fields, rather than calculating or programmatically deriving values. In the four-color map problem, it would be too slow if the renderer was responsible for figuring out the color to draw for each feature, when the map is drawn. In this case, create a color field calculate and populate its values to allow ArcMap to render the data faster. Also remember, ArcMap renders data based on an integer field faster than it would if the field was a text data type. This is true for ArcSDE geodatabases, since less data has to be interpreted and transferred over the network.

public void prepareFilter(IFeatureClass fc, IQueryFilter qFilter)throws IOException,
    AutomationException{

    //Get fields from the feature class.
    IFields fields = fc.getFields();

    //Add all fields to the query filter.
    for (int i = 0; i < fields.getFieldCount(); i++)
        qFilter.addField(fields.getField(i).getName());

    //If an exclusion set is specified by the setExclusionSetByRef() method, 
    //make sure the ObjectID field is present.

    if (exclusionSet != null){
        if (exclusionSet.getCount() > 0){
            qFilter.addField(fc.getOIDFieldName());
        }
    }
}

draw

• Significance—The draw() method receives a featureCursor indicating the features to draw. The implementation of the draw() method must draw the specified symbol for the features by invoking IFeatureDraw.draw() on each feature. Other relevant text symbols accompanying the features, as in custom ValenceRenderers, can be drawn using IDisplay.drawText(), which draws adjacent to the feature.
  
  Remember, the featureCursor only contains features within the current display extent. Since, the queryFilter is used to fetch features, a spatial filter with the display extent is used to limit the features returned. However, there are usually more features in the cursor than in the display extent, since the spatial filter criteria is set against the spatial index rather than the feature geometries.  The renderer draws these offscreen features since it is more efficient to draw than to have a slower query. When data has no spatial index (for example, some shapefiles), all the features in the dataset will be fetched in the feature cursor. Therefore, you might find features in the cursor that are not within the current display extent. It is more efficient to draw these features than to check their extent. ArcGIS has produced the query for speed of execution. In the following code example, the simple renderer loops through the feature cursor and draws features by invoking IFeatureDraw.draw(): 

//draw method of IFeatureRenderer that draws the feature.
public void draw(IFeatureCursor featureCursor, int drawPhase, IDisplay display,
    ITrackCancel trackCancel)throws IOException, AutomationException{

    //declare local variable to to track cancel
    boolean bContinue = false;
    // Do not draw features if there is no display or incorrect drawPhase.
    if (display == null || drawPhase != esriDrawPhase.esriDPGeography)
        return ;

    //Create and set the display symbol to represent the features.
    //Set the display symbol. 
    CharacterMarkerSymbol markerSym = new CharacterMarkerSymbol();
    markerSym.setCharacterIndex(72);
    markerSym.setSize(12.0);
    IColor redColor = new RgbColor();
    redColor.setRGB(0xFF0000);
    markerSym.setColor(redColor);
    display.setSymbol(markerSym);

    //Verify Track Cancel
    if (trackCancel != null)
        bContinue = trackCancel.esri_continue();

    //Loop through the features and draw them using the display symbol.
    IFeature feature = featureCursor.nextFeature();
    while ((feature != null) && (bcontinue == true)){
        IFeatureDraw featureDraw = (IFeatureDraw)feature;
        featureDraw.draw(drawPhase, display, markerSym, false, null,
            esriDrawStyle.esriDSNormal);
        feature = featureCursor.nextFeature();
        bContinue = trackCancel.esri_continue();
    }
}

getSymbolByFeature

• Significance—Using getSymbolByFeature enables the possibility to contain other renderers within your custom renderer. For example, instead of using a single symbol to disperse points, use another symbology option, such as proportional symbols or unique values. This can be achieved by keeping a reference to a contained renderer class (the custom renderer), then for each feature in the draw loop, calling getSymbolByFeature on the contained renderer to determine the symbol to use.
  

What's Next

See Also: