MGLShape

@interface MGLShape : NSObject <MGLAnnotation, NSSecureCoding>

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.

Creating a Shape

+shapeWithData:encoding:error:

Returns an MGLShape object initialized with the given data interpreted as a string containing a GeoJSON object.

If the GeoJSON object is a geometry, the returned value is a kind of MGLShape. If it is a feature object, the returned value is a kind of MGLShape that conforms to the MGLFeature protocol. If it is a feature collection object, the returned value is an instance of MGLShapeCollectionFeature.

Example

let url = mainBundle.url(forResource: "amsterdam", withExtension: "geojson")!
let data = try! Data(contentsOf: url)
let feature = try! MGLShape(data: data, encoding: String.Encoding.utf8.rawValue) as! MGLShapeCollectionFeature

Declaration

Objective-C

+ (nullable MGLShape *)shapeWithData:(nonnull NSData *)data
                        encoding:(NSStringEncoding)encoding
                           error:(NSError *_Nullable *_Nullable)outError;

Swift

/*not inherited*/ init(data: Data, encoding: UInt) throws

Parameters

data

String data containing GeoJSON source code.

encoding

The encoding used by data.

outError

Upon return, if an error has occurred, a pointer to an NSError object describing the error. Pass in NULL to ignore any error.

Return Value

An MGLShape object representation of data, or nil if data could not be parsed as valid GeoJSON source code. If nil, outError contains an NSError object describing the problem.

Accessing the Shape Attributes

title

The title of the shape annotation.

The default value of this property is nil.

This property is ignored when the shape is used in an MGLShapeSource. To name a shape used in a shape source, create an MGLFeature and add an attribute to the MGLFeature.attributes property.

Declaration

Objective-C

@property (nonatomic, copy, readwrite, nullable) NSString *title;

Swift

var title: String? { get set }

subtitle

The subtitle of the shape annotation. The default value of this property is nil.

This property is ignored when the shape is used in an MGLShapeSource. To provide additional information about a shape used in a shape source, create an MGLFeature and add an attribute to the MGLFeature.attributes property.

Declaration

Objective-C

@property (nonatomic, copy, readwrite, nullable) NSString *subtitle;

Swift

var subtitle: String? { get set }

Creating GeoJSON Data

-geoJSONDataUsingEncoding:

Returns the GeoJSON string representation of the shape encapsulated in a data object.

Declaration

Objective-C

- (nonnull NSData *)geoJSONDataUsingEncoding:(NSStringEncoding)encoding;

Swift

func geoJSONData(usingEncoding encoding: UInt) -> Data

Parameters

encoding

The string encoding to use.

Return Value

A data object containing the shape’s GeoJSON string representation.