MGLFeature

 
@protocol MGLFeature <MGLAnnotation>

The MGLFeature protocol is used to provide details about geographic features contained in an MGLShapeSource or MGLVectorSource object. Each concrete subclass of MGLShape in turn has a subclass that conforms to this protocol. A feature object associates a shape with an optional identifier and attributes.

You can add custom data to display on the map by creating feature objects and adding them to an MGLShapeSource using the -[MGLShapeSource initWithIdentifier:shape:options:] method or MGLShapeSource.shape property. Similarly, you can add MGLPointFeature, MGLPolylineFeature, and MGLPolygonFeature objects to the map as annotations using -[MGLMapView addAnnotations:] and related methods.

In addition to adding data to the map, you can also extract data from the map: -[MGLMapView visibleFeaturesAtPoint:] and related methods return feature objects that correspond to features in the source. This enables you to inspect the properties of features in vector tiles loaded by MGLVectorSource objects. You also reuse these feature objects as overlay annotations.

  • An object that uniquely identifies the feature in its containing content source.

    You can configure an MGLVectorStyleLayer object to include or exclude a specific feature in an MGLShapeSource or MGLVectorSource. In the MGLVectorStyleLayer.predicate property, compare the special $id attribute to the feature’s identifier.

    In vector tiles loaded by MGLVectorSource objects, the identifier corresponds to the feature identifier (id). If the source does not specify the feature’s identifier, the value of this property is nil. If specified, the identifier may be an integer, floating-point number, or string. These data types are mapped to instances of the following Foundation classes:

    In the tile sourceThis property
    Integer NSNumber (use the unsignedLongLongValue or longLongValue property)
    Floating-point number NSNumber (use the doubleValue property)
    String NSString

    For details about the identifiers used in most Mapbox-provided styles, consult the Mapbox Streets layer reference.

    The identifier should be set before adding the feature to an MGLShapeSource object; setting it afterwards has no effect on the map’s contents. While it is possible to change this value on feature instances obtained from -[MGLMapView visibleFeaturesAtPoint:] and related methods, doing so likewise has no effect on the map’s contents.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) id identifier;

    Swift

    var identifier: Any? { get set }
    View Source on GitHub

  • A dictionary of attributes for this feature.

    You can configure an MGLVectorStyleLayer object to include or exclude a specific feature in an MGLShapeSource or MGLVectorSource. In the MGLVectorStyleLayer.predicate property, compare a key of the attribute dictionary to the value you want to include. For example, if you want an MGLLineStyleLayer object to display only important features, you might assign a value above 50 to the important features’ importance attribute, then set MGLVectorStyleLayer.predicate to an NSPredicate with the format importance > 50.

    You can also configure some attributes of an MGLSymbolStyleLayer object to include the value of an attribute in this dictionary whenever it renders this feature. For example, to label features in an MGLShapeSource object by their names, you can assign a name attribute to each of the source’s features, then set MGLSymbolStyleLayer.textField to an MGLStyleValue object containing the string {name}.

    In vector tiles loaded by MGLVectorSource objects, the keys and values of each feature’s attribute dictionary are determined by the source. Each attribute name is a string, while each attribute value may be a null value, Boolean value, integer, floating-point number, or string. These data types are mapped to instances of the following Foundation classes:

    In the tile sourceIn this dictionary
    Null NSNull
    Boolean NSNumber (use the boolValue property)
    Integer NSNumber (use the unsignedLongLongValue or longLongValue property)
    Floating-point number NSNumber (use the doubleValue property)
    String NSString

    For details about the attribute names and values found in Mapbox-provided vector tile sources, consult the Mapbox Streets and Mapbox Terrain layer references.

    Note that while it is possible to change this value on feature instances obtained from -[MGLMapView visibleFeaturesAtPoint:] and related methods, there will be no effect on the map. Setting this value can be useful when the feature instance is used to initialize an MGLShapeSource and that source is added to the map and styled.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic)
    NSDictionary<NSString *, id> *_Nonnull attributes;

    Swift

    var attributes: [String : Any] { get set }
    View Source on GitHub

  • Returns the feature attribute for the given attribute name.

    See the attributes property’s documentation for details on keys and values associated with this method.

    Declaration

    Objective-C

    - (nullable id)attributeForKey:(nonnull NSString *)key;

    Swift

    func attribute(forKey key: String) -> Any?
    View Source on GitHub

  • Returns a dictionary that can be serialized as a GeoJSON Feature representation of an instance of an MGLFeature subclass.

    The dictionary includes a geometry key corresponding to the receiver’s underlying geometry data, a properties key corresponding to the receiver’s attributes property, and an id key corresponding to the receiver’s identifier property.

    Declaration

    Objective-C

    - (nonnull NSDictionary<NSString *, id> *)geoJSONDictionary;

    Swift

    func geoJSONDictionary() -> [String : Any]
    View Source on GitHub