Skip To Content

Working with symbols and renderers

In this topic

Symbols define the non-geographic aspects of a graphic's appearance. This includes a graphic's color, border width, transparency, and more. The ArcGIS Runtime SDK for OS X includes many symbol classes, each of which allows you to specify symbology in a unique way. Each symbol type is also specific to one geometry type (that is, point, line, or polygon).

Renderers define sets of symbols to apply to a Graphics layer. The symbol applied to each graphic depends on the graphic's attributes. The renderer specifies which attribute values correspond to which symbol.

Symbol types

The available symbols and the geometries to which they apply are summarized in the following table:

SymbolGeometryDescriptionSymbol class

Simple Marker

Point

Symbolizes points with simple shapes.

AGSSimpleMarkerSymbol

Picture Marker

Point

Symbolizes points with images.

AGSPictureMarkerSymbol

Simple Line

Polyline

Symbolizes lines with pre-defined styles.

AGSSimpleLineSymbol

Composite

Point, Polyline, or Polygon

Symbolizes geometries with an array of symbols.

AGSCompositeSymbol

Simple Fill

Polygon

Fills polygons with a variety of patterns.

AGSSimpleFillSymbol

Text

Point, Polyline, or Polygon

Displays text labels for geometries.

AGSTextSymbol

All the symbol classes mentioned here inherit from AGSSymbol.

Creating symbols

In many applications, the same symbol will be used multiple times. Consider, for instance, an application that uses the Find task to allow users to search for counties. In this situation, it makes sense to apply the same symbology to the task's results every time the task is executed. In such cases, you should store a reference to the object in an instance variable/property in your class.

The following code creates an AGSSimpleMarkerSymbol drawn as a blue diamond with a white, three pixel-wide white outline:

//Create the AGSSimpleMarker Symbol and set some properties
AGSSimpleMarkerSymbol* myMarkerSymbol = [AGSSimpleMarkerSymbol simpleMarkerSymbol];
myMarkerSymbol.color = [NSColor blueColor];
myMarkerSymbol.style = AGSSimpleMarkerSymbolStyleDiamond;
myMarkerSymbol.outline.color = [NSColor whiteColor];
myMarkerSymbol.outline.width = 3;

The following code creates an AGSSimpleFillSymbol with a semi-transparent red fill and a red outline that is two pixels wide. The outline for a simple fill symbol is an AGSSimpleLineSymbol.

//Create the AGSSimpleFillSymbol and set it’s color
AGSSimpleFillSymbol* myFillSymbol = [AGSSimpleFillSymbol simpleFillSymbol];
myFillSymbol.color = [NSColor colorWithRed:0.7 green:0.1 blue:0.1 alpha:0.5];

//Create the AGSSimpleLineSymbol used for the outline
AGSSimpleLineSymbol* myOutlineSymbol = [AGSSimpleLineSymbol simpleLineSymbol];
myOutlineSymbol.color = [NSColor redColor];
myOutlineSymbol.width = 2;

//set the outline property to myOutlineSymbol
myFillSymbol.outline = myOutlineSymbol;

Now that the symbol is declared, you can attach it to a graphic or use it in a renderer.

Renderers

A renderer defines a set of symbols that will be used for graphics in a Graphics layer. You can use renderers to symbolize features with different colors or sizes based on a the graphic's attribute values. To use a renderer, you create it, define the symbology, then set the renderer property of a Graphics layer.

myGraphicsLayer.renderer = myRenderer;

Creating a simple renderer

A simple renderer uses the same symbol for every graphic. All you need to do is create the renderer with the desired symbol, then set it as the Graphics layer’s renderer property.

AGSSimpleRenderer* mySimpleRenderer = [AGSSimpleRenderer
simpleRendererWithSymbol:myMarkerSymbol];
myGraphicsLayer.renderer = mySimpleRenderer;

The symbol property on AGSSimpleRenderer is read-only. To use a symbol with a simple renderer, you must create a renderer with the desired symbol. Also, the symbol type needs to match the feature type (marker symbols for point features, line symbols for polyline features, and fill symbols for polygon features).

Creating a class breaks renderer

A class breaks renderer symbolizes each graphic based on the value of some numeric attribute. Graphics with similar values for the attribute get the same symbol. The "breaks" define the values at which the symbology changes.

The mapping between symbols and values is defined in an array of AGSClassBreak objects. The AGSClassBreaksRenderer stores this in its classBreaks property as an array of AGSClassBreak objects. The AGSClassBreak object contains the symbol used to draw the graphic, a minimum value, and a maximum value. Any value greater than or equal to the minimum value and less than the maximum value is drawn using the class break symbol.

The following code creates an AGSClassBreaksRenderer to symbolize cities according to size. There are three class breaks: the first is from DBL_MIN to 50,000, the second is from 50,000 to 250,000, the last is from 250,000 to DBL_MAX.

//create the renderer with a default simple marker symbol  
//and an attribute field.  
AGSClassBreaksRenderer *cityRenderer = [[[AGSClassBreaksRenderer alloc] init] autorelease];  
cityRenderer.field = @"POP1990";  
cityRenderer.minValue = DBL_MIN;      

//create three AGSClassBreak objects, one each for  
//low, medium and high populations and the appropriate  
//symbol (for clarity, the symbol creation has been omitted)  
AGSClassBreak* lowClassBreak = [AGSClassBreak classBreakInfoWithLabel:@"Low" description:@"" maxValue:50000 symbol:lowMarkerSymbol];    
AGSClassBreak* mediumClassBreak =[AGSClassBreak classBreakInfoWithLabel:@"Medium" description:@"" maxValue:250000 symbol:mediumMarkerSymbol];    
AGSClassBreak* highClassBreak = [AGSClassBreak classBreakInfoWithLabel:@"High" description:@"" maxValue:DBL_MAX symbol:highMarkerSymbol];    

//add the AGSClassBreak objects to the renderer   
NSMutableArray* classBreaks = [NSMutableArray array];
[classBreaks addObject:lowClassBreak];   
[classBreaks addObject:mediumClassBreak];
[classBreaks addObject:highClassBreak];        
cityRenderer.classBreaks = classBreaks;


//add the renderer to the graphics layer  
citiesGraphicsLayer.renderer = cityRenderer;

Creating a unique value renderer

A unique value renderer symbolizes groups of graphics that have matching attributes. This is most common with nominal, or string data. For example, you can use a unique value renderer to symbolize zoning designations: yellow for Residential, purple for Industrial, red for Commercial, and so on. You can also use unique value renderers on numeric fields that are coded values, or on ordinal attributes such as First, Second, Third, and so on.

The following code creates an AGSUniqueValueRenderer for symbolizing cities with three values: VILLAGE, CITY, and TOWN, each with a unique symbol to represent the TYPE attribute field (the creation of the symbols has been omitted for clarity):

//create the renderer  
//specify the attribute field whose values will decide the symbol 
//we need to provide a default symbol for unmatched values
AGSUniqueValueRenderer *cityRenderer = [[[AGSUniqueValueRenderer alloc] init] autorelease];  
cityRenderer.defaultSymbol = defaultMakerSymbol;  
cityRenderer.field1 = @"TYPE";      

//create three AGSUniqueValue objects, one each for  
//CITY, TOWN, and VILLAGE 
AGSUniqueValue* village = [[AGSUniqueValue alloc] initWithValue:@"VILLAGE" label:@"village" description:nil symbol:villageSymbol];  
AGSUniqueValue* city = [[AGSUniqueValue alloc] initWithValue:@"CITY" label:@"city" description:nil symbol:citySymbol];  
AGSUniqueValue* town = [[AGSUniqueValue alloc] initWithValue:@"TOWN" label:@"town" description:nil symbol:townSymbol];    

//add the AGSUniqueValue objects to the renderer
[cityRenderer.uniqueValues addObject:village];  
[cityRenderer.uniqueValues addObject:city];  
[cityRenderer.uniqueValues addObject:town];    

//add the renderer to the graphics layer  
citiesGraphicsLayer.renderer = cityRenderer;

The object in the setObject method above is the symbol and the key is the attribute that symbol will represent. The attributes are members of the attribute field specified in the AGSUniqueValueRenderer uniqueValueRendererWithDefaultSymbol method.

Remember, for all renderer variations, the symbol type needs to match the feature type: marker symbols for point features, line symbols for polyline features, and fill symbols for polygon features.

Change rendering for a dynamic layer

With ArcGIS for Server version 10.1 or greater, dynamic layers provide the ability to change rendering on the client for data coming from an ArcGIS for Server (non-cached) map service. Setting layer definitions and draw options on a dynamic layer allows you to control the content and the display of sub-layers within the service.

Generate a renderer on the server

For layers from services created with ArcGIS for Server version 10.1 or later, you can use a GenerateRendererTask to generate and return either a class breaks or a unique value renderer. The generated renderer can then be applied to the corresponding dynamic layer in your map.

Creating a unique value renderer using the task gives you the ability to specify a color ramp from which a unique color can be retrieved for each unique symbol in the renderer. Generating a renderer for a feature layer with several unique values using GenerateRendererTask is more efficient than writing code to explicitly define each class in the renderer.

Generating a class breaks renderer with the task gives you the ability to use statistical classification methods to determine your class ranges. Rather than manually coding the minimum and maximum values for your class breaks, you can specify the number of breaks desired and use one of the following classification methods to determine the values for each break: Natural Breaks, Equal Interval, Quantile, or Standard Deviation. You can also choose to normalize your data by percent of the total, the value of another field, or by log.