Primitive Shapes
MGLAnnotation
The MGLAnnotation
protocol is used to provide annotation-related information to a map view. To use this protocol, you adopt it in any custom objects that store or represent annotation data. Each object then serves as the source of information about a single map annotation and provides critical information, such as the annotation’s location on the map. Annotation objects do not provide the visual representation of the annotation but typically coordinate (in conjunction with the map view’s delegate) the creation of an appropriate objects to handle the display.
An object that adopts this protocol must implement the coordinate
property. The other methods of this protocol are optional.
Declaration
Objective-C
@protocol MGLAnnotation <NSObject>
Swift
protocol MGLAnnotation : NSObjectProtocol
MGLOverlay
The MGLOverlay
protocol defines a specific type of annotation that represents both a point and an area on a map. Overlay objects are essentially data objects that contain the geographic data needed to represent the map area. Overlays can take the form of a polyline or polygon.
You use overlays to layer more sophisticated content on top of a map view. For example, you could use an overlay to show the boundaries of a national park or trace a bus route along city streets. This SDK defines several concrete classes that conform to this protocol and define standard shapes.
Declaration
Objective-C
@protocol MGLOverlay <MGLAnnotation>
Swift
protocol MGLOverlay : MGLAnnotation
MGLShape
MGLShape
is an abstract class that represents a shape or annotation. Shapes constitute the content of a map — not only the overlays atop the map, but also the content that forms the base map.
Create instances of MGLPointAnnotation
, MGLPointCollection
, MGLPolyline
, MGLMultiPolyline
, MGLPolygon
, MGLMultiPolygon
, or MGLShapeCollection
in order to use MGLShape
‘s methods. Do not create instances of MGLShape
directly, and do not create your own subclasses of this class. The shape classes correspond to the Geometry object types in the GeoJSON standard, but some have nonstandard names for backwards compatibility.
Although you do not create instances of this class directly, you can use its +[MGLShape shapeWithData:encoding:error:]
factory method to create one of the concrete subclasses of MGLShape
noted above from GeoJSON data. To access a shape’s attributes, use the corresponding MGLFeature
class instead.
You can add shapes to the map by adding them to an MGLShapeSource
object. Configure the appearance of an MGLShapeSource
’s or MGLVectorTileSource
’s shapes collectively using a concrete instance of MGLVectorStyleLayer
. Alternatively, you can add some kinds of shapes directly to a map view as annotations or overlays.
You can filter the features in a MGLVectorStyleLayer
or vary their layout or paint attributes based on the features’ geographies. Pass an MGLShape
into an NSPredicate
with the format SELF IN %@
or %@ CONTAINS SELF
and set the MGLVectorStyleLayer.predicate
property to that predicate, or set a layout or paint attribute to a similarly formatted NSExpression
.
Declaration
Objective-C
@interface MGLShape : NSObject <MGLAnnotation, NSSecureCoding>
Swift
class MGLShape : NSObject, MGLAnnotation, NSSecureCoding
MGLMultiPoint
The MGLMultiPoint
class is an abstract superclass used to define shapes composed of multiple vertices.
Create instances of MGLPolyline
or MGLPolygon
in order to use properties of MGLMultiPoint
. Do not create instances of MGLMultiPoint
directly and do not create your own subclasses of this class. You can use the method and properties of this class to access information about the vertices of the line or polygon.
Do not confuse MGLMultiPoint
with MGLPointCollection
, which represents a collection of related but disconnected points.
Declaration
Objective-C
@interface MGLMultiPoint : MGLShape
Swift
class MGLMultiPoint : MGLShape
MGLPointAnnotation
An MGLPointAnnotation
object represents a one-dimensional shape located at a single geographical coordinate. Depending on how it is used, an MGLPointAnnotation
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.
You can add point shapes to the map by adding them to an MGLShapeSource
object. Configure the appearance of an MGLShapeSource
’s or MGLVectorTileSource
’s point shapes collectively using an MGLCircleStyleLayer
or MGLSymbolStyleLayer
object.
For more interactivity, add a selectable point annotation to a map view using the -[MGLMapView addAnnotation:]
method. Alternatively, define your own model class that conforms to the MGLAnnotation
protocol. Configure a point annotation’s appearance using -[MGLMapViewDelegate mapView:imageForAnnotation:]
or -[MGLMapViewDelegate mapView:viewForAnnotation:]
(iOS only). A point annotation’s MGLShape.title
and MGLShape.subtitle
properties define the default content of the annotation’s callout (on iOS) or popover (on macOS).
To group multiple related points together in one shape, use an MGLPointCollection
or MGLShapeCollection
object. To access a point’s attributes, use an MGLPointFeature
object.
A point shape is known as a Point geometry in GeoJSON.
Declaration
Objective-C
@interface MGLPointAnnotation : MGLShape
Swift
class MGLPointAnnotation : MGLShape
MGLPointCollection
An MGLPointCollection
object represents a shape consisting of one or more disconnected vertices, specified as CLLocationCoordinate2D
instances. The points in the collection may be related but are not connected spatially. For example, you could use a point collection to represent all the trees in an orchard.
You can add point collections to the map by adding them to an MGLShapeSource
object. Configure the appearance of an MGLShapeSource
’s or MGLVectorTileSource
’s point collections collectively using an MGLCircleStyleLayer
or MGLSymbolStyleLayer
object. To access a point collection’s attributes, use an MGLPointCollectionFeature
object.
You cannot add an MGLPointCollection
object directly to a map view as an annotation. However, you can create individual MGLPointAnnotation
objects from the coordinates
array and add those annotation objects to the map view using the -[MGLMapView addAnnotations:]
method.
A point collection is known as a MultiPoint geometry in GeoJSON. Do not confuse MGLPointCollection
with MGLMultiPoint
, the abstract superclass of MGLPolyline
and MGLPolygon
.
Declaration
Objective-C
@interface MGLPointCollection : MGLShape <MGLOverlay>
Swift
class MGLPointCollection : MGLShape, MGLOverlay
MGLPolygon
An MGLPolygon
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.
You can add polygon shapes to the map by adding them to an MGLShapeSource
object. Configure the appearance of an MGLShapeSource
’s or MGLVectorTileSource
’s polygons collectively using an MGLFillStyleLayer
or MGLSymbolStyleLayer
object. To access a polygon’s attributes, use an MGLPolygonFeature
object.
Alternatively, you can add a polygon overlay directly to a map view using the -[MGLMapView addAnnotation:]
or -[MGLMapView addOverlay:]
method. Configure a polygon overlay’s appearance using -[MGLMapViewDelegate mapView:strokeColorForShapeAnnotation:]
and -[MGLMapViewDelegate mapView:fillColorForPolygonAnnotation:]
.
The vertices are automatically connected in the order in which you provide them. You should close the polygon by specifying the same CLLocationCoordinate2D
as the first and last vertices; otherwise, the polygon’s fill may not cover the area you expect it to. To avoid filling the space within the shape, give the polygon a transparent fill or use an MGLPolyline
object.
A polygon may have one or more interior polygons, or holes, that you specify as MGLPolygon
objects with the +polygonWithCoordinates:count:interiorPolygons:
method. For example, if a polygon represents a lake, it could exclude an island within the lake using an interior polygon. Interior polygons may not themselves have interior polygons. To represent a shape that includes a polygon within a hole or, more generally, to group multiple polygons together in one shape, use an MGLMultiPolygon
or MGLShapeCollection
object.
To make the polygon straddle the antimeridian, specify some longitudes less than −180 degrees or greater than 180 degrees.
Declaration
Objective-C
@interface MGLPolygon : MGLMultiPoint <MGLOverlay>
Swift
class MGLPolygon : MGLMultiPoint, MGLOverlay
MGLMultiPolygon
An MGLMultiPolygon
object represents a shape consisting of one or more polygons that do not overlap. For example, you could use a multipolygon shape to represent the body of land that consists of an island surrounded by an atoll: the inner island would be one MGLPolygon
object, while the surrounding atoll would be another. You could also use a multipolygon shape to represent a group of disconnected but related buildings.
You can add multipolygon shapes to the map by adding them to an MGLShapeSource
object. Configure the appearance of an MGLShapeSource
’s or MGLVectorTileSource
’s multipolygons collectively using an MGLFillStyleLayer
or MGLSymbolStyleLayer
object.
You cannot add an MGLMultiPolygon
object directly to a map view using -[MGLMapView addAnnotation:]
or -[MGLMapView addOverlay:]
. However, you can add the polygons
array’s items as overlays individually.
Declaration
Objective-C
@interface MGLMultiPolygon : MGLShape <MGLOverlay>
Swift
class MGLMultiPolygon : MGLShape, MGLOverlay
MGLPolyline
An MGLPolyline
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 an polyline to represent a road or the path along which something moves.
You can add polyline shapes to the map by adding them to an MGLShapeSource
object. Configure the appearance of an MGLShapeSource
’s or MGLVectorTileSource
’s polylines collectively using an MGLLineStyleLayer
or MGLSymbolStyleLayer
object. To access a polyline’s attributes, use an MGLPolylineFeature
object.
Alternatively, you can add a polyline overlay directly to a map view using the -[MGLMapView addAnnotation:]
or -[MGLMapView addOverlay:]
method. Configure a polyline overlay’s appearance using -[MGLMapViewDelegate mapView:strokeColorForShapeAnnotation:]
and -[MGLMapViewDelegate mapView:lineWidthForPolylineAnnotation:]
.
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 MGLPolygon
object. To group multiple polylines together in one shape, use an MGLMultiPolyline
or MGLShapeCollection
object.
To make the polyline go across the antimeridian or international date line, specify some longitudes less than −180 degrees or greater than 180 degrees. For example, a polyline that stretches from Tokyo to San Francisco would have coordinates of (35.68476, -220.24257) and (37.78428, -122.41310).
let coordinates = [
CLLocationCoordinate2D(latitude: 35.68476, longitude: -220.24257),
CLLocationCoordinate2D(latitude: 37.78428, longitude: -122.41310)
]
let polyline = MGLPolyline(coordinates: coordinates, count: UInt(coordinates.count))
A polyline is known as a LineString geometry in GeoJSON.
Declaration
Objective-C
@interface MGLPolyline : MGLMultiPoint <MGLOverlay>
Swift
class MGLPolyline : MGLMultiPoint, MGLOverlay
MGLMultiPolyline
An MGLMultiPolyline
object represents a shape consisting of one or more polylines. For example, you could use a multipolyline shape to represent both sides of a divided highway (dual carriageway), excluding the median (central reservation): each carriageway would be a distinct MGLPolyline
object.
You can add multipolyline shapes to the map by adding them to an MGLShapeSource
object. Configure the appearance of an MGLShapeSource
’s or MGLVectorTileSource
’s multipolylines collectively using an MGLLineStyleLayer
or MGLSymbolStyleLayer
object.
You cannot add an MGLMultiPolyline
object directly to a map view using -[MGLMapView addAnnotation:]
or -[MGLMapView addOverlay:]
. However, you can add the polylines
array’s items as overlays individually.
A multipolyline is known as a MultiLineString geometry in GeoJSON.
Declaration
Objective-C
@interface MGLMultiPolyline : MGLShape <MGLOverlay>
Swift
class MGLMultiPolyline : MGLShape, MGLOverlay
MGLShapeCollection
An MGLShapeCollection
object represents a shape consisting of zero or more distinct but related shapes that are instances of MGLShape
. The constituent shapes can be a mixture of different kinds of shapes.
MGLShapeCollection
is most commonly used to add multiple shapes to a single MGLShapeSource
. Configure the appearance of an MGLShapeSource
’s or MGLVectorTileSource
’s shape collection collectively using an MGLSymbolStyleLayer
object, or use multiple instances of MGLCircleStyleLayer
, MGLFillStyleLayer
, and MGLLineStyleLayer
to configure the appearance of each kind of shape inside the collection.
You cannot add an MGLShapeCollection
object directly to a map view as an annotation. However, you can create individual MGLPointAnnotation
, MGLPolyline
, and MGLPolygon
objects from the shapes
array and add those annotation objects to the map view using the -[MGLMapView addAnnotations:]
method.
To represent a collection of point, polyline, or polygon shapes, it may be more convenient to use an MGLPointCollection
, MGLMultiPolyline
, or MGLMultiPolygon
object, respectively. To access a shape collection’s attributes, use the corresponding MGLFeature
object.
A shape collection is known as a GeometryCollection geometry in GeoJSON.
Declaration
Objective-C
@interface MGLShapeCollection : MGLShape
Swift
class MGLShapeCollection : MGLShape
iOS SDK
Examples
SDK JS Reference
- MGLAnnotationImage
- MGLErrorCode
- MGLNetworkConfiguration
- MGLCircleStyleLayer
- MGLUserTrackingMode
- MGLTransition
- MGLCoordinateFormatter
- MGLImageSource
- MGLOrnamentPosition
- MGLAnnotation
- Other Type Definitions
- MGLAnnotationViewDragState
- NSValue(MGLCircleStyleLayerAdditions)
- MGLPolyline
- MGLCoordinateQuad
- MGLDEMEncoding
- Styling the Map
- MGLAttributionInfoStyle
- MGLTextTranslationAnchor
- MGLSymbolPlacement
- MGLOfflineStorage
- MGLHillshadeStyleLayer
- Other Functions
- MGLCompassButton
- MGLAttributionInfo
- MGLHeatmapStyleLayer
- Other Categories
- MGLSphericalPosition
- MGLCirclePitchAlignment
- User Interaction
- Location Updates
- MGLSphericalPosition
- Offline Maps
- MGLSymbolZOrder
- MGLIconRotationAlignment
- MGLLightAnchor
- MGLLocationManagerDelegate
- MGLAttributedExpression
- MGLLight
- MGLStyleLayer
- NSExpression(MGLAdditions)
- MGLAccountManager
- MGLShapeOfflineRegion
- Geometry
- MGLHillshadeIlluminationAnchor
- Info.plist Keys
- MGLBackgroundStyleLayer
- MGLSource
- MGLSymbolStyleLayer
- MGLResourceKind
- MGLCoordinateSpan
- MGLOrnamentVisibility
- NSValue(MGLFillExtrusionStyleLayerAdditions)
- NSValue(MGLHillshadeStyleLayerAdditions)
- MGLOfflineStorageDelegate
- MGLCluster
- Appendices
- MGLUserLocationAnnotationViewStyle
- NSValue(MGLLineStyleLayerAdditions)
- MGLStyle
- MGLMapSnapshotterDelegate
- MGLTextWritingMode
- MGLRasterResamplingMode
- MGLUserLocation
- MGLOfflinePackProgress
- MGLFillExtrusionTranslationAnchor
- MGLForegroundStyleLayer
- MGLLoggingConfiguration
- MGLTilePyramidOfflineRegion
- MGLRasterTileSource
- MGLAnnotationView
- Working with GeoJSON Data
- MGLVectorStyleLayer
- MGLMapSnapshotOptions
- MGLMapViewDelegate
- MGLMapDebugMaskOptions
- MGLMapSnapshotOverlay
- MGLIconTranslationAnchor
- Other Enumerations
- Other Protocols
- MGLTextRotationAlignment
- MGLUserLocationAnnotationView
- MGLTextPitchAlignment
- MGLCalloutViewDelegate
- Annotations
- MGLLineTranslationAnchor
- MGLShapeSource
- NSValue(MGLSymbolStyleLayerAdditions)
- MGLOfflinePackState
- MGLTextJustification
- Other Classes
- MGLMapSnapshotter
- MGLIconPitchAlignment
- MGLComputedShapeSource
- MGLRasterStyleLayer
- MGLCoordinateQuad
- MGLFeature
- MGLComputedShapeSourceDataSource
- MGLOfflineRegion
- MGLLineCap
- MGLLoggingLevel
- MGLFillExtrusionStyleLayer
- Style Content
- NSValue(MGLFillStyleLayerAdditions)
- NSValue(MGLRasterStyleLayerAdditions)
- MGLLocationManager
- MGLMapCamera
- MGLIconTextFit
- MGLLineStyleLayer
- MGLPointCollection
- MGLMultiPolygon
- MGLCircleTranslationAnchor
- Other Structures
- MGLFillStyleLayer
- MGLShapeCollection
- Primitive Shapes
- MGLTransition
- Information for Style Authors
- MGLLineJoin
- MGLPointAnnotation
- MGLTileSource
- MGLVectorTileSource
- MGLCoordinateBounds
- Gesture Recognizers
- NSValue(MGLAdditions)
- MGLCompassDirectionFormatter
- MGLIconAnchor
- Migrating to Expressions
- MGLPolygon
- MGLDistanceFormatter
- MGLFillTranslationAnchor
- MGLTextTransform
- MGLMultiPoint
- Customizing Fonts
- Maps
- MGLClockDirectionFormatter
- MGLCalloutView
- MGLTextAnchor
- MGLCircleScaleAlignment
- MGLCoordinateSpan
- MGLMapSnapshot
- MGLStylable
- MGLShape
- MGLOfflinePackProgress
- Style Primitives
- Predicates and expressions
- Formatters
- MGLMultiPolyline
- MGLTileCoordinateSystem
- MGLAnnotationVerticalAlignment
- MGLOverlay
- MGLCoordinateBounds
- Tile URL Templates
- MGLOfflinePack
- Style Layers
- MGLMapView
- Other Constants