Add graphics and text to graphics overlays

A graphic is a visible item on your map that can be seen as a point, line, polygon, or text. You can add graphics to your map view. These are contained in graphics overlays and are for showing temporary data that's not persisted once the application closes. For example, you may want to display a route between two locations or animate data items that change quickly.

This topic discusses adding graphics to your map in a way that generates a symbol instance for each graphic. If you're drawing a large number of graphics with the same symbology, then you should consider applying a renderer to the graphics overlay instead, which allows you to define the appearance of all the graphics in the overlay. Using renderers to add graphics is discussed in Symbols and renderers.

The image below shows an example of graphics drawn over a gray basemap. The graphics are showing:

  • Red markers showing location of buoys
  • Text symbols adding names to the islands of Craigleith and Bass Rock
  • A green cross hatched polygon showing a Gannet nesting ground on Bass Rock
  • A purple line showing the path of a boat trip.

Screenshot of a map with multiple graphics

For more information on graphics and when to use them, see Features and graphics. For more information on graphics overlays, see Add graphics overlays to your app.

Create graphics in the graphics layer

This example demonstrates how to build graphics and add them into a graphics layer. Graphics include a geometry, and in this example they are symbolized by an associated symbol. You can see the complete code in the QML sample Add graphics with symbols.

  1. Define geometries for the buoys (points) and the anchor points for the text. Also create a geometry builder for the nesting area polygon. The geometry for the boat route is created later.

    // buoy location 1 (immutable once created)
        Point {
            x: -2.712642647560347
            y: 56.062812566811544
            spatialReference: SpatialReference.createWgs84()
    
            onComponentCompleted: {
                buoyLocArray.push(this);
            }
        }
    
        // buoy location 2 (immutable once created)
        Point {
            x: -2.6908416959572303
            y: 56.06444173689877
            spatialReference: SpatialReference.createWgs84()
    
            onComponentCompleted: {
                buoyLocArray.push(this);
            }
        }
    
        // text location 1: craigleith (immutable once created)
        Point {
            x: -2.640631
            y: 56.078083
            spatialReference: SpatialReference.createWgs84()
    
            onComponentCompleted: {
                textLocArray.push(this);
            }
        }
    
        // text location 2: bass rock (immutable once created)
        Point {
            x: -2.720324
            y: 56.073569
            spatialReference: SpatialReference.createWgs84()
    
            onComponentCompleted: {
                textLocArray.push(this);
            }
        }
    
        // polygon for nesting ground
        PolygonBuilder {
            id: nestingGroundPolygonBuilder
            spatialReference: SpatialReference.createWgs84()
        }

  2. Define the symbols to use for the buoys, boat route, and nesting area.

    // marker symbol for buoys
        SimpleMarkerSymbol {
            id: buoyMarkerSymbol
            style: Enums.SimpleMarkerSymbolStyleCircle
            color: "red"
            size: 10
        }
    
        // line symbol for boat route
        SimpleLineSymbol {
            id: boatRouteSymbol
            style: Enums.SimpleLineSymbolStyleDash
            color: Qt.rgba(0.5, 0.0, 0.5, 1)
            width: 4
            antiAlias: true
        }
    
        // fill symbol for nesting ground
        SimpleFillSymbol {
            id: nestingGroundSymbol
            style: Enums.SimpleFillSymbolStyleDiagonalCross
            color: Qt.rgba(0.0, 0.31, 0.0, 1)
    
            // default property: ouline
            SimpleLineSymbol {
                style: Enums.SimpleLineSymbolStyleDash
                color: Qt.rgba(0.0, 0.0, 0.5, 1)
                width: 1
                antiAlias: true
            }
        }

  3. Create and add all the graphics to the graphics overlay. Create each graphic type and then add them to the overlay one at a time. Alternatively, you can create all of them and store in a list and add all of them by calling appendAll and pass in the list.

    Component.onCompleted: {  // The component is the containing Rectangle  
            // add buoy points
            buoyLocArray.forEach(function(buoyPoint) {
                graphicsOverlay.graphics.append(createGraphic(buoyPoint, buoyMarkerSymbol));
            });
    
            // add text symbols
            for (var i = 0; i < textLocArray.length; i++) {
                var textSymbol = ArcGISRuntimeEnvironment.createObject("TextSymbol");
                textSymbol.size = 10;
                textSymbol.color = Qt.rgba(0.1, 0.4, 0.9, 1);
                textSymbol.text = symbolTextArray[i];
    
                if (i === 1) {
                    textSymbol.horizontalAlignment = Enums.HorizontalAlignmentLeft;
                    textSymbol.verticalAlignment = Enums.VerticalAlignmentBottom;
                } else {
                    textSymbol.horizontalAlignment =  Enums.HorizontalAlignmentRight;
                    textSymbol.verticalAlignment =  Enums.VerticalAlignmentTop;
                }
                graphicsOverlay.graphics.append(createGraphic(textLocArray[i], textSymbol));
            }
    
            // add boat route
            graphicsOverlay.graphics.append(createGraphic(createBoatRoute(), boatRouteSymbol));
    
            // add the nesting ground
            graphicsOverlay.graphics.append(createGraphic(createNestingGround(), nestingGroundSymbol));
        }

  4. Notice that the code in the previous step uses helper functions to create the geometries. Using helper functions makes your code more flexible, easier to read, and easier to maintain.

    // create and return a graphic
        function createGraphic(geometry, symbol) {
            var graphic = ArcGISRuntimeEnvironment.createObject("Graphic");
            graphic.geometry = geometry;
            graphic.symbol = symbol;
            return graphic;
        }

    Helper functions are especially useful when creating geometry objects with lots vertices. The helper function createNestingGround demonstrates one approach by creating and inserting points one-by-one into the polygon builder.

    // create the nesting ground polygon
        function createNestingGround() {
            // create the polygon using the builder class
            nestingGroundPolygonBuilder.addPointXY(-2.643077012566659, 56.077125346044475);
            nestingGroundPolygonBuilder.addPointXY(-2.6428195210159444, 56.07717324600376);
            nestingGroundPolygonBuilder.addPointXY(-2.6425405718360033, 56.07774804087097);
            nestingGroundPolygonBuilder.addPointXY(-2.6427122328698127, 56.077927662508635);
            nestingGroundPolygonBuilder.addPointXY(-2.642454741319098, 56.07829887790651);
            nestingGroundPolygonBuilder.addPointXY(-2.641853927700763, 56.078526395253725);
            nestingGroundPolygonBuilder.addPointXY(-2.6409741649024867, 56.078801809192434);
            nestingGroundPolygonBuilder.addPointXY(-2.6399871139580795, 56.07881378366685);
            nestingGroundPolygonBuilder.addPointXY(-2.6394077579689705, 56.07908919555142);
            nestingGroundPolygonBuilder.addPointXY(-2.638764029092183, 56.07917301616904);
            nestingGroundPolygonBuilder.addPointXY(-2.638485079912242, 56.07896945149566);
            nestingGroundPolygonBuilder.addPointXY(-2.638570910429147, 56.078203080726844);
            nestingGroundPolygonBuilder.addPointXY(-2.63878548672141, 56.077568418396);
            nestingGroundPolygonBuilder.addPointXY(-2.6391931816767085, 56.077197195961084);
            nestingGroundPolygonBuilder.addPointXY(-2.6399441986996273, 56.07675411934114);
            nestingGroundPolygonBuilder.addPointXY(-2.6406523004640934, 56.076730169108444);
            nestingGroundPolygonBuilder.addPointXY(-2.6406737580933193, 56.07632301287509);
            nestingGroundPolygonBuilder.addPointXY(-2.6401802326211157, 56.075999679860494);
            nestingGroundPolygonBuilder.addPointXY(-2.6402446055087943, 56.075844000034046);
            nestingGroundPolygonBuilder.addPointXY(-2.640416266542604, 56.07578412301025);
            nestingGroundPolygonBuilder.addPointXY(-2.6408883343855822, 56.075808073830935);
            nestingGroundPolygonBuilder.addPointXY(-2.6417680971838577, 56.076239186057734);
            nestingGroundPolygonBuilder.addPointXY(-2.642197249768383, 56.076251161328514);
            nestingGroundPolygonBuilder.addPointXY(-2.6428409786451708, 56.07661041772168);
            nestingGroundPolygonBuilder.addPointXY(-2.643077012566659, 56.077125346044475);
    
            return nestingGroundPolygonBuilder.geometry;
        }

    The helper function createBoatRoute creates the geometry from its JSON representation.

    // create the boat route
        function createBoatRoute() {
            // create polyline using json
            return ArcGISRuntimeEnvironment.createObject("Polyline", {"json": boatRouteJson});
        }
    
        property var boatRouteJson : {"paths":[[[-2.7184791227926772,56.06147084563517],
                                        [-2.7196807500463924,56.06147084563517],
                                        [-2.722084004553823,56.062141712059706],
                                        [-2.726375530459948,56.06386674355254],
                                        [-2.726890513568683,56.0660708381432],
                                        [-2.7270621746049275,56.06779569383808],
                                        [-2.7255172252787228,56.068753913653914],
                                        [-2.723113970771293,56.069424653352335],
                                        [-2.719165766937657,56.07028701581465],
                                        [-2.713672613777817,56.070574465681325],
                                        [-2.7093810878716917,56.07095772883556],
                                        [-2.7044029178205866,56.07153261642126],
                                        [-2.698223120515766,56.072394931722265],
                                        [-2.6923866452834355,56.07325722773041],
                                        [-2.68672183108735,56.07335303720707],
                                        [-2.6812286779275096,56.07354465544585],
                                        [-2.6764221689126497,56.074215311778964],
                                        [-2.6698990495353394,56.07488595644139],
                                        [-2.6647492184479886,56.075748196715914],
                                        [-2.659427726324393,56.076131408423215],
                                        [-2.654792878345778,56.07622721075461],
                                        [-2.651359657620878,56.076514616319784],
                                        [-2.6477547758597324,56.07708942101955],
                                        [-2.6450081992798125,56.07814320736718],
                                        [-2.6432915889173625,56.08025069360931],
                                        [-2.638656740938747,56.08044227755186],
                                        [-2.636940130576297,56.078813783674946],
                                        [-2.636425147467562,56.07728102068079],
                                        [-2.637798435757522,56.076610417698504],
                                        [-2.638656740938747,56.07507756705851],
                                        [-2.641231656482422,56.07479015077557],
                                        [-2.6427766058086277,56.075748196715914],
                                        [-2.6456948434247924,56.07546078543464],
                                        [-2.647239792750997,56.074598538729404],
                                        [-2.6492997251859376,56.072682365868616],
                                        [-2.6530762679833284,56.0718200569986],
                                        [-2.655479522490758,56.070861913404286],
                                        [-2.6587410821794135,56.07047864929729],
                                        [-2.6633759301580286,56.07028701581465],
                                        [-2.666637489846684,56.07009538137926],
                                        [-2.670070710571584,56.06990374599109],
                                        [-2.6741905754414645,56.069137194910745],
                                        [-2.678310440311345,56.06808316228391],
                                        [-2.682086983108735,56.06789151689155],
                                        [-2.6868934921235956,56.06760404701653],
                                        [-2.6911850180297208,56.06722075051504],
                                        [-2.695133221863356,56.06702910083509],
                                        [-2.698223120515766,56.066837450202335],
                                        [-2.7016563412406667,56.06645414607839],
                                        [-2.7061195281830366,56.0660708381432],
                                        [-2.7100677320166717,56.065591697864576],
                                        [-2.713329291705327,56.06520838135397],
                                        [-2.7167625124302273,56.06453756828941],
                                        [-2.718307461756433,56.06348340989081],
                                        [-2.719165766937657,56.062812566811544],
                                        [-2.7198524110826376,56.06204587471371],
                                        [-2.719165766937657,56.06166252294756],
                                        [-2.718307461756433,56.06147084563517]]],
                                        "spatialReference":{"wkid":4326}}

Select graphics

Selecting a graphic is a way of bringing it to the attention of a user by drawing a halo around it. Change the selection state of a graphic by using the selected property on the Graphic type.

Screenshot of selected graphic

Update graphics

It's possible to update the geometry or attributes of a graphic by using the graphics collection of the graphics overlay. You can access and modify the list of graphics in a graphics overlay through its graphics property.

Remove graphics

To remove graphics you work with the graphics collection and call the remove method.