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 pop-over.

1
​​func addAnnotation(_ annotation: NGLAnnotation)
2

3
func addAnnotations(_ annotations: [NGLAnnotation])

Example

1
let coord = CLLocationCoordinate2D(latitude: 12.97780156, longitude: 77.59656748)
2
let annotation = NGLPointAnnotation()
3
annotation.title = "title"
4
annotation.subtitle = "subtitle"
5
annotation.coordinate = coord
6
nbMapView.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:]

1
func 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

1
func 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.

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

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

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

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

3
func mapView(_ mapView: NGLMapView, tapOnCalloutFor annotation: 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.

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

7
nbMapView.addAnnotation(line)

Protocol

Configure a polyline overlay’s appearance using following methods

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

5
func mapView(_ mapView: NGLMapView, fillColorForPolygonAnnotation annotation: NGLPolygon) -> UIColor  {
6
   return UIColor.blue
7
}
8

9
func 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

1
func 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

1
let 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

9
let 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)
2
func addAnnotations(_ annotations: [NGLAnnotation])
3

4
nbMapView.addAnnotation(polygon)

Protocol

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

1
func 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.

1
func 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
func mapView(_ mapView: NGLMapView, fillColorForPolygonAnnotation annotation: NGLPolygon) -> UIColor  {
2
        return UIColor.blue
3
    }

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. Protocol When working with circle-style layers, you can implement the NGLAnnotation protocol to customize the visual representation of your circle annotations on the map. The protocol allows you to define attributes such as the circle's color, size, and other properties.

Here's an example of how you can create and customize an NGLPointFeature, which conforms to the NGLAnnotation protocol, and a corresponding NGLShapeSource to represent a circle annotation:

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

6
let 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:].

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

10

11
nbMapView.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.

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

3
func 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

1
func mapView(_ mapView: NGLMapView, imageFor annotation: NGLAnnotation) -> NGLAnnotationImage?{
2
        return nil
3
}
4
    
5
    
6
func 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

1
func 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

Remove annotation

The 'removeAnnotation' method allows you to effectively remove an annotation from the map view, also deselecting it if it happens to be currently selected. When an annotation is removed, it is completely disassociated from the map view, ensuring that it will no longer be visible on the map. Typically, you would use this method when you intend to hide or delete a specific annotation from the map.

Here are the available methods for removing annotations:

1
func removeAnnotation(_ annotation: NGLAnnotation)
2

3
func removeAnnotations(_ annotations: [NGLAnnotation])

1. func removeAnnotation(_ annotation: NGLAnnotation): This method removes a single annotation from the map view.

2. func removeAnnotations(_ annotations: [NGLAnnotation]): Use this method to remove multiple annotations simultaneously by providing an array of annotations to be removed.

These functions provide a straightforward way to manage and manipulate annotations on the map, enhancing your control over their visibility and presence.