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.

Add point graphics

The following steps show how to create the red buoy markers on the image above.

  1. The location of point graphics is represented by the Point geometry class. The following code shows how the buoy locations are defined:

    SpatialReference SPATIAL_REFERENCE = SpatialReferences.getWgs84();
    Point buoy1Loc = new Point(-2.72, 56.065, SPATIAL_REFERENCE);
    Point buoy2Loc = new Point(-2.69, 56.065, SPATIAL_REFERENCE);
    Point buoy3Loc = new Point(-2.66, 56.065, SPATIAL_REFERENCE);
    Point buoy4Loc = new Point(-2.63, 56.065, SPATIAL_REFERENCE);

    The points are defined in the WGS84 spatial reference, which is generally the spatial reference you would obtain from a GPS receiver, for example.

    Tip:

    If the spatial reference of the geometry of a graphic is null, then it is assumed the geometry is in the same spatial reference as the map view; if your graphics do not display as expected and have a null spatial reference, check that the coordinates of your geometry use the same spatial reference as the map view. If the spatial reference is set, and is different to that of the map view, geometries are automatically reprojected for display. For maximum efficiency, especially when dealing with large numbers of graphics or moving graphics, geometries of graphics should have the same spatial reference as the map view.

  2. Define what the points look like. Points can be drawn as simple marker symbols (circles, crosses, diamonds, etc.) or picture marker symbols represented by small bitmap images.

    The code below shows how to define a red circle.

    // create a red (0xFFFF0000) circle simple marker symbol
    SimpleMarkerSymbol redCircleSymbol = new SimpleMarkerSymbol(SimpleMarkerSymbol.Style.CIRCLE, 0xFFFF0000, 10);

  3. Create graphics, which are defined by the point geometry and the symbol.

    // create graphics and add to graphics overlay
    Graphic buoyGraphic1 = new Graphic(buoy1Loc, redCircleSymbol);
    Graphic buoyGraphic2 = new Graphic(buoy2Loc, redCircleSymbol);
    Graphic buoyGraphic3 = new Graphic(buoy3Loc, redCircleSymbol);
    Graphic buoyGraphic4 = new Graphic(buoy4Loc, redCircleSymbol);

  4. Add the graphics to the graphics overlay, which will display them on the map view.

    graphicsOverlay.getGraphics().addAll(Arrays.asList(buoyGraphic1, buoyGraphic2, buoyGraphic3, buoyGraphic4));

Add line graphics

The following steps show how to create the purple, dashed line representing the boat trip in the image near the top of this topic.

  1. The geometry for the boat trip is represented by the Polyline class. This is built with a collection of points used to define the vertices of the line.

    // create a new point collection for polyline
    PointCollection points = new PointCollection(SPATIAL_REFERENCE);
    
    // create and add points to the point collection
    points.add(new Point(-2.715, 56.061));
    points.add(new Point(-2.6438, 56.079));
    points.add(new Point(-2.638, 56.079));
    points.add(new Point(-2.636, 56.078));
    points.add(new Point(-2.636, 56.077));
    points.add(new Point(-2.637, 56.076));
    points.add(new Point(-2.715, 56.061));
    
    // create the polyline from the point collection
    Polyline polyline = new Polyline(points);

    For more information on drawing lines using the geometry API, see Geometries.

  2. Define the symbol for the boat trip using the SimpleLineSymbol class.

    The code below defines this as a purple dashed line.

    // create a purple (0xFF800080) simple line symbol
    SimpleLineSymbol lineSymbol = new SimpleLineSymbol(SimpleLineSymbol.Style.DASH, 0xFF800080, 4);

  3. Create the graphic from the line geometry and line symbol.

    // create the graphic with polyline and symbol
    Graphic graphic = new Graphic(polyline, lineSymbol);

  4. Add the graphic to the graphics overlay.

    // add graphic to the graphics overlay
    graphicsOverlay.getGraphics().add(graphic);

Add polygon graphics

The following steps show how to create the polygon representing the nesting ground area in the image near the top of this topic.

  1. The geometry for the nesting ground is defined using the Polygon class. The vertices of the polygon are created from a collection of points. For more information on building polygons, see Geometries.

    // create a new point collection for polygon
    PointCollection points = new PointCollection(SPATIAL_REFERENCE);
    
    // create and add points to the point collection
    points.add(new Point(-2.6425, 56.0784));
    points.add(new Point(-2.6430, 56.0763));
    points.add(new Point(-2.6410, 56.0759));
    points.add(new Point(-2.6380, 56.0765));
    points.add(new Point(-2.6380, 56.0784));
    points.add(new Point(-2.6410, 56.0786));
    
    // create the polyline from the point collection
    Polygon polygon = new Polygon(points);

  2. Define a symbol for the polygon. The symbol in the screen shot above is made up of a line symbol for the outline and a fill symbol for the polygon fill.

    // create a green (0xFF005000) simple line symbol
    SimpleLineSymbol outlineSymbol = new SimpleLineSymbol(SimpleLineSymbol.Style.DASH, 0xFF005000, 1);
    // create a green (0xFF005000) mesh simple fill symbol
    SimpleFillSymbol fillSymbol = new SimpleFillSymbol(SimpleFillSymbol.Style.DIAGONAL_CROSS, 0xFF005000,
        outlineSymbol);

  3. Create the graphic from the polygon geometry and fill symbol.

    // create the graphic with polyline and symbol
    Graphic graphic = new Graphic(polygon, fillSymbol);

  4. Add the polygon graphic to the graphics overlay.

    // add graphic to the graphics overlay
    graphicsOverlay.getGraphics().add(graphic);

Add text

The following steps show how to add the "Craigleith" and "Bass Rock" text to the graphics overlay.

  1. The geometry for text symbols is a point. The point represents the anchor point for the text. The following code defines the anchor points for the two text symbols in the image at the top of this topic.

    // create two points
    Point bassPoint = new Point(-2.64, 56.079, SPATIAL_REFERENCE);
    Point craigleithPoint = new Point(-2.72, 56.076, SPATIAL_REFERENCE);

  2. Create the symbols for the text items.

    final int BLUE = 0xFF0000E6;
    // create two text symbols
    TextSymbol bassRockTextSymbol = new TextSymbol(10, "Bass Rock", BLUE, HorizontalAlignment.LEFT,
        VerticalAlignment.BOTTOM);
    
    TextSymbol craigleithTextSymbol = new TextSymbol(10, "Craigleith", BLUE, HorizontalAlignment.RIGHT,
        VerticalAlignment.TOP);

  3. Create the graphics from the point and text symbol.

    // create two graphics from the points and symbols
    Graphic bassRockGraphic = new Graphic(bassPoint, bassRockTextSymbol);
    Graphic craigleithGraphic = new Graphic(craigleithPoint, craigleithTextSymbol);

  4. Add the text graphics to the graphics overlays.

    // add graphics to the graphics overlay
    graphicsOverlay.getGraphics().add(bassRockGraphic);
    graphicsOverlay.getGraphics().add(craigleithGraphic);

Identify graphics

In your app, you can add code to allow users to click on a graphic and get more information about it. For example, you may tap or click on a seabird in your graphics overlay to display the name of the bird's species in a dialog box.

The identifyGraphicsOverlay method on the map view allows you identify graphics at a point on the map for a given graphics overlay. If you have more than one graphics overlay and want to perform an identify operation on all graphics overlays, use the identifyGraphicsOverlays method. The example below shows how you can perform an identify on a single graphics overlay in response to a tap on the map view.

mapView.setOnMouseClicked(e -> {
  if (e.getButton() == MouseButton.PRIMARY && e.isStillSincePress()) {
    // create a point from location clicked
    Point2D mapViewPoint = new Point2D(e.getX(), e.getY());

    // identify graphics on the graphics overlay
    ListenableFuture<IdentifyGraphicsOverlayResult> identifyGraphics = mapView.identifyGraphicsOverlayAsync(graphicsOverlay, mapViewPoint, 10, false);

    identifyGraphics.addDoneListener(() -> Platform.runLater(() -> {
      try {
        // get the list of graphics returned by identify
        IdentifyGraphicsOverlayResult result = identifyGraphics.get();
        List<Graphic> graphics = result.getGraphics();

        if (!graphics.isEmpty()) {
          // show a alert dialog box if a graphic was returned
          Alert dialog = new Alert(AlertType.INFORMATION);
          dialog.setHeaderText(null);
          dialog.setTitle("Information Dialog Sample");
          dialog.setContentText("Clicked on " + graphics.size() + " graphic");
          dialog.showAndWait();
        }
      } catch (Exception ex) {
        // on any error, display the stack trace
        ex.printStackTrace();
      }
    }));
  }
});

You can iterate through each result returned from an identify. For example, you can display a list of the attribute values from each result.

public void seaBirdDialog(ListenableFuture<List<Graphic>> identifyGraphics) {
  StringBuilder seaBirds = new StringBuilder();

  try {
    // get the list of graphics returned by identify
    List<Graphic> graphics = identifyGraphics.get();

    // loop through the graphics
    for (Graphic grItem : graphics) {
      seaBirds.append(grItem.getAttributes().get("SEABIRD")).append("\n");
    }

    Alert alert = new Alert(Alert.AlertType.INFORMATION);
    alert.setTitle("Seabirds identified:");
    alert.setHeaderText(null);
    alert.setContentText(seaBirds.toString());

    alert.showAndWait();

  }catch(Exception e){
    e.printStackTrace();
  }
}

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 setSelected method on the Graphic class.

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. The code below sets a new geometry on a graphic (grItem).

// create a point from location clicked
mapView.setOnMouseClicked(e -> {
  if (e.getButton() == MouseButton.PRIMARY) {
    Point2D mapViewPoint = new Point2D(e.getX(), e.getY());
    // add new location to selected graphic
    Point mapPoint = mapView.screenToLocation(mapViewPoint);
    selectedGraphic.setGeometry(mapPoint);
  }
});

Remove graphics

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

routeGraphicsOverlay.getGraphics().remove(routeGraphic);