diff options
author | Jesse Bounds <jesse@rebounds.net> | 2016-11-30 09:26:21 -0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2016-11-30 09:26:21 -0800 |
commit | ba775404d88ddb61b7347eb14c5e39cf2df8e1dd (patch) | |
tree | 44d515103e19ebbc12d3808d93b5686f9b3c7e2a /platform/darwin | |
parent | 17db5210bf60171ee7dbc15de77fdea53b8f0d4d (diff) | |
download | qtlocation-mapboxgl-ba775404d88ddb61b7347eb14c5e39cf2df8e1dd.tar.gz |
[ios, macos] Add notes to APIs that rely on style and source ids (#6886)
Update documentation to make the implications of identifiers clearer.
Diffstat (limited to 'platform/darwin')
-rw-r--r-- | platform/darwin/src/MGLStyle.h | 64 |
1 files changed, 64 insertions, 0 deletions
diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h index b3e1b28eee..10fad0196e 100644 --- a/platform/darwin/src/MGLStyle.h +++ b/platform/darwin/src/MGLStyle.h @@ -184,6 +184,14 @@ static const NSInteger MGLStyleDefaultVersion = 9; /** Returns a source with the given identifier in the current style. + @note Source identifiers are not guaranteed to exist across styles or different + versions of the same style. Applications that use this API must first set the + style URL to an explicitly versioned style using a convenience method like + `+[MGLStyle outdoorsStyleURLWithVersion:]`, `MGLMapView`'s “Style URL” + inspectable in Interface Builder, or a manually constructed `NSURL`. This + approach also avoids source identifer name changes that will occur in the default + style’s sources over time. + @return An instance of a concrete subclass of `MGLSource` associated with the given identifier, or `nil` if the current style contains no such source. */ @@ -199,6 +207,14 @@ static const NSInteger MGLStyleDefaultVersion = 9; /** Removes a source from the current style. + @note Source identifiers are not guaranteed to exist across styles or different + versions of the same style. Applications that use this API must first set the + style URL to an explicitly versioned style using a convenience method like + `+[MGLStyle outdoorsStyleURLWithVersion:]`, `MGLMapView`'s “Style URL” + inspectable in Interface Builder, or a manually constructed `NSURL`. This + approach also avoids source identifer name changes that will occur in the default + style’s sources over time. + @param source The source to remove from the current style. */ - (void)removeSource:(MGLSource *)source; @@ -214,6 +230,14 @@ static const NSInteger MGLStyleDefaultVersion = 9; /** Returns a style layer with the given identifier in the current style. + @note Layer identifiers are not guaranteed to exist across styles or different + versions of the same style. Applications that use this API must first set + the style URL to an explicitly versioned style using a convenience method like + `+[MGLStyle outdoorsStyleURLWithVersion:]`, `MGLMapView`'s “Style URL” + inspectable in Interface Builder, or a manually constructed `NSURL`. This + approach also avoids layer identifer name changes that will occur in the default + style’s layers over time. + @return An instance of a concrete subclass of `MGLStyleLayer` associated with the given identifier, or `nil` if the current style contains no such style layer. @@ -240,6 +264,14 @@ static const NSInteger MGLStyleDefaultVersion = 9; /** Inserts a new layer below another layer. + + @note Layer identifiers are not guaranteed to exist across styles or different + versions of the same style. Applications that use this API must first set + the style URL to an explicitly versioned style using a convenience method like + `+[MGLStyle outdoorsStyleURLWithVersion:]`, `MGLMapView`'s “Style URL” + inspectable in Interface Builder, or a manually constructed `NSURL`. This + approach also avoids layer identifer name changes that will occur in the default + style’s layers over time. @param layer The layer to insert. @param sibling An existing layer in the style. @@ -248,6 +280,14 @@ static const NSInteger MGLStyleDefaultVersion = 9; /** Inserts a new layer above another layer. + + @note Layer identifiers are not guaranteed to exist across styles or different + versions of the same style. Applications that use this API must first set + the style URL to an explicitly versioned style using a convenience method like + `+[MGLStyle outdoorsStyleURLWithVersion:]`, `MGLMapView`'s “Style URL” + inspectable in Interface Builder, or a manually constructed `NSURL`. This + approach also avoids layer identifer name changes that will occur in the default + style’s layers over time. @param layer The layer to insert. @param sibling An existing layer in the style. @@ -256,6 +296,14 @@ static const NSInteger MGLStyleDefaultVersion = 9; /** Removes a layer from the map view. + + @note Layer identifiers are not guaranteed to exist across styles or different + versions of the same style. Applications that use this API must first set + the style URL to an explicitly versioned style using a convenience method like + `+[MGLStyle outdoorsStyleURLWithVersion:]`, `MGLMapView`'s “Style URL” + inspectable in Interface Builder, or a manually constructed `NSURL`. This + approach also avoids layer identifer name changes that will occur in the default + style’s layers over time. @param layer The layer object to remove from the map view. This object must conform to the `MGLStyleLayer` protocol. @@ -287,6 +335,14 @@ static const NSInteger MGLStyleDefaultVersion = 9; /** Deactivates the style class with the given identifier. + + @note Style class names are not guaranteed to exist across styles or different + versions of the same style. Applications that use this API must first set the + style URL to an explicitly versioned style using a convenience method like + `+[MGLStyle outdoorsStyleURLWithVersion:]`, `MGLMapView`'s “Style URL” + inspectable in Interface Builder, or a manually constructed `NSURL`. This + approach also avoids style class name changes that will occur in the default + style over time. @param styleClass The style class to deactivate. */ @@ -307,6 +363,14 @@ static const NSInteger MGLStyleDefaultVersion = 9; /** Removes a name and its associated image from the style. + + @note Names and their associated images are not guaranteed to exist across + styles or different versions of the same style. Applications that use this + API must first set the style URL to an explicitly versioned style using a + convenience method like `+[MGLStyle outdoorsStyleURLWithVersion:]`, + `MGLMapView`'s “Style URL” inspectable in Interface Builder, or a manually + constructed `NSURL`. This approach also avoids image name changes that will + occur in the default style over time. @param name The name of the image to remove. */ |