From 3fed3c10edb2cd015bd733a22c56ace7af900ef8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Minh=20Nguye=CC=82=CC=83n?= Date: Thu, 8 Dec 2016 03:40:59 -0800 Subject: [ios, macos] Expanded source documentation Also fixed a few stray references to GeoJSON sources. --- platform/darwin/src/MGLAttributionInfo.h | 2 +- platform/darwin/src/MGLRasterSource.h | 17 +++++++++++------ platform/darwin/src/MGLShapeSource.h | 27 ++++++++++++++++----------- platform/darwin/src/MGLSource.h | 18 +++++++++++++----- platform/darwin/src/MGLVectorSource.h | 22 +++++++++++++++++----- platform/darwin/test/MGLStyleTests.mm | 4 ++-- platform/darwin/test/MGLStyleValueTests.swift | 4 ++-- platform/ios/CHANGELOG.md | 2 +- platform/macos/CHANGELOG.md | 2 +- 9 files changed, 64 insertions(+), 34 deletions(-) (limited to 'platform') 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 The - style specification. + `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://`). + @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://`). + 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://`). @see The TileJSON specification. 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 The - style specification. + `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 + GeoJSON 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 /** - 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 + Mapbox Vector Tile 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 The - style specification. + Within each vector tile, each geometric coordinate must lie between + −1 × extent and + (extent × 2) − 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://`). + @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://`). + 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://`). 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] = [ 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)) -- cgit v1.2.1