From 1254bcdb4006d87fefedfc5020b3dc7d3cd0e544 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Minh=20Nguy=E1=BB=85n?= Date: Tue, 20 Dec 2016 16:11:05 -0800 Subject: [ios, macos] Update and reformat documentation for runtime styling (#7475) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [ios, macos] Optimized changelog for runtime styling Changelog entries related to style JSON now lead off with the analogous portion of the runtime styling API. * [ios, macos] Autolink cross-class property references in docs jazzy can autolink `Class.property` references in documentation comments. * [ios, macos] Removed extra blank lines * [ios, macos] Corrected typo in MGLMultiPoint docs * [ios, macos] Rewrote shape and feature docs Rewrote documentation about MGLShape, its subclasses, and MGLFeature to emphasize runtime styling uses over annotation uses, associate each type with real-world concepts, cross-reference related style layer classes, and cross-reference related or easily confused shape classes. Links to the GeoJSON specification have been updated to RFC 7946. * [ios, macos] Expanded style layer docs With this change, documentation about style layer classes is nominally based on the documentation in the style specification. However, all the existing layer types’ documentation has been overridden to explain what the layer looks like, relate the layer to a real-world concept, and cross-reference related geometry classes. This change also corrects the description of MGLBackgroundStyleLayer, which erroneously stated that the identifier must be “background”, whereas that only happens to be true by default for Studio template styles. * [ios, macos] Wrap style layer docs * [ios, macos] Removed unused code * [ios, macos] Corrected symbol references in docs * [ios, macos] Corrected typo in abstract class exception --- platform/darwin/src/MGLStyle.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'platform/darwin/src/MGLStyle.h') diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h index 96dd502c30..1e0b87a73f 100644 --- a/platform/darwin/src/MGLStyle.h +++ b/platform/darwin/src/MGLStyle.h @@ -40,7 +40,7 @@ static const NSInteger MGLStyleDefaultVersion = 9; via `-[MGLMapView style]` by updating the style's data sources or layers. @note Wait until the map style has finished loading before modifying a map's - style via any of the MGLStyle instance methods below. + style via any of the `MGLStyle` instance methods below. You can use the `MGLMapViewDelegate` methods `-mapViewDidFinishLoadingMap:` or `-mapView:didFinishLoadingStyle:` as indicators that it's safe to modify the map's style. -- cgit v1.2.1 From 916cd6c310ee4b7978efa9010123673f067ca6a9 Mon Sep 17 00:00:00 2001 From: Fredrik Karlsson Date: Mon, 19 Dec 2016 15:58:38 +0100 Subject: [ios, macos] reversed MGLStyle.layers --- platform/darwin/src/MGLStyle.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'platform/darwin/src/MGLStyle.h') diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h index 1e0b87a73f..cc87d7defd 100644 --- a/platform/darwin/src/MGLStyle.h +++ b/platform/darwin/src/MGLStyle.h @@ -237,7 +237,7 @@ static const NSInteger MGLStyleDefaultVersion = 9; #pragma mark Managing Style Layers /** - The layers included in the style, arranged according to their front-to-back + The layers included in the style, arranged according to their back-to-front ordering on the screen. */ @property (nonatomic, strong) NS_MUTABLE_ARRAY_OF(MGLStyleLayer *) *layers; -- cgit v1.2.1 From b6f7d03e5d4cb632dd3c59e3c6451e33fadca945 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Minh=20Nguye=CC=82=CC=83n?= Date: Fri, 23 Dec 2016 15:01:00 -0800 Subject: [ios, macos] Sources, layers properties are immutable If you need a mutable array of layers, use -mutableArrayValueForKey:. --- platform/darwin/src/MGLStyle.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'platform/darwin/src/MGLStyle.h') diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h index cc87d7defd..58bc57b4fa 100644 --- a/platform/darwin/src/MGLStyle.h +++ b/platform/darwin/src/MGLStyle.h @@ -189,7 +189,7 @@ static const NSInteger MGLStyleDefaultVersion = 9; /** A set containing the style’s sources. */ -@property (nonatomic, strong) NS_MUTABLE_SET_OF(MGLSource *) *sources; +@property (nonatomic, strong) NS_SET_OF(MGLSource *) *sources; /** Returns a source with the given identifier in the current style. @@ -240,7 +240,7 @@ static const NSInteger MGLStyleDefaultVersion = 9; The layers included in the style, arranged according to their back-to-front ordering on the screen. */ -@property (nonatomic, strong) NS_MUTABLE_ARRAY_OF(MGLStyleLayer *) *layers; +@property (nonatomic, strong) NS_ARRAY_OF(MGLStyleLayer *) *layers; /** Returns a style layer with the given identifier in the current style. -- cgit v1.2.1 From 4700c72e1501aca9509d9e051b1afc2d2112597e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Minh=20Nguye=CC=82=CC=83n?= Date: Fri, 23 Dec 2016 15:14:54 -0800 Subject: [ios, macos] Relaxed sources, layers type MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refined the types of MGLStyle’s sources and layers types so that Objective-C code can easily send messages intended for subclasses of MGLSource or MGLStyleLayer that are contained in one of these containers. --- platform/darwin/src/MGLStyle.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'platform/darwin/src/MGLStyle.h') diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h index 58bc57b4fa..ea7f8ed5cb 100644 --- a/platform/darwin/src/MGLStyle.h +++ b/platform/darwin/src/MGLStyle.h @@ -189,7 +189,7 @@ static const NSInteger MGLStyleDefaultVersion = 9; /** A set containing the style’s sources. */ -@property (nonatomic, strong) NS_SET_OF(MGLSource *) *sources; +@property (nonatomic, strong) NS_SET_OF(__kindof MGLSource *) *sources; /** Returns a source with the given identifier in the current style. @@ -240,7 +240,7 @@ static const NSInteger MGLStyleDefaultVersion = 9; The layers included in the style, arranged according to their back-to-front ordering on the screen. */ -@property (nonatomic, strong) NS_ARRAY_OF(MGLStyleLayer *) *layers; +@property (nonatomic, strong) NS_ARRAY_OF(__kindof MGLStyleLayer *) *layers; /** Returns a style layer with the given identifier in the current style. -- cgit v1.2.1 From 226054bf7186bed5269e7de5ca23f2e4bb2df002 Mon Sep 17 00:00:00 2001 From: Jesse Bounds Date: Sun, 8 Jan 2017 17:08:24 -0800 Subject: Document requirement about adding sources and layers (#7634) * [ios, macos] Document requirement about adding sources and layers Sources and layers added outside of mapView:didFinishLoadingStyle: and mapViewDidFinishLoadingMap: are not guaranteed to appear since the map may not be fully loaded and ready to accept new sources and layers. This also fixes a compiler warning in iosapp. --- platform/darwin/src/MGLStyle.h | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-) (limited to 'platform/darwin/src/MGLStyle.h') diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h index ea7f8ed5cb..fcb464a303 100644 --- a/platform/darwin/src/MGLStyle.h +++ b/platform/darwin/src/MGLStyle.h @@ -40,10 +40,10 @@ static const NSInteger MGLStyleDefaultVersion = 9; via `-[MGLMapView style]` by updating the style's data sources or layers. @note Wait until the map style has finished loading before modifying a map's - style via any of the `MGLStyle` instance methods below. - You can use the `MGLMapViewDelegate` methods `-mapViewDidFinishLoadingMap:` - or `-mapView:didFinishLoadingStyle:` as indicators that it's safe - to modify the map's style. + style via any of the `MGLStyle` instance methods below. You can use the + `-[MGLMapViewDelegate mapView:didFinishLoadingStyle:]` or + `-[MGLMapViewDelegate mapViewDidFinishLoadingMap:]` methods as indicators + that it's safe to modify the map's style. */ @interface MGLStyle : NSObject @@ -213,8 +213,13 @@ static const NSInteger MGLStyleDefaultVersion = 9; @note Adding the same source instance more than once will result in a `MGLRedundantSourceException`. Reusing the same source identifier, even with different source instances, will result in a - `MGLRedundantSourceIdentifierException`. + `MGLRedundantSourceIdentifierException`. + @note Sources should be added in + `-[MGLMapViewDelegate mapView:didFinishLoadingStyle:]` or + `-[MGLMapViewDelegate mapViewDidFinishLoadingMap:]` to ensure that the map + has loaded the style and is ready to accept a new source. + @param source The source to add to the current style. */ - (void)addSource:(MGLSource *)source; @@ -264,7 +269,12 @@ static const NSInteger MGLStyleDefaultVersion = 9; @note Adding the same layer instance more than once will result in a `MGLRedundantLayerException`. Reusing the same layer identifer, even with - different layer instances, will also result in an exception. + different layer instances, will also result in an exception. + + @note Layers should be added in + `-[MGLMapViewDelegate mapView:didFinishLoadingStyle:]` or + `-[MGLMapViewDelegate mapViewDidFinishLoadingMap:]` to ensure that the map + has loaded the style and is ready to accept a new layer. @param layer The layer object to add to the map view. This object must be an instance of a concrete subclass of `MGLStyleLayer`. @@ -276,7 +286,12 @@ static const NSInteger MGLStyleDefaultVersion = 9; @note Adding the same layer instance more than once will result in a `MGLRedundantLayerException`. Reusing the same layer identifer, even with - different layer instances, will also result in an exception. + different layer instances, will also result in an exception. + + @note Layers should be added in + `-[MGLMapViewDelegate mapView:didFinishLoadingStyle:]` or + `-[MGLMapViewDelegate mapViewDidFinishLoadingMap:]` to ensure that the map + has loaded the style and is ready to accept a new layer. @param layer The layer to insert. @param index The index at which to insert the layer. An index of 0 would send -- cgit v1.2.1