summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMinh Nguyễn <mxn@1ec5.org>2016-12-08 03:40:59 -0800
committerMinh Nguyễn <mxn@1ec5.org>2016-12-10 14:58:01 -0800
commit3fed3c10edb2cd015bd733a22c56ace7af900ef8 (patch)
tree94705abe7ece234a4c123204cfdc5416a5f120d1
parent7f75eb5d6ae014391f3baf066a9873c5fb1c1ded (diff)
downloadqtlocation-mapboxgl-3fed3c10edb2cd015bd733a22c56ace7af900ef8.tar.gz
[ios, macos] Expanded source documentation
Also fixed a few stray references to GeoJSON sources.
-rw-r--r--platform/darwin/src/MGLAttributionInfo.h2
-rw-r--r--platform/darwin/src/MGLRasterSource.h17
-rw-r--r--platform/darwin/src/MGLShapeSource.h27
-rw-r--r--platform/darwin/src/MGLSource.h18
-rw-r--r--platform/darwin/src/MGLVectorSource.h22
-rw-r--r--platform/darwin/test/MGLStyleTests.mm4
-rw-r--r--platform/darwin/test/MGLStyleValueTests.swift4
-rw-r--r--platform/ios/CHANGELOG.md2
-rw-r--r--platform/macos/CHANGELOG.md2
9 files changed, 64 insertions, 34 deletions
diff --git a/platform/darwin/src/MGLAttributionInfo.h b/platform/darwin/src/MGLAttributionInfo.h
index c0cb1578b5..84552722c9 100644
--- a/platform/darwin/src/MGLAttributionInfo.h
+++ b/platform/darwin/src/MGLAttributionInfo.h
@@ -8,7 +8,7 @@ NS_ASSUME_NONNULL_BEGIN
/**
Information about an attribution statement, usually a copyright or trademark
- statement, associated with a map source.
+ statement, associated with a map content source.
*/
@interface MGLAttributionInfo : NSObject
diff --git a/platform/darwin/src/MGLRasterSource.h b/platform/darwin/src/MGLRasterSource.h
index 78f5af8a6a..2940f05371 100644
--- a/platform/darwin/src/MGLRasterSource.h
+++ b/platform/darwin/src/MGLRasterSource.h
@@ -8,10 +8,12 @@
NS_ASSUME_NONNULL_BEGIN
/**
- A raster tile source.
-
- @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-raster">The
- style specification.</a>
+ `MGLRasterSource` is a map content source that supplies raster image tiles to
+ be shown on the map. The location of and metadata about the raster tiles are
+ defined by either an `MGLTileSet` object or an external TileJSON resource. A
+ raster source is added to an `MGLStyle` object along with an
+ `MGLRasterStyleLayer` object. Use a raster style layer to control the
+ appearance of content supplied by the raster source.
*/
@interface MGLRasterSource : MGLSource
@@ -24,6 +26,9 @@ NS_ASSUME_NONNULL_BEGIN
After initializing and configuring the source, add it to a map view’s style
using the `-[MGLStyle addSource:]` method.
+ The URL may be a full HTTP or HTTPS URL or, for tile sets hosted by Mapbox, a
+ Mapbox URL indicating a map identifier (`mapbox://<mapid>`).
+
@param identifier A string that uniquely identifies the source in the style to
which it is added.
@param url A URL to a TileJSON configuration file describing the source’s
@@ -56,8 +61,8 @@ NS_ASSUME_NONNULL_BEGIN
A URL to a TileJSON configuration file describing the source’s contents and
other metadata.
- The URL may be a full HTTP or HTTPS URL or a Mapbox URL indicating the tile
- set’s map ID (`mapbox://<mapid>`).
+ The URL may be a full HTTP or HTTPS URL or, for tile sets hosted by Mapbox, a
+ Mapbox URL indicating a map identifier (`mapbox://<mapid>`).
@see <a href="https://www.mapbox.com/help/an-open-platform/#tilejson">The
TileJSON specification.</a>
diff --git a/platform/darwin/src/MGLShapeSource.h b/platform/darwin/src/MGLShapeSource.h
index 5067466e6d..407d9c45a1 100644
--- a/platform/darwin/src/MGLShapeSource.h
+++ b/platform/darwin/src/MGLShapeSource.h
@@ -57,10 +57,15 @@ extern const MGLShapeSourceOption MGLShapeSourceOptionBuffer;
extern const MGLShapeSourceOption MGLShapeSourceOptionSimplificationTolerance;
/**
- A shape source.
-
- @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson">The
- style specification.</a>
+ `MGLShapeSource` is a map content source that supplies vector shapes to be
+ shown on the map. The shapes may be instances of `MGLShape` or `MGLFeature`,
+ or they may be defined by local or external
+ <a href="http://geojson.org/">GeoJSON</a> code. A shape source is added to an
+ `MGLStyle` object along with an `MGLVectorStyleLayer` object. The vector style
+ layer defines the appearance of any content supplied by the shape source.
+
+ Any vector style layer initialized with a shape source should have a `nil`
+ value in its `sourceLayerIdentifier` property.
*/
@interface MGLShapeSource : MGLSource
@@ -109,12 +114,12 @@ extern const MGLShapeSourceOption MGLShapeSourceOptionSimplificationTolerance;
#pragma mark Accessing a Source’s Content
/**
- The contents of the source. A shape can represent a GeoJSON geometry, a feature,
- or a collection of features.
+ The contents of the source. A shape can represent a GeoJSON geometry, a
+ feature, or a collection of features.
- If the receiver was initialized using `-initWithIdentifier:URL:options:`, this property
- is set to `nil`. This property is unavailable until the receiver is passed into
- `-[MGLStyle addSource]`.
+ If the receiver was initialized using `-initWithIdentifier:URL:options:`, this
+ property is set to `nil`. This property is unavailable until the receiver is
+ passed into `-[MGLStyle addSource]`.
*/
@property (nonatomic, nullable) MGLShape *shape;
@@ -135,8 +140,8 @@ extern const MGLShapeSourceOption MGLShapeSourceOptionSimplificationTolerance;
/**
The URL to the GeoJSON document that specifies the contents of the source.
- If the receiver was initialized using `-initWithIdentifier:geoJSONData:options`,
- this property is set to `nil`.
+ If the receiver was initialized using
+ `-initWithIdentifier:geoJSONData:options`, this property is set to `nil`.
*/
@property (nonatomic, nullable) NSURL *URL;
diff --git a/platform/darwin/src/MGLSource.h b/platform/darwin/src/MGLSource.h
index ec3733bf08..f0a8aacecb 100644
--- a/platform/darwin/src/MGLSource.h
+++ b/platform/darwin/src/MGLSource.h
@@ -1,12 +1,20 @@
#import <Foundation/Foundation.h>
/**
- A source supplies data to be shown on the map. Sources don't contain styling
- details like color or width. Use subclasses of `MGLStyleLayer` to give visual
- representation to sources.
+ `MGLSource` is an abstract base class for map content sources. A map content
+ source supplies content to be shown on the map. A source is added to an
+ `MGLStyle` object along with an `MGLForegroundStyleLayer` object. The
+ foreground style layer defines the appearance of any content supplied by the
+ source.
- You should use the concrete subclasses of `MGLSource` to create vector,
- raster, GeoJSON, and other source types.
+ Each source defined by the style JSON file is represented at runtime by an
+ `MGLSource` object that you can use to refine the map’s content. You can also
+ add and remove sources dynamically using methods such as
+ `-[MGLStyle addSource:]` and `-[MGLStyle sourceWithIdentifier:]`.
+
+ Do not create instances of this class directly, and do not create your own
+ subclasses of this class. Instead, create instances of `MGLRasterSource`,
+ `MGLShapeSource`, and `MGLVectorSource`.
*/
@interface MGLSource : NSObject
diff --git a/platform/darwin/src/MGLVectorSource.h b/platform/darwin/src/MGLVectorSource.h
index 6cfab09489..758b4c993f 100644
--- a/platform/darwin/src/MGLVectorSource.h
+++ b/platform/darwin/src/MGLVectorSource.h
@@ -6,10 +6,19 @@
NS_ASSUME_NONNULL_BEGIN
/**
- A vector tile source. Tiles must be in Mapbox Vector Tile format.
+ `MGLVectorSource` is a map content source that supplies tiled vector data in
+ <a href="https://www.mapbox.com/vector-tiles/">Mapbox Vector Tile</a> format to
+ be shown on the map. The location of and metadata about the vector tiles are
+ defined by either an `MGLTileSet` object or an external TileJSON resource. A
+ vector source is added to an `MGLStyle` object along with an
+ `MGLVectorStyleLayer` object. The vector style layer defines the appearance of
+ any content supplied by the vector source.
- @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-vector">The
- style specification.</a>
+ Within each vector tile, each geometric coordinate must lie between
+ −1&nbsp;×&nbsp;<var>extent</var> and
+ (<var>extent</var>&nbsp;×&nbsp;2)&nbsp;−&nbsp;1, inclusive. Any vector style
+ layer initialized with a vector source must have a non-`nil` value in its
+ `sourceLayerIdentifier` property.
*/
@interface MGLVectorSource : MGLSource
@@ -21,6 +30,9 @@ NS_ASSUME_NONNULL_BEGIN
After initializing and configuring the source, add it to a map view’s style
using the `-[MGLStyle addSource:]` method.
+ The URL may be a full HTTP or HTTPS URL or, for tile sets hosted by Mapbox, a
+ Mapbox URL indicating a map identifier (`mapbox://<mapid>`).
+
@param identifier A string that uniquely identifies the source in the style to
which it is added.
@param url A URL to a TileJSON configuration file describing the source’s
@@ -48,8 +60,8 @@ NS_ASSUME_NONNULL_BEGIN
A URL to a TileJSON configuration file describing the source’s contents and
other metadata.
- The URL may be a full HTTP or HTTPS URL or a Mapbox URL indicating the tile
- set’s map ID (`mapbox://<mapid>`).
+ The URL may be a full HTTP or HTTPS URL or, for tile sets hosted by Mapbox, a
+ Mapbox URL indicating a map identifier (`mapbox://<mapid>`).
If the receiver was initialized using `-initWithIdentifier:tileSet:`, this
property is set to `nil`.
diff --git a/platform/darwin/test/MGLStyleTests.mm b/platform/darwin/test/MGLStyleTests.mm
index f2151988b9..0dd6e98c5d 100644
--- a/platform/darwin/test/MGLStyleTests.mm
+++ b/platform/darwin/test/MGLStyleTests.mm
@@ -121,7 +121,7 @@
}
- (void)testAddingSourcesTwice {
- MGLShapeSource *shapeSource = [[MGLShapeSource alloc] initWithIdentifier:@"geoJSONSource" shape:nil options:nil];
+ MGLShapeSource *shapeSource = [[MGLShapeSource alloc] initWithIdentifier:@"shapeSource" shape:nil options:nil];
[self.style addSource:shapeSource];
XCTAssertThrowsSpecificNamed([self.style addSource:shapeSource], NSException, @"MGLRedundantSourceException");
@@ -143,7 +143,7 @@
}
- (void)testAddingLayersTwice {
- MGLShapeSource *source = [[MGLShapeSource alloc] initWithIdentifier:@"geoJSONSource" shape:nil options:nil];
+ MGLShapeSource *source = [[MGLShapeSource alloc] initWithIdentifier:@"shapeSource" shape:nil options:nil];
MGLBackgroundStyleLayer *backgroundLayer = [[MGLBackgroundStyleLayer alloc] initWithIdentifier:@"backgroundLayer"];
[self.style addLayer:backgroundLayer];
diff --git a/platform/darwin/test/MGLStyleValueTests.swift b/platform/darwin/test/MGLStyleValueTests.swift
index 2d2792fdc0..e529af0634 100644
--- a/platform/darwin/test/MGLStyleValueTests.swift
+++ b/platform/darwin/test/MGLStyleValueTests.swift
@@ -22,8 +22,8 @@ extension MGLStyleValueTests {
}
func testFunctions() {
- let geoJSONSource = MGLShapeSource(identifier: "test", shape: nil, options: nil)
- let symbolStyleLayer = MGLSymbolStyleLayer(identifier: "test", source: geoJSONSource)
+ let shapeSource = MGLShapeSource(identifier: "test", shape: nil, options: nil)
+ let symbolStyleLayer = MGLSymbolStyleLayer(identifier: "test", source: shapeSource)
// Boolean
let stops: [NSNumber: MGLStyleValue<NSNumber>] = [
diff --git a/platform/ios/CHANGELOG.md b/platform/ios/CHANGELOG.md
index 5c63bdd2f5..565b709214 100644
--- a/platform/ios/CHANGELOG.md
+++ b/platform/ios/CHANGELOG.md
@@ -14,7 +14,7 @@ Mapbox welcomes participation and contributions from everyone. Please read [CONT
* A new runtime styling API allows you to adjust the style and content of the base map dynamically. All the options available in [Mapbox Studio](https://www.mapbox.com/studio/) are now exposed via MGLStyle and subclasses of MGLStyleLayer and MGLSource. ([#5727](https://github.com/mapbox/mapbox-gl-native/pull/5727))
* MGLMapView’s `styleURL` property can now be set to an absolute file URL. ([#6026](https://github.com/mapbox/mapbox-gl-native/pull/6026))
-* GeoJSON sources specified by the stylesheet at design time now support `cluster`, `clusterMaxZoom`, and `clusterRadius` attributes for clustering point features on the base map. ([#5724](https://github.com/mapbox/mapbox-gl-native/pull/5724))
+* MGLShapeSource objects, as well as GeoJSON sources specified by the stylesheet at design time, now support `cluster`, `clusterMaxZoom`, and `clusterRadius` attributes for clustering point features on the base map. ([#5724](https://github.com/mapbox/mapbox-gl-native/pull/5724))
* Added [quadkey](https://msdn.microsoft.com/en-us/library/bb259689.aspx) support and limited WMS support in raster tile URL templates. ([#5628](https://github.com/mapbox/mapbox-gl-native/pull/5628))
* TileJSON manifests can now specify `"scheme": "tms"` to indicate the use of [TMS](https://en.wikipedia.org/wiki/Tile_Map_Service) coordinates. ([#2270](https://github.com/mapbox/mapbox-gl-native/pull/2270))
* Fixed an issue causing abstract MGLMultiPointFeature objects to be returned in feature query results. Now concrete MGLPointCollectionFeature objects are returned. ([#6742](https://github.com/mapbox/mapbox-gl-native/pull/6742))
diff --git a/platform/macos/CHANGELOG.md b/platform/macos/CHANGELOG.md
index ab85890edb..8482cc5e0b 100644
--- a/platform/macos/CHANGELOG.md
+++ b/platform/macos/CHANGELOG.md
@@ -13,7 +13,7 @@
* A new runtime styling API allows you to adjust the style and content of the base map dynamically. All the options available in [Mapbox Studio](https://www.mapbox.com/studio/) are now exposed via MGLStyle and subclasses of MGLStyleLayer and MGLSource. ([#5727](https://github.com/mapbox/mapbox-gl-native/pull/5727))
* MGLMapView’s `styleURL` property can now be set to an absolute file URL. ([#6026](https://github.com/mapbox/mapbox-gl-native/pull/6026))
-* GeoJSON sources specified by the stylesheet at design time now support `cluster`, `clusterMaxZoom`, and `clusterRadius` attributes for clustering point features on the base map. ([#5724](https://github.com/mapbox/mapbox-gl-native/pull/5724))
+* MGLShapeSource objects, as well as GeoJSON sources specified by the stylesheet at design time, now support `cluster`, `clusterMaxZoom`, and `clusterRadius` attributes for clustering point features on the base map. ([#5724](https://github.com/mapbox/mapbox-gl-native/pull/5724))
* TileJSON manifests can now specify `"scheme": "tms"` to indicate the use of [TMS](https://en.wikipedia.org/wiki/Tile_Map_Service) coordinates. ([#2270](https://github.com/mapbox/mapbox-gl-native/pull/2270))
* Fixed an issue causing abstract `MGLMultiPointFeature` objects to be returned in feature query results. Now concrete `MGLPointCollectionFeature` objects are returned. ([#6742](https://github.com/mapbox/mapbox-gl-native/pull/6742))
* Fixed rendering artifacts and missing glyphs that occurred after viewing a large number of CJK characters on the map. ([#5908](https://github.com/mapbox/mapbox-gl-native/pull/5908))