Using Graphics

Version 3.7

Graphics in the ArcGIS API for Flex


The following discussion assumes that you are familiar with the basic concepts of Flex.

Working with graphics

When the ArcGIS API for Flex was first released, the only option for displaying information client-side was through the use of a graphics layer. The graphics layer allows you to dynamically display graphics on a map. The graphics can be drawn by the user as markup or input to a task, or they can be drawn by the application in response to a task. For example, the application might add the results of a query to the map as graphics.

A graphic is composed of the following:

  • Geometry—The geometry determines where the graphic is located. IT can be point, multipoint, polyline, polygon, or extent.
  • Symbol—The symbol determines how the graphic looks. It can be a marker symbol (for point and multipoint geometries), a line symbol (for polylines), or a fill symbol (for polygons). For more information on working with symbols in graphics, see Symbols and Renderers.
  • Attributes—These are name-value pairs that describe the graphic. If you create the graphic, you need to assign the attributes. If the graphic is created in response to a task performed on a layer, the graphic automatically includes the field attributes of the layer. Some tasks allow you to limit the attributes that are returned to the resultant graphic. Query.outFields is an example of a property that limits the returned attributes of a task.

Graphics are not required to have all of three items as listed above. For example, many task results are returned as graphic objects in a FeatureSet. These graphics have only geometry and attributes when they are returned. If you want to add the graphics to a map, you must define a symbol for them.

If you're writing code that allows users to draw graphics on the map, the Draw tool can make your work easier. DrawTool is a class that can help you capture the geometry that a user draws on the screen. You can then define a symbol and apply it to the geometry in a new graphic object. The DrawTool sample demonstrates this workflow.

The way that you add task results to the map as graphics varies by task type. If your task returns a feature set, you get an array of graphics (FeatureSet.features) that you can assign to graphicProvider of GraphicsLayer. The code below shows how you might do this with results from QueryTask.

This code defines a symbol to the graphics layer that is assigned to all the graphics added to that layer.

private function doQuery():void
    queryTask.execute(query, new AsyncResponder(onResult, onFault));
    function onResult(featureSet:FeatureSet, token:Object = null):void
        myGraphicsLayer.graphicProvider = featureSet.features;
    function onFault(info:Object, token:Object = null):void
    { info.toString() );

<esri:SimpleMarkerSymbol id="sms" size="10" color="0xFF0000" style="circle" />
<esri:GraphicsLayer id="myGraphicsLayer" symbol="{sms}"/>

Other tasks do not provide a feature set as a result but do provide the geometry, which you can use to create a graphic. For example, a Locator task finds an address candidate, whose location property is a MapPoint geometry. You can use this geometry to create a graphic showing the address location, as in the code below:

for each (var candidate:AddressCandidate in candidates)
    if (candidate.score > 80) {
        var myGraphic:Graphic = new Graphic();
        myGraphic.geometry = candidate.location;
        myGraphic.symbol = mySymbol;
        myGraphic.attributes = { address: candidate.address,score: candidate.score, locatorName: candidate.attributes.Loc_name };

See the samples for more ideas of how to create graphics from the results of different tasks.

3.0 and above

Starting with version 3.0 of the ArcGIS API for Flex, a defaultGraphicsLayer property was added to the Map class. This references the default graphics layer that is always displayed on top of all other layers in the map. This graphics layer cannot be removed.

Extending the graphics layer

The graphics layer is a very useful class that provides vast functionality. You can add to the already existing functionality provided by the graphics layer by extending it to build your own custom graphics layer. One example as to why you may want to create an extendable version of the graphics layer would be if you have attribute information that should correspond to a specific level of geography, e.g. census data in relation to county polygons. A custom graphics layer could be created that uses the geometry from an ArcGIS for Server service and corresponding attribute information could be derived from another back-end service, combining them to create graphic objects within a custom graphics layer. The FeatureLayer class was introduced at version 2.0 of the ArcGIS API for Flex and is a prime example of extending the GraphisLayer class.

Conceptual overview of working with Graphics

The following provides high-level steps of working with graphics in the API:

  1. Retrieve the graphics layer.
  2. Create or retrieve a graphic.
  3. Set the graphic's Geometry (if it is not already set).
  4. Apply the symbol to the graphic.
  5. Add the graphic to the graphics layer.