diff options
Diffstat (limited to 'platform/darwin/src/MGLFeature.h')
| -rw-r--r-- | platform/darwin/src/MGLFeature.h | 138 |
1 files changed, 94 insertions, 44 deletions
diff --git a/platform/darwin/src/MGLFeature.h b/platform/darwin/src/MGLFeature.h index b3a1868ed2..82dbb450cf 100644 --- a/platform/darwin/src/MGLFeature.h +++ b/platform/darwin/src/MGLFeature.h @@ -11,30 +11,41 @@ NS_ASSUME_NONNULL_BEGIN /** The `MGLFeature` protocol is used to provide details about geographic features - contained in a map view’s - <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources">tile sources</a>. - Each concrete subclass of `MGLShape` in turn has a subclass that conforms to - this protocol. - - Typically, you do not create feature objects yourself but rather obtain them - using `-[MGLMapView visibleFeaturesAtPoint:]` and related methods. Each feature - object associates a shape with an identifier and attributes as specified by the - source. Like ordinary `MGLAnnotation` objects, some kinds of `MGLFeature` - objects can also be added to a map view using an `MGLShapeSource` or - `-[MGLMapView addAnnotations:]` and related methods. + 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. */ @protocol MGLFeature <MGLAnnotation> /** - An object that uniquely identifies the feature in its containing - <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources">tile source</a>. + An object that uniquely identifies the feature in its containing content + source. - The identifier corresponds to the + 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 <a href="https://github.com/mapbox/vector-tile-spec/tree/master/2.1#42-features">feature identifier</a> - (`id`) in the tile source. 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: + (`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: <table> <thead> @@ -50,22 +61,40 @@ NS_ASSUME_NONNULL_BEGIN For details about the identifiers used in most Mapbox-provided styles, consult the <a href="https://www.mapbox.com/vector-tiles/mapbox-streets/">Mapbox Streets</a> - layer reference. 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. + 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. */ @property (nonatomic, copy, nullable) id identifier; /** - A dictionary of attributes for this feature specified by the - <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources">tile source</a>. + 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`. - The keys and values of this dictionary are determined by the tile source. In - the tile 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: + 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: <table> <thead> @@ -85,7 +114,9 @@ NS_ASSUME_NONNULL_BEGIN <a href="https://www.mapbox.com/vector-tiles/mapbox-streets/">Mapbox Streets</a> and <a href="https://www.mapbox.com/vector-tiles/mapbox-terrain/">Mapbox Terrain</a> - layer references. Note that while it is possible to change this value on feature + 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 @@ -115,56 +146,75 @@ NS_ASSUME_NONNULL_BEGIN @end /** - The `MGLPointFeature` class represents a point in a - <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources">tile source</a>. + An `MGLPointFeature` object associates a point shape with an optional + identifier and attributes. */ MGL_EXPORT @interface MGLPointFeature : MGLPointAnnotation <MGLFeature> @end /** - The `MGLPolylineFeature` class represents a polyline in a - <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources">tile source</a>. + An `MGLPolylineFeature` object associates a polyline shape with an optional + identifier and attributes. + + A polyline feature is known as a + <a href="https://tools.ietf.org/html/rfc7946#section-3.1.4">LineString</a> + feature in GeoJSON. */ MGL_EXPORT @interface MGLPolylineFeature : MGLPolyline <MGLFeature> @end /** - The `MGLPolygonFeature` class represents a polygon in a - <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources">tile source</a>. + An `MGLPolygonFeature` object associates a polygon shape with an optional + identifier and attributes. */ MGL_EXPORT @interface MGLPolygonFeature : MGLPolygon <MGLFeature> @end /** - The `MGLPointCollectionFeature` class represents a multipoint in a - <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources">tile source</a>. + An `MGLPointCollectionFeature` object associates a point collection with an + optional identifier and attributes. + + A point collection feature is known as a + <a href="https://tools.ietf.org/html/rfc7946#section-3.1.3">MultiPoint</a> + feature in GeoJSON. */ MGL_EXPORT @interface MGLPointCollectionFeature : MGLPointCollection <MGLFeature> @end +// https://github.com/mapbox/mapbox-gl-native/issues/7473 +@compatibility_alias MGLMultiPointFeature MGLPointCollectionFeature; + /** - The `MGLMultiPolylineFeature` class represents a multipolyline in a - <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources">tile source</a>. + An `MGLMultiPolylineFeature` object associates a multipolyline shape with an + optional identifier and attributes. + + A multipolyline feature is known as a + <a href="https://tools.ietf.org/html/rfc7946#section-3.1.5">MultiLineString</a> + feature in GeoJSON. */ MGL_EXPORT @interface MGLMultiPolylineFeature : MGLMultiPolyline <MGLFeature> @end /** - The `MGLMultiPolygonFeature` class represents a multipolygon in a - <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources">tile source</a>. + An `MGLMultiPolygonFeature` object associates a multipolygon shape with an + optional identifier and attributes. */ MGL_EXPORT @interface MGLMultiPolygonFeature : MGLMultiPolygon <MGLFeature> @end /** - The `MGLShapeCollectionFeature` class represents a shape collection in a - <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources">tile source</a>. + An `MGLShapeCollectionFeature` object associates a shape collection with an + optional identifier and attributes. + + A shape collection feature is known as a + <a href="https://tools.ietf.org/html/rfc7946#section-3.3">feature collection</a> + in GeoJSON. */ MGL_EXPORT @interface MGLShapeCollectionFeature : MGLShapeCollection <MGLFeature> |