[ios, macos] Simplify MGLSource and subclasses (#7377)

* [ios, macos] Audited source headers for nullability

* [macos] Made MGLTileSet public

* [ios, macos] Replaced MGLTileSet with MGLTileSource

MGLRasterSource and MGLVectorSource now share a common abstract superclass, MGLTileSource. MGLTileSet has been removed. MGLTileSource is modeled after mbgl::style::RasterSource and mbgl::style::VectorSource. It has initializers that incorporate the parameters of MGLTileSet’s initializers, but it lacks getters for everything but the attribution string. MGLTileSet’s properties have been converted into options that can be passed into MGLTileSource’s initializers in a dictionary.

Properly implement rawSource as a covariant property so that it doesn’t end up getting autosynthesized as a shadow ivar. This prevents concrete subclasses of MGLSource from setting _rawSource directly but getting a different value out of self.rawSource.

Marked -[MGLSource init] as unavailable and ensured that concrete subclasses of MGLSource have the right set of initializers marked as designated initializers.

Documentation comments for each concrete source class identify the corresponding source type in the style specification. Clarified the purpose of MGLTileSetScheme, now known as MGLTileCoordinateSystem.

* [ios, macos] Clarified tile size interpretation

Sticking to a default value of 256 for mapbox: URLs, but other URLs get the standard 512 value.

* [ios, macos] rawSource is always set

* [ios, macos] Cleaned up MGLShapeSource initialization

rawSource is never nil, so there’s no need for a -commonInit method. Extracted -geoJSONOptions from MGLShapeSource into a standalone function for easier testing.

* [ios, macos] Synchronized headers in project

Realphabetized headers in groups. Added headers missing from one project or the other.

* [ios, macos] Added MGLShape methods to (de)serialize GeoJSON data

Added a class initializer and instance method to MGLShape that deserialize and serialize the shape as GeoJSON data, respectively. The new initializer handles parsing errors gracefully.

Removed methods specific to GeoJSON data from MGLShapeSource, in an effort to reduce parallel state. Developers are now expected to go through the new MGLShape initializer to get an MGLShape representation. Alternatively, a local file URL can be passed into the other MGLShapeSource initializer.

* [ios, macos] Typo in assertion message

* [ios, macos] Simplified GeoJSON serialization

Every MGLShape now knows its most specific mbgl::GeoJSON representation.

* [ios, macos] Reremoved MGLFeaturePrivate

mbgl::GeoJSON, which is a variant, allows a single GeoJSON representation method to traffic in whatever type is needed for a particular shape class. This change removes some hidden private protocols, which are a bug waiting to happen.

* [ios, macos] Fixed covariant rawLayer property

Properly implement rawLayer as a covariant property so that it doesn’t end up getting autosynthesized as a shadow ivar. This prevents concrete subclasses of MGLStyleLayer from setting _rawLayer directly but getting a different value out of self.rawLayer.

* [ios, macos] Use MGLAttributionInfo for source attribution

Made MGLAttributionInfo public. Replaced MGLTileSource’s attribution property with an attributionInfos property set to an array of MGLAttributionInfo objects. Added an MGLTileSourceOption for specifying an array of MGLAttributionInfo objects instead of an HTML string (either is acceptable when creating an MGLTileSource).

* [ios, macos] Corrected method references in documentation

Author: 1ec5

platform/darwin/src/MGLAttributionInfo.h

@@ -13,45 +13,49 @@ NS_ASSUME_NONNULL_BEGIN
 @interface MGLAttributionInfo : NSObject
 
 /**
- Parses and returns the attribution infos contained in the given HTML source
- code string.
+ Returns an initialized attribution info object with the given title and URL.
  
- @param htmlString The HTML source code to parse.
- @param fontSize The default text size in points.
- @param linkColor The default link color.
+ @param title The attribution statement’s title.
+ @param URL A URL to more information about the entity named in the attribution.
+ @return An initialized attribution info object.
  */
-+ (NS_ARRAY_OF(MGLAttributionInfo *) *)attributionInfosFromHTMLString:(NSString *)htmlString fontSize:(CGFloat)fontSize linkColor:(nullable MGLColor *)linkColor;
-
 - (instancetype)initWithTitle:(NSAttributedString *)title URL:(nullable NSURL *)URL;
 
+/**
+ The attribution statement’s attributed title text.
+ */
 @property (nonatomic) NSAttributedString *title;
-@property (nonatomic, nullable) NSURL *URL;
-@property (nonatomic, getter=isFeedbackLink) BOOL feedbackLink;
-
-- (nullable NSURL *)feedbackURLAtCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate zoomLevel:(double)zoomLevel;
 
-@end
-
-@interface NSMutableArray (MGLAttributionInfoAdditions)
+/**
+ The URL to more information about the entity named in the attribution.
+ 
+ If this property is set, the attribution statement should be displayed as a
+ hyperlink or action button. Otherwise, if it is `nil`, the attribution
+ statement should be displayed as plain text.
+ */
+@property (nonatomic, nullable) NSURL *URL;
 
 /**
- Adds the given attribution info object to the receiver as long as it isn’t
- redundant to any object already in the receiver. Any existing object that is
- redundant to the given object is replaced by the given object.
+ A Boolean value indicating whether the attribution statement is a shortcut to a
+ feedback tool.
  
- @param info The info object to add to the receiver.
- @return True if the given info object was added to the receiver.
+ If this property is set, the statement should be treated as a way for the user
+ to provide feedback rather than an attribution statement.
  */
-- (void)growArrayByAddingAttributionInfo:(MGLAttributionInfo *)info;
+@property (nonatomic, getter=isFeedbackLink) BOOL feedbackLink;
 
 /**
- Adds each of the given attribution info objects to the receiver as long as it
- isn’t redundant to any object already in the receiver. Any existing object that
- is redundant to the given object is replaced by the given object.
+ Returns a copy of the `URL` property modified to account for the given center
+ coordinate and zoom level.
  
- @param infos An array of info objects to add to the receiver.
+ @param centerCoordinate The map’s center coordinate.
+ @param zoomLevel The map’s zoom level. See `MGLMapView`’s `zoomLevel` property
+    for more information.
+ @return A modified URL containing a fragment that points to the specified
+    viewport. If the `feedbackLink` property is set to `NO`, this method returns
+    `nil`.
  */
-- (void)growArrayByAddingAttributionInfosFromArray:(NS_ARRAY_OF(MGLAttributionInfo *) *)infos;
+- (nullable NSURL *)feedbackURLAtCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate zoomLevel:(double)zoomLevel;
 
 @end
 

platform/darwin/src/MGLAttributionInfo.mm

@@ -1,4 +1,4 @@
-#import "MGLAttributionInfo.h"
+#import "MGLAttributionInfo_Private.h"
 
 #if TARGET_OS_IPHONE
     #import <UIKit/UIKit.h>
@@ -7,13 +7,18 @@
 #endif
 
 #import "MGLMapCamera.h"
+#import "NSArray+MGLAdditions.h"
 #import "NSString+MGLAdditions.h"
 
 #include <string>
 
 @implementation MGLAttributionInfo
 
-+ (NS_ARRAY_OF(MGLAttributionInfo *) *)attributionInfosFromHTMLString:(NSString *)htmlString fontSize:(CGFloat)fontSize linkColor:(nullable MGLColor *)linkColor {
++ (NS_ARRAY_OF(MGLAttributionInfo *) *)attributionInfosFromHTMLString:(nullable NSString *)htmlString fontSize:(CGFloat)fontSize linkColor:(nullable MGLColor *)linkColor {
+    if (!htmlString) {
+        return @[];
+    }
+    
     NSDictionary *options = @{
         NSDocumentTypeDocumentAttribute: NSHTMLTextDocumentType,
         NSCharacterEncodingDocumentAttribute: @(NSUTF8StringEncoding),
@@ -84,6 +89,18 @@ @implementation MGLAttributionInfo
     return infos;
 }
 
++ (NSAttributedString *)attributedStringForAttributionInfos:(NS_ARRAY_OF(MGLAttributionInfo *) *)attributionInfos {
+    NSMutableArray *titles = [NSMutableArray arrayWithCapacity:attributionInfos.count];
+    for (MGLAttributionInfo *info in attributionInfos) {
+        NSMutableAttributedString *title = info.title.mutableCopy;
+        if (info.URL) {
+            [title addAttribute:NSLinkAttributeName value:info.URL range:title.mgl_wholeRange];
+        }
+        [titles addObject:title];
+    }
+    return [titles mgl_attributedComponentsJoinedByString:@" "];
+}
+
 - (instancetype)initWithTitle:(NSAttributedString *)title URL:(NSURL *)URL {
     if (self = [super init]) {
         _title = title;

platform/darwin/src/MGLAttributionInfo_Private.h

@@ -0,0 +1,48 @@
+#import <Foundation/Foundation.h>
+#import <CoreGraphics/CoreGraphics.h>
+#import <CoreLocation/CoreLocation.h>
+
+#import "MGLAttributionInfo.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface MGLAttributionInfo (Private)
+
+/**
+ Parses and returns the attribution infos contained in the given HTML source
+ code string.
+ 
+ @param htmlString The HTML source code to parse.
+ @param fontSize The default text size in points.
+ @param linkColor The default link color.
+ */
++ (NS_ARRAY_OF(MGLAttributionInfo *) *)attributionInfosFromHTMLString:(nullable NSString *)htmlString fontSize:(CGFloat)fontSize linkColor:(nullable MGLColor *)linkColor;
+
++ (NSAttributedString *)attributedStringForAttributionInfos:(NS_ARRAY_OF(MGLAttributionInfo *) *)attributionInfos;
+
+@end
+
+@interface NSMutableArray (MGLAttributionInfoAdditions)
+
+/**
+ Adds the given attribution info object to the receiver as long as it isn’t
+ redundant to any object already in the receiver. Any existing object that is
+ redundant to the given object is replaced by the given object.
+ 
+ @param info The info object to add to the receiver.
+ @return True if the given info object was added to the receiver.
+ */
+- (void)growArrayByAddingAttributionInfo:(MGLAttributionInfo *)info;
+
+/**
+ Adds each of the given attribution info objects to the receiver as long as it
+ isn’t redundant to any object already in the receiver. Any existing object that
+ is redundant to the given object is replaced by the given object.
+ 
+ @param infos An array of info objects to add to the receiver.
+ */
+- (void)growArrayByAddingAttributionInfosFromArray:(NS_ARRAY_OF(MGLAttributionInfo *) *)infos;
+
+@end
+
+NS_ASSUME_NONNULL_END

platform/darwin/src/MGLBackgroundStyleLayer.mm

@@ -26,11 +26,21 @@ - (instancetype)initWithIdentifier:(NSString *)identifier
     if (self = [super initWithIdentifier:identifier]) {
         auto layer = std::make_unique<mbgl::style::BackgroundLayer>(identifier.UTF8String);
         _pendingLayer = std::move(layer);
-        _rawLayer = _pendingLayer.get();
+        self.rawLayer = _pendingLayer.get();
     }
     return self;
 }
 
+- (mbgl::style::BackgroundLayer *)rawLayer
+{
+    return (mbgl::style::BackgroundLayer *)super.rawLayer;
+}
+
+- (void)setRawLayer:(mbgl::style::BackgroundLayer *)rawLayer
+{
+    super.rawLayer = rawLayer;
+}
+
 #pragma mark -  Adding to and removing from a map view
 
 - (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
@@ -52,7 +62,7 @@ - (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLaye
 - (void)removeFromMapView:(MGLMapView *)mapView
 {
     _pendingLayer = nullptr;
-    _rawLayer = nullptr;
+    self.rawLayer = nullptr;
 
     auto removedLayer = mapView.mbglMap->removeLayer(self.identifier.UTF8String);
     if (!removedLayer) {
@@ -67,7 +77,7 @@ - (void)removeFromMapView:(MGLMapView *)mapView
     removedLayer.release();
 
     _pendingLayer = std::unique_ptr<mbgl::style::BackgroundLayer>(layer);
-    _rawLayer = _pendingLayer.get();
+    self.rawLayer = _pendingLayer.get();
 }
 
 #pragma mark - Accessing the Paint Attributes
@@ -76,41 +86,41 @@ - (void)setBackgroundColor:(MGLStyleValue<MGLColor *> *)backgroundColor {
     MGLAssertStyleLayerIsValid();
 
     auto mbglValue = MGLStyleValueTransformer<mbgl::Color, MGLColor *>().toPropertyValue(backgroundColor);
-    _rawLayer->setBackgroundColor(mbglValue);
+    self.rawLayer->setBackgroundColor(mbglValue);
 }
 
 - (MGLStyleValue<MGLColor *> *)backgroundColor {
     MGLAssertStyleLayerIsValid();
 
-    auto propertyValue = _rawLayer->getBackgroundColor() ?: _rawLayer->getDefaultBackgroundColor();
+    auto propertyValue = self.rawLayer->getBackgroundColor() ?: self.rawLayer->getDefaultBackgroundColor();
     return MGLStyleValueTransformer<mbgl::Color, MGLColor *>().toStyleValue(propertyValue);
 }
 
 - (void)setBackgroundOpacity:(MGLStyleValue<NSNumber *> *)backgroundOpacity {
     MGLAssertStyleLayerIsValid();
 
     auto mbglValue = MGLStyleValueTransformer<float, NSNumber *>().toPropertyValue(backgroundOpacity);
-    _rawLayer->setBackgroundOpacity(mbglValue);
+    self.rawLayer->setBackgroundOpacity(mbglValue);
 }
 
 - (MGLStyleValue<NSNumber *> *)backgroundOpacity {
     MGLAssertStyleLayerIsValid();
 
-    auto propertyValue = _rawLayer->getBackgroundOpacity() ?: _rawLayer->getDefaultBackgroundOpacity();
+    auto propertyValue = self.rawLayer->getBackgroundOpacity() ?: self.rawLayer->getDefaultBackgroundOpacity();
     return MGLStyleValueTransformer<float, NSNumber *>().toStyleValue(propertyValue);
 }
 
 - (void)setBackgroundPattern:(MGLStyleValue<NSString *> *)backgroundPattern {
     MGLAssertStyleLayerIsValid();
 
     auto mbglValue = MGLStyleValueTransformer<std::string, NSString *>().toPropertyValue(backgroundPattern);
-    _rawLayer->setBackgroundPattern(mbglValue);
+    self.rawLayer->setBackgroundPattern(mbglValue);
 }
 
 - (MGLStyleValue<NSString *> *)backgroundPattern {
     MGLAssertStyleLayerIsValid();
 
-    auto propertyValue = _rawLayer->getBackgroundPattern() ?: _rawLayer->getDefaultBackgroundPattern();
+    auto propertyValue = self.rawLayer->getBackgroundPattern() ?: self.rawLayer->getDefaultBackgroundPattern();
     return MGLStyleValueTransformer<std::string, NSString *>().toStyleValue(propertyValue);
 }