DingiFeature

 
@protocol DingiFeature <DingiAnnotation>

The DingiFeature protocol is used to provide details about geographic features contained in an DingiShapeSource or DingiVectorTileSource 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 DingiShapeSource using the -[DingiShapeSource initWithIdentifier:shape:options:] method or DingiShapeSource.shape property.

In addition to adding data to the map, you can also extract data from the map: -[DingiMapView 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 DingiVectorTileSource objects. You also reuse these feature objects as overlay annotations.

While it is possible to add DingiFeature-conforming objects to the map as annotations using -[DingiMapView addAnnotations:] and related methods, doing so has trade-offs:

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

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

    In vector tiles loaded by DingiVectorTileSource 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 DingiShapeSource 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 -[DingiMapView 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 }

  • A dictionary of attributes for this feature.

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

    You can also configure many layout and paint attributes of an DingiStyleLayer object to match the value of an attribute in this dictionary whenever it renders this feature. For example, if you display features in an DingiShapeSource using an DingiCircleStyleLayer, you can assign a halfway attribute to each of the source’s features, then set DingiCircleStyleLayer.circleRadius to an DingiStyleValue object with an interpolation mode of MGLInterpolationModeIdentity and an attribute name of halfway.

    The DingiSymbolStyleLayer.textField and DingiSymbolStyleLayer.iconImageName properties allow you to use attributes yet another way. For example, to label features in an DingiShapeSource object by their names, you can assign a name attribute to each of the source’s features, then set DingiSymbolStyleLayer.textField to an DingiStyleValue object containing the raw string value {name}.

    In vector tiles loaded by DingiVectorTileSource 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.

    When adding a feature to an DingiShapeSource, use the same Foundation types listed above for each attribute value. In addition to the Foundation types, you may also set an attribute to an NSColor (macOS) or UIColor (iOS), which will be converted into its CSS string representation when the feature is added to an DingiShapeSource. This can be convenient when using the attribute to supply a value for a color-typed layout or paint attribute via the MGLInterpolationModeIdentity interpolation mode.

    Note that while it is possible to change this value on feature instances obtained from -[DingiMapView 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 DingiShapeSource 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 }

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

  • Returns a dictionary that can be serialized as a GeoJSON Feature representation of an instance of an DingiFeature 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]