Graphics are objects held in memory that store a shape (geometry) and are displayed on a map via a GraphicsLayer. Optionally, attribute information describing a Graphic can be stored in a collection of key/value pairs. Graphics can be displayed using symbology applied directly to the Graphic itself or with a Renderer associated with the containing GraphicsLayer.
A Graphic is a type of the abstract class Feature, which defines getAttributes and getGeometry methods. The Graphic class extends the Feature class by adding members to control how it is displayed on the map, including getSymbol and getDrawOrder. Unlike other types of features, such as GeodatabaseFeature, the geometry and attributes that define graphics are not physically stored on disk. Graphics are always stored in memory, and must therefore be created programmatically.
Graphics can be used to do things such as:
- Add geometries drawn interactively by the user
- Highlight a selection (features returned from a query, for example)
- Provide animation for data that changes quickly (such as GPS positions)
- Show text on the map
- Display buffer polygons around features
Add a graphics layer
A GraphicsLayer is a container for Graphic objects. A Graphic can store a point, line, or polygon geometry (including a multipart geometry), and a single GraphicsLayer can be used to display any combination of geometry types. The GraphicsLayer includes some members that control how individual graphics in the layer are displayed, including the setGraphicVisible and setSelectedGraphics methods. Optionally, you can define rendering properties for a GraphicsLayer to control how graphics are symbolized when drawn on the map.
Symbology defined for individual graphics will override rendering defined for the GraphicsLayer as a whole.
A map can contain any number of graphics layers. A GraphicsLayer, in turn, can store any number of Graphic objects, exposed by the getNumberOfGraphics() and getGraphicIDs() methods. The GraphicsLayer provides methods for adding and removing individual graphics in the layer.
The following code shows how a graphics layer is created and added to a MapView defined in layout XML:
// Get MapView from layout XML
// Alternatively, create new MapView object, set a basemap, then call setContentView(mMapView);
MapView mMapView = (MapView) findViewById(R.id.map);
// Create and add a GraphicsLayer
Once a graphics layer is in the map, you can add graphics by following this basic process:
- Create a Graphic object and assign the Geometry you want to display. Make sure the spatial reference for the geometry matches that of the map.
- Define a Symbol appropriate for the type of geometry used for the graphic (for example, marker, line, or fill symbol). This step is not required if a Renderer has been assigned to the GraphicsLayer.
- Optionally, define and assign a collection of attributes describing the Graphic. This may be required if your GraphicsLayer uses a renderer that depends on a specific attribute value (such as a class breaks renderer or unique value renderer).
- Add the new Graphic to the GraphicsLayer.
Add point graphics
A Point is the most basic type of geometry, in its simplest form defined with a single pair of coordinates (x, y). As a graphic, points can be used to represent things such as cities (at a small map scale), stops along a route, vehicles moving along a streets network, or perhaps simply to define where a piece of text should be displayed on the map.
You can add points to a graphics layer and display them using either a SimpleMarkerSymbol or a PictureMarkerSymbol. A SimpleMarkerSymbol allows you to display a graphic using one of a finite list of symbol types (circle, cross, diamond, square, or x). You can further define the symbol by specifying a size, color, and optionally an outline to display around the marker (defined using a SimpleLineSymbol, which in turn also has a color, style, and width).
A PictureMarkerSymbol symbolizes a point using an image specified in a Drawable. Along with the image, you can also specify a rotation angle, size (width and height), and an offset to apply when drawing the symbol.
A SimpleMarkerSymbol is created by specifying a color, shape, and size. The geographic location of a point is represented by a Point object, which contains the x, y, and optionally the z (height) and m (measure) coordinates of the point. The Symbol and Point are then used together to create a Graphic instance, which is added to the graphics layer, as shown in the following code snippet:
// create a point marker symbol (red, size 10, of type circle)
SimpleMarkerSymbol simpleMarker = new SimpleMarkerSymbol(Color.RED, 10, SimpleMarkerSymbol.STYLE.CIRCLE);
// create a point at x=-302557, y=7570663 (for a map using meters as units; this depends // on the spatial reference)
Point pointGeometry = new Point(-302557, 7570663);
// create a graphic with the geometry and marker symbol
Graphic pointGraphic = new Graphic(pointGeometry, simpleMarker);
// add the graphic to the graphics layer
Add polyline graphics
Polylines are collections of vertices (individual x/y locations) that are connected in a particular order. The simplest Polyline is one consisting of two vertices (a from and a to location) and the connection between them. More complex polylines can consist of several vertices, and can be multipart—composed of two or more (visually) distinct sets of connected vertices. Although potentially consisting of individual parts (called paths), a Polyline is still considered a single geometry by ArcGIS.
Polylines can be added to a graphics layer and displayed using a SimpleLineSymbol. This symbol allows you to display the graphic using one of a finite list of symbol types (dash, dash dot, dash dot dot, dot, null, or solid). You can further define the symbol by specifying a width and a color.
The following code snippet shows how to add a polyline graphic that represents the path of a boat:
// create a line symbol (green, 3 thick and a dash style)
SimpleLineSymbol lineSymbol = new SimpleLineSymbol(Color.GREEN, 3, SimpleLineSymbol.STYLE.DASH);
// create the line geometry
Polyline lineGeometry = new Polyline();
// create the graphic using the geometry and the symbol
Graphic lineGraphic = new Graphic(lineGeometry, lineSymbol);
// add the graphic to the graphics layer
The code result is a line similar to the following:
Add polygon graphics
Like polylines, a Polygon is a collection of vertices (individual x/y locations) that are connected in a particular order. The difference being that a polygon closes to produce an area. A valid Polygon must consist of at least three vertices (the minimum needed to enclose an area). More complex polygons can consist of many more vertices and can contain holes or be multipart—composed of two or more (visually) distinct sets of connected vertices. Although potentially consisting of individual parts (called rings), a Polygon is still considered a single geometry by ArcGIS.
Polygons can be displayed with a SimpleFillSymbol or a PictureFillSymbol. A SimpleFillSymbol allows you to display a graphic using one of a finite list of fill types (horizontal, vertical, cross, backward diagonal, forward diagonal, diagonal cross, null, or solid). You can further define the symbol by specifying a color (for the fill) and an outline to display as the border (defined using a SimpleLineSymbol, which in turn also has a color, style, and width).
PictureFillSymbol symbolizes a polygon using an image specified in a Drawable. The image you specify will be repeated to complete the polygon fill. Along with the image, you can also specify a rotation angle, size (width and height), and an offset to apply when drawing the symbol. PictureFillSymbol also has an outline that is set with a SimpleLineSymbol.
The following examples illustrate creating polygon shapes and symbolizing them with fill symbols.
Create simple polygons
The code below creates a dark gray, solid SimpleLineSymbol to use as an outline. A SimpleFillSymbol is created with a solid, green fill, and the outline previously created. Next, a Polygon is created - its first point is defined using the startPath method, and subsequent points using the lineTo method repeatedly. Lastly, a Graphic object is created from the SimpleFillSymbol and the Polygon, and added to the graphics layer.
// create a line symbol for the polygon outline (this is optional)
SimpleLineSymbol polygonOutline = new SimpleLineSymbol(Color.DKGRAY, 2, SimpleLineSymbol.STYLE.SOLID);
// create the polygon symbol
// if an outline is not needed put "null" instead of "polygonOutline"
SimpleFillSymbol fillSymbol = new SimpleFillSymbol(Color.GREEN, SimpleFillSymbol.STYLE.SOLID);
// create the geometry for a polygon
Polygon polygonGeometry = new Polygon();
// create the graphic
Graphic polygonGraphic = new Graphic(polygonGeometry, fillSymbol);
// add the graphic to the graphics layer
The code result displays a rectangle similar to the following image:
Create multipart and donut polygons
You can use multipart polygons to represent, for example, a region that consists of a number of islands or lakes. Donut polygons can be used to represent an island, a lake, or perhaps an island that has a lake in the middle. Think of the state of Hawaii: it consists of several individual islands but is represented on a map as a single feature.
The following is an example of a complex polygon that consists of the triangle to the west, and the rectangle with a hole in it, to the east:
The important thing to note is that the entirety of these (visually distinct) shapes are conceptually one object defined as a single geometry: a multipart polygon. The geometry shown above was constructed using the following code:
Polygon complexPolygon = new Polygon();
//create the main rectangle outline
//create a hole in the rectangle
//add the triangle to the left of the rectangle
You can now use this geometry to create a graphic that can be added to a graphics layer.
Add text to the map by assigning a TextSymbol to a graphic. Point graphics are best suited for displaying text, as the geometry will define the left, bottom point of the text. To modify where the text appears relative to its point geometry, use the setHorizontalAlignment and setVerticalAlignment methods on the TextSymbol. A TextSymbol, however, can be applied to a graphic of any geometry type. For Polygon or Polyline, by default the text will appear at the center of the geometry's bounding envelope (Extent), but you can adjust the text's alignment in the same way as with point geometries.
If you want the geometry (such as a point) to appear along with the text you're going to add, you may need to create two graphics—one to display the text (symbolized with a TextSymbol) and another to display the point (symbolized with a SimpleMarkerSymbol or PictureMarkerSymbol).
The following example illustrates using a text symbol and a point geometry to create a graphic:
//text symbol which defines text size, the text and color
TextSymbol txtSymbol = new TextSymbol(10, "Gannet nesting ground", Color.BLUE);
//a point to define where the text is drawn
Point pt = new Point(-293826, 7574114);
//create a graphic from the point and symbol
Graphic gr = new Graphic(pt, txtSymbol);
//add the graphic to the map
The following is an image showing this graphic created with a TextSymbol added to a graphics layer displaying over a tiled layer (an OpenStreetMapLayer in this case):
The angle of the text in a TextSymbol is measured clockwise from horizontal.
Render a graphics layer
As shown in the previous examples, you can define symbology for individual graphics by setting the Symbol property with the appropriate symbol object. As an alternative, you can define symbology for the entire GraphicsLayer, which will define how all graphics contained in the layer will be displayed. This is especially useful if the symbol used for a graphic should be determined by an attribute value.
Symbology for a GraphicsLayer is defined using a Renderer. This can be set with one of the following types of renderers:
- SimpleRenderer—Defines a single symbol to use for all features in the layer.
- ClassBreaksRenderer—Symbolizes graphics in the layer using classes (divisions) of a numeric attribute value.
- UniqueValueRenderer—Symbolizes graphics using unique values for a specified attribute.
The following is an example of point graphics displayed with a unique value renderer and symbolized with picture marker symbols.