Annotations

This section focuses on the usage and customization of different types of annotations on a map. Annotations are visual elements that represent specific points, lines, or shapes on a map. They provide additional information and enhance the user experience by adding context to the displayed map.

It covers various types of annotations and their respective functionalities. Each subsection explains the specific annotation type, provides examples of how to use them, and discusses the relevant protocols or interfaces involved.

PointAnnotation

An NGLPointAnnotation object represents a one-dimensional shape located at a single geographical coordinate. Depending on how it is used, an NGLPointAnnotation object is known as a point annotation or point shape. For example, you could use a point shape to represent a city at low zoom levels, an address at high zoom levels, or the location of a long press gesture.

Interface

For more interactivity, add a selectable point annotation to a map view using the -[NGLMapView addAnnotation:] method. A point annotation’s annotation.title and annotation.subtitle properties define the default content of the annotation’s callout or popover

1​​func addAnnotation(_ annotation: NGLAnnotation)
2
3func addAnnotations(_ annotations: [NGLAnnotation])

Example

1let coord = CLLocationCoordinate2D(latitude: 12.97780156, longitude: 77.59656748)
2let annotation = NGLPointAnnotation()
3annotation.title = "title"
4annotation.subtitle = "subtitle"
5annotation.coordinate = coord
6nbMapView.addAnnotation(annotation)

Protocol

Alternatively, define your own model class that conforms to the NGLAnnotation protocol. Configure a point annotation’s appearance using -[NGLMapViewDelegate mapView:imageForAnnotation:] or -[NGLMapViewDelegate mapView:viewForAnnotation:]

1func mapView(_ mapView: NGLMapView, imageFor annotation: NGLAnnotation)

To show a callout view when tapping on an annotation you can implement the method annotationCanShowCallout and return true

1func mapView(_ mapView: NGLMapView, annotationCanShowCallout annotation: NGLAnnotation) -> Bool{
2   return true
3}

You can add accessory views to either end of the callout by implementing the -mapView:leftCalloutAccessoryViewForAnnotation: and -mapView:rightCalloutAccessoryViewForAnnotation: methods.

1func mapView(_ mapView: NGLMapView, rightCalloutAccessoryViewFor annotation: NGLAnnotation) -> UIView?
2
3func mapView(_ mapView: NGLMapView, leftCalloutAccessoryViewFor annotation: NGLAnnotation) -> UIView?

You can further customize the callout’s contents by implementing the -mapView:calloutViewForAnnotation: method.

1func mapView(_ mapView: NGLMapView, calloutViewFor annotation: NGLAnnotation) -> NGLCalloutView?
2
3func mapView(_ mapView: NGLMapView, tapOnCalloutFor annotation: NGLAnnotation)

Remove annotation

Removes an annotation from the map view, deselecting it if it is selected. Removing an annotation object dissociates it from the map view entirely, preventing it from being displayed on the map. Thus you would typically call this method only when you want to hide or delete a given annotation.

1func removeAnnotation(_ annotation: NGLAnnotation)
2
3func removeAnnotations(_ annotations: [NGLAnnotation])

PolylineAnnotation

An NGLPolyline object represents a shape consisting of two or more vertices, specified as CLLocationCoordinate2D instances, and the line segments that connect them. For example, you could use a polyline to represent a road or the path along which something moves.

The vertices are automatically connected in the order in which you provide them. The first and last vertices are not connected to each other, but you can specify the same CLLocationCoordinate2D as the first and last vertices in order to close the polyline. To fill the space within the shape, use an NGLPolygon object. To group multiple polylines together in one shape, use an NGLMultiPolyline or NGLShapeCollection object.

Example

you can create and add a polyline overlay directly to a map view using the -[NGLMapView addAnnotation:] or -[NGLMapView addOverlay:] method.

1var points : Array = [CLLocationCoordinate2D]()
2points.append(CLLocationCoordinate2D(latitude: 12.97780156, longitude: 77.59656748)
3)
4...
5let line = NGLPolyline(coordinates:points, count: UInt(points.count))
6
7nbMapView.addAnnotation(line)

Protocol

Configure a polyline overlay’s appearance using following methods

1func mapView(_ mapView: NGLMapView, strokeColorForShapeAnnotation annotation: NGLShape) -> UIColor  {
2   return UIColor.red
3}
4
5func mapView(_ mapView: NGLMapView, fillColorForPolygonAnnotation annotation: NGLPolygon) -> UIColor  {
6   return UIColor.blue
7}
8
9func mapView(_ mapView: NGLMapView, lineWidthForPolylineAnnotation annotation: NGLPolyline) -> CGFloat  {}

You can set the opacity of an entire polyline shape, inclusive of its stroke and fill by implementing the method

1func mapView(_ mapView: NGLMapView, alphaForShapeAnnotation annotation: NGLShape) -> CGFloat  {
2  return 1.0
3}

PolygonAnnotation

An NGLPolygon object represents a closed shape consisting of four or more vertices, specified as CLLocationCoordinate2D instances, and the edges that connect them. For example, you could use a polygon shape to represent a building, a lake, or an area you want to highlight.

Example

Create a polyline with coordinates

1let locations: [CLLocationCoordinate2D] =  [
2            CLLocationCoordinate2D(latitude: 12.94798778, longitude: 77.57375084),
3            CLLocationCoordinate2D(latitude: 12.93669616, longitude: 77.57385337),
4            CLLocationCoordinate2D(latitude: 12.93639637, longitude: 77.58031279),
5            CLLocationCoordinate2D(latitude: 12.94808770, longitude: 77.58000520)
6        ]
7
8
9let polygon: NGLPolygon = NGLPolygon(coordinates: locations, count: 4)

you can add a polygon overlay directly to a map view using the -[NGLMapView addAnnotation:] or -[NGLMapView addOverlay:] method.

1​​func addAnnotation(_ annotation: NGLAnnotation)
2func addAnnotations(_ annotations: [NGLAnnotation])
3
4nbMapView.addAnnotation(polygon)

Protocol

The following methods can be used to configure the appearance of a polygon overlay using the Protocol:

1func mapView(_ mapView: NGLMapView, alphaForShapeAnnotation annotation: NGLShape) -> CGFloat  {
2        return 1.0
3    }

This method sets the opacity of the entire shape, including its stroke and fill. The value returned should be a CGFloat representing the desired opacity. In the provided example, the opacity is set to 1.0, indicating full opacity.

1func mapView(_ mapView: NGLMapView, strokeColorForShapeAnnotation annotation: NGLShape) -> UIColor  {
2        return UIColor.red
3    }

This method sets the default stroke color for the shape annotation. The returned UIColor object represents the desired stroke color. In the provided example, the stroke color is set to red.

1
2func mapView(_ mapView: NGLMapView, fillColorForPolygonAnnotation annotation: NGLPolygon) -> UIColor  {
3        return UIColor.blue
4    }

This method sets the fill color for the polygon annotation. The returned UIColor object represents the desired fill color. In the provided example, the fill color is set to blue.

1 func mapView(_ mapView: NGLMapView, lineWidthForPolylineAnnotation annotation: NGLPolyline) -> CGFloat  {
2        return 3.0
3    }

This method sets the line width, in points, for rendering the outline of a polyline annotation. The value returned should be a CGFloat representing the desired line width. In the provided example, the line width is set to 3.0 points.

CircleAnnotation

An NGLCircleStyleLayer is a style layer that renders one or more filled circles on the map. A circle-style layer renders circles whose radii are measured in screen units. To display circles on the map whose radii correspond to real-world distances, use many-sided regular polygons and configure their appearance using an NGLFillStyleLayer object.

Use a circle-style layer to configure the visual appearance of point or point collection features. These features can come from vector tiles loaded by an NGLVectorTileSource object, or they can be NGLPointAnnotation, NGLPointFeature, NGLPointCollection, or NGLPointCollectionFeature instances in an NGLShapeSource or NGLComputedShapeSource object.

1let shape = NGLPointFeature()
2shape.coordinate = CLLocationCoordinate2D(latitude: 51.050459433092655, longitude: -114.06847000122069)
3shape.identifier = "circle-feature"
4shape.attributes = ["color": "green"]
5
6let pointSource = NGLShapeSource(identifier: "circle-point-source", shape: shape, options: nil)

Example

You can access an existing circle style layer using the -[NGLStyle layerWithIdentifier:] method if you know its identifier; otherwise, find it using the NGLStyle.layers property. You can also create a new circle style layer and add it to the style using a method such as -[NGLStyle addLayer:].

1let circleLayer = NGLCircleStyleLayer(identifier: "leaf-circle-layer", source: pointSource)
2circleLayer.predicate = NSPredicate(format: "color = 'green'")
3circleLayer.circleColor = NSExpression(forConstantValue: UIColor.green)
4circleLayer.circleRadius = NSExpression(forConstantValue: 10)
5        
6if let shapeLayer = self.nbMapView.style?.layer(withIdentifier: "leaf-circle-layer") {
7   self.nbMapView.style?.removeLayer(shapeLayer)
8}
9
10
11nbMapView.style?.addLayer(circleLayer)

ViewAnnotation

You can customize a View Annotation by implementing the following methods to mark a point annotation with a view object. If you want to mark a particular point annotation with a static image instead, omit this method or have it return nil for that annotation, then implement -mapView:imageForAnnotation: instead.

1func mapView(_ mapView: NGLMapView, viewFor annotation: NGLAnnotation) -> NGLAnnotationView?  
2
3func mapView(_ mapView: NGLMapView, imageFor annotation: NGLAnnotation) -> NGLAnnotationImage?
4

Annotation views are compatible with UIKit, Core Animation, and other Cocoa Touch frameworks. On the other hand, static annotation images use less memory and draw more quickly than annotation views.

The user location annotation view can also be customized via this method. When annotation is an instance of NGLUserLocation (or equal to the map view’s userLocation property), return an instance of NGLUserLocationAnnotationView (or a subclass thereof).

Custom ViewAnnotation and UserLocationView with a view object

1func mapView(_ mapView: NGLMapView, imageFor annotation: NGLAnnotation) -> NGLAnnotationImage?{
2        return nil
3}
4    
5    
6func mapView(_ mapView: NGLMapView, viewFor annotation: NGLAnnotation) -> NGLAnnotationView? {
7        if annotation === mapView.userLocation {
8            if mapView.showsUserLocation {
9                let annotationView = NGLUserLocationAnnotationView(frame: .zero)
10                annotationView.frame = CGRect(x: 0, y: 0, width: annotationView.intrinsicContentSize.width, height: annotationView.intrinsicContentSize.height)
11                return annotationView
12            }
13            
14            return nil
15        }
16        
17        
18        var annotationView = mapView.dequeueReusableAnnotationView(withIdentifier:"NBXViewControllerAnnotationViewReuseIdentifer")
19        if annotationView == nil {
20            annotationView = NGLAnnotationView(reuseIdentifier: "NBXViewControllerAnnotationViewReuseIdentifer")
21            annotationView?.frame = CGRect(x: 0, y: 0, width: 20, height: 20)
22            annotationView?.backgroundColor = .red
23            
24            annotationView?.isDraggable = true
25        } else {
26            // orange indicates that the annotation view was reused
27            annotationView?.backgroundColor = .orange
28        }
29        
30        return annotationView
31    }
32

Custom ViewAnnotation with a static Image

1func mapView(_ mapView: NGLMapView, imageFor annotation: NGLAnnotation) -> NGLAnnotationImage?{
2        return NGLAnnotationImage(image: UIImage(named: "marker")!,reuseIdentifier:"Marker-Identifier")
3 }
4    
5    
6    func mapView(_ mapView: NGLMapView, viewFor annotation: NGLAnnotation) -> NGLAnnotationView? {
7       return nil
8 }
9