Skip To Content

Creating a Graphics layer

In this topic

Graphics layers allow you to dynamically display graphics on a map. A Graphics layer could, for example, be used to hold polygons or lines drawn by a user, or display features that satisfy the results of a task such as query or geoprocessing. In the image below, a Graphics layer is used to highlight states that have a population density of more than 200 per square mile:

CreateGraphics

When you want to add a Graphics layer to the map, use the AGSGraphicsLayer class to create your layer. Instances of this class contain a list of graphics and an optional renderer (AGSRenderer). There are also methods for adding, removing, and redrawing graphics. Be sure to add the Graphics layer after any base layers so that graphics display above those layers when you run your application. For more information, refer to the layer types .

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 iOS 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.

Adding a graphics layer

If you have not already done so, create an application with a map as described in Add a map to your app, then create your layer as follows:

let myGraphicsLayer = AGSGraphicsLayer()

If you want to reference your new Graphics layer in another method, you can create an instance variable in your class to hold the Graphics layer.

To add the new Graphics layer to the map, use the AGSMapView method, addMapLayer:

self.mapView.addMapLayer(myGraphicsLayer, withName:"Graphics Layer")

Note that the name you give your layer in the addMapLayer method must be unique to your map view.

Adding graphic features

A graphic is an instance of the AGSGraphic class. A graphic is associated with a geometry, which defines the location and shape of the graphic on a map. The graphic can be associated with a symbol, which defines how the graphic should be displayed. Alternatively, a Graphics layer can be associated with a renderer, which determines how all graphics in that layer are displayed. Optionally, you can have attributes associated with the graphic. These attributes are key value pairs that represent information about the real world entity that the graphic represents.

In most cases, the graphics you display on a map will be returned as the result of executing tasks, such as a querying a map service, geocoding an address, or performing geoprocessing analysis. In such cases, the graphics will contain a geometry that describes their location and shape on a map. All you need to do is define how the graphics should be displayed, either by assigning each graphic a symbol, or by assigning the Graphics layer a renderer.

However, you can also create graphics programmatically. In such cases, you additionally need to assign the graphic a geometry. You can create the geometry yourself, or let a user interactively sketch the geometry using the Sketch layer.

The following code creates a graphic, assigns it a symbol and a geometry, and adds it to an existing Graphics layer:

//create a marker symbol to be used by our Graphic
let myMarkerSymbol = AGSSimpleMarkerSymbol()
myMarkerSymbol.color = UIColor.blueColor()
        
//Create an AGSPoint (which inherits from AGSGeometry) that
//defines where the Graphic will be drawn
let myMarkerPoint = AGSPoint(x: -93.2984, y: 44.9409, spatialReference: self.mapView.spatialReference)
        
//Create the Graphic, using the symbol and
//geometry created earlier
let myGraphic = AGSGraphic(geometry: myMarkerPoint, symbol: myMarkerSymbol, attributes: nil)
        
//Add the graphic to the Graphics layer
graphicsLayer.addGraphic(myGraphic)

Graphics that are returned as the result of a task are already populated with a geometry but not a symbol, so you either need to give those graphics a symbol or apply a renderer to the Graphics layer before adding the graphics to your Graphics layer. To set a symbol into graphics that have been returned as the result of a Query task, do the following:

//create a simple fill symbol
let fillSymbol = AGSSimpleFillSymbol()
fillSymbol.color = UIColor.purpleColor().colorWithAlphaComponent(0.25)
fillSymbol.outline.color = UIColor.darkGrayColor()
        
//featureSet.features is the result of a Query task.
//It is an array of AGSGraphic objects containing
//geometries, but not symbols.
for graphic in featureSet.features as [AGSGraphic] {

	//set the graphics’s symbol to fillSymbol
 graphic.symbol = fillSymbol
            
 //add the graphic to the layer
 graphicsLayer.addGraphic(graphic)
}

Displaying attribute information in the callout

A graphic can contain custom attributes that provide information about the graphic. For instance, a graphic representing a city might have attributes providing information about its total population, average household income, and so on. Attributes are basically key-value pairs that are stored in a dictionary along with each graphic. To automatically display a map callout whenever a user taps on a graphic, you must either -

  • Set a delegate on AGSCallout
  • Set a calloutDelegate on the AGSGraphicsLayer that contains the graphic.

Refer to Displaying a callout topic for more information.

Using symbols

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 iOS 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).

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 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.

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
let myMarkerSymbol = AGSSimpleMarkerSymbol ()
myMarkerSymbol.color = UIColor.blueColor()
myMarkerSymbol.style = .Diamond
myMarkerSymbol.outline.color = UIColor.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
let myFillSymbol = AGSSimpleFillSymbol()
myFillSymbol.color = UIColor(red:0.7, green:0.1, blue:0.1, alpha:0.5)
        
//Create the AGSSimpleLineSymbol used for the outline
let myOutlineSymbol = AGSSimpleLineSymbol()
myOutlineSymbol.color = UIColor.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.

Using 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.

graphicsLayer.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.

let mySimpleRenderer = AGSSimpleRenderer(symbol: myMarkerSymbol)
graphicsLayer.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.
let cityRenderer = AGSClassBreaksRenderer()
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)
let lowClassBreak = AGSClassBreak(label: "Low", description: "", maxValue: 50000, symbol: lowMarkerSymbol)
let mediumClassBreak = AGSClassBreak(label: "Medium", description: "", maxValue: 250000, symbol: mediumMarkerSymbol)
let highClassBreak = AGSClassBreak(label: "High", description: "", maxValue: DBL_MAX, symbol: highMarkerSymbol) 
        
//add the AGSClassBreak objects to the renderer
cityRenderer.classBreaks = [lowClassBreak, mediumClassBreak, highClassBreak]
                
//add the renderer to the graphics layer  
graphicsLayer.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
let cityRenderer = AGSUniqueValueRenderer()
cityRenderer.defaultSymbol = defaultMakerSymbol
cityRenderer.field1 = "TYPE"
        
//create three AGSUniqueValue objects, one each for
//CITY, TOWN, and VILLAGE
let village = AGSUniqueValue(value: "VILLAGE", label: "village", description: nil, symbol: villageSymbol)
let city = AGSUniqueValue(value: "CITY", label: "city", description: nil, symbol: citySymbol)
let town = AGSUniqueValue(value: "TOWN", label: "town", description: nil, symbol: townSymbol)
        
//add the AGSUniqueValue objects to the renderer
cityRenderer.uniqueValues = [village, city, 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.