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

  • 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.

    View Source on GitHub

Accessing the Shape Attributes

  • 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 }
    View Source on GitHub

  • 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 }
    View Source on GitHub

  • The tooltip of the shape annotation.

    The default value of this property is nil.

    This property is ignored when the shape is used in an MGLShapeSource.

    Declaration

    Objective-C

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

    Swift

    var toolTip: String? { get set }
    View Source on GitHub

Creating GeoJSON Data

  • 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.

    View Source on GitHub