Merge branch 'release-ios-v3.4.0' into 1ec5-release-ios-v3.4.0-beta.7

1 files changed, 210 insertions, 55 deletions

diff --git a/platform/darwin/src/MGLLineStyleLayer.h b/platform/darwin/src/MGLLineStyleLayer.h
index 6df0d38088..98f2778291 100644
--- a/platform/darwin/src/MGLLineStyleLayer.h
+++ b/platform/darwin/src/MGLLineStyleLayer.h
@@ -10,19 +10,24 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  The display of line endings.
  
- Values of this type are used in the `lineCap` property of `MGLLineStyleLayer`.
+ Values of this type are used in the `MGLLineStyleLayer.lineCap`
+ property.
  */
 typedef NS_ENUM(NSUInteger, MGLLineCap) {
     /**
-     A cap with a squared-off end which is drawn to the exact endpoint of the line.
+     A cap with a squared-off end which is drawn to the exact endpoint of the
+     line.
      */
     MGLLineCapButt,
     /**
-     A cap with a rounded end which is drawn beyond the endpoint of the line at a radius of one-half of the line's width and centered on the endpoint of the line.
+     A cap with a rounded end which is drawn beyond the endpoint of the line at
+     a radius of one-half of the line's width and centered on the endpoint of
+     the line.
      */
     MGLLineCapRound,
     /**
-     A cap with a squared-off end which is drawn beyond the endpoint of the line at a distance of one-half of the line's width.
+     A cap with a squared-off end which is drawn beyond the endpoint of the line
+     at a distance of one-half of the line's width.
      */
     MGLLineCapSquare,
 };
@@ -30,19 +35,24 @@ typedef NS_ENUM(NSUInteger, MGLLineCap) {
 /**
  The display of lines when joining.
  
- Values of this type are used in the `lineJoin` property of `MGLLineStyleLayer`.
+ Values of this type are used in the `MGLLineStyleLayer.lineJoin`
+ property.
  */
 typedef NS_ENUM(NSUInteger, MGLLineJoin) {
     /**
-     A join with a squared-off end which is drawn beyond the endpoint of the line at a distance of one-half of the line's width.
+     A join with a squared-off end which is drawn beyond the endpoint of the
+     line at a distance of one-half of the line's width.
      */
     MGLLineJoinBevel,
     /**
-     A join with a rounded end which is drawn beyond the endpoint of the line at a radius of one-half of the line's width and centered on the endpoint of the line.
+     A join with a rounded end which is drawn beyond the endpoint of the line at
+     a radius of one-half of the line's width and centered on the endpoint of
+     the line.
      */
     MGLLineJoinRound,
     /**
-     A join with a sharp, angled corner which is drawn with the outer sides beyond the endpoint of the path until they meet.
+     A join with a sharp, angled corner which is drawn with the outer sides
+     beyond the endpoint of the path until they meet.
      */
     MGLLineJoinMiter,
 };
@@ -50,24 +60,49 @@ typedef NS_ENUM(NSUInteger, MGLLineJoin) {
 /**
  Controls the translation reference point.
  
- Values of this type are used in the `lineTranslateAnchor` property of `MGLLineStyleLayer`.
+ Values of this type are used in the `MGLLineStyleLayer.lineTranslationAnchor`
+ property.
  */
-typedef NS_ENUM(NSUInteger, MGLLineTranslateAnchor) {
+typedef NS_ENUM(NSUInteger, MGLLineTranslationAnchor) {
     /**
      The line is translated relative to the map.
      */
-    MGLLineTranslateAnchorMap,
+    MGLLineTranslationAnchorMap,
     /**
      The line is translated relative to the viewport.
      */
-    MGLLineTranslateAnchorViewport,
+    MGLLineTranslationAnchorViewport,
 };
 
 /**
- A line layer which allows customization of styling properties at runtime. You may 
- instantiate a new line layer to add to a map style or you may query an 
- `MGLMapView` for its `style` and obtain existing layers using the 
- `-[MGLStyle layerWithIdentifier:]` method. 
+ An `MGLLineStyleLayer` is a style layer that renders one or more stroked
+ polylines on the map.
+ 
+ Use a line style layer to configure the visual appearance of polyline or
+ multipolyline features in vector tiles loaded by an `MGLVectorSource` object or
+ `MGLPolyline`, `MGLPolylineFeature`, `MGLMultiPolyline`, or
+ `MGLMultiPolylineFeature` instances in an `MGLShapeSource` object.
+ 
+ You can access an existing line style layer using the
+ `-[MGLStyle layerWithIdentifier:]` method if you know its identifier;
+ otherwise, find it using the `MGLStyle.layers` property. You can also create a
+ new line style layer and add it to the style using a method such as
+ `-[MGLStyle addLayer:]`.
+ 
+ ### Example
+ 
+ ```swift
+ let layer = MGLLineStyleLayer(identifier: "trails-path", source: trails)
+ layer.sourceLayerIdentifier = "trails"
+ layer.lineWidth = MGLStyleValue(interpolationBase: 1.5, stops: [
+     14: MGLStyleValue(rawValue: 2),
+     18: MGLStyleValue(rawValue: 20),
+ ])
+ layer.lineColor = MGLStyleValue(rawValue: .brown)
+ layer.lineCap = MGLStyleValue(rawValue: NSValue(mglLineCap: .round))
+ layer.predicate = NSPredicate(format: "%K == %@", "trail-type", "mountain-biking")
+ mapView.style?.addLayer(layer)
+ ```
  */
 MGL_EXPORT
 @interface MGLLineStyleLayer : MGLVectorStyleLayer
@@ -77,32 +112,44 @@ MGL_EXPORT
 /**
  The display of line endings.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSValue` object containing `MGLLineCapButt`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing `MGLLineCapButt`. Set this property to `nil` to
+ reset it to the default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineCap;
 
 /**
  The display of lines when joining.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSValue` object containing `MGLLineJoinMiter`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing `MGLLineJoinMiter`. Set this property to `nil` to
+ reset it to the default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineJoin;
 
 /**
  Used to automatically convert miter joins to bevel joins for sharp angles.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSNumber` object containing the float `2`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSNumber` object containing the float `2`. Set this property to `nil` to reset
+ it to the default value.
  
- This property is only applied to the style if `lineJoin` is set to an `MGLStyleValue` object containing an `NSValue` object containing `MGLLineJoinMiter`. Otherwise, it is ignored.
+ This property is only applied to the style if `lineJoin` is set to an
+ `MGLStyleValue` object containing an `NSValue` object containing
+ `MGLLineJoinMiter`. Otherwise, it is ignored.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *lineMiterLimit;
 
 /**
  Used to automatically convert round joins to miter joins for shallow angles.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSNumber` object containing the float `1.05`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSNumber` object containing the float `1.05`. Set this property to `nil` to
+ reset it to the default value.
  
- This property is only applied to the style if `lineJoin` is set to an `MGLStyleValue` object containing an `NSValue` object containing `MGLLineJoinRound`. Otherwise, it is ignored.
+ This property is only applied to the style if `lineJoin` is set to an
+ `MGLStyleValue` object containing an `NSValue` object containing
+ `MGLLineJoinRound`. Otherwise, it is ignored.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *lineRoundLimit;
 
@@ -110,10 +157,12 @@ MGL_EXPORT
 
 /**
  Blur applied to the line, in points.
-
+ 
  This property is measured in points.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSNumber` object containing the float `0`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSNumber` object containing the float `0`. Set this property to `nil` to reset
+ it to the default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *lineBlur;
 
@@ -121,93 +170,199 @@ MGL_EXPORT
 /**
  The color with which the line will be drawn.
  
- The default value of this property is an `MGLStyleValue` object containing `UIColor.blackColor`. Set this property to `nil` to reset it to the default value.
-
- This property is only applied to the style if `linePattern` is set to `nil`. Otherwise, it is ignored.
+ The default value of this property is an `MGLStyleValue` object containing
+ `UIColor.blackColor`. Set this property to `nil` to reset it to the default
+ value.
+ 
+ This property is only applied to the style if `linePattern` is set to `nil`.
+ Otherwise, it is ignored.
  */
-@property (nonatomic, null_resettable) MGLStyleValue<MGLColor *> *lineColor;
+@property (nonatomic, null_resettable) MGLStyleValue<UIColor *> *lineColor;
 #else
 /**
  The color with which the line will be drawn.
  
- The default value of this property is an `MGLStyleValue` object containing `NSColor.blackColor`. Set this property to `nil` to reset it to the default value.
-
- This property is only applied to the style if `linePattern` is set to `nil`. Otherwise, it is ignored.
+ The default value of this property is an `MGLStyleValue` object containing
+ `NSColor.blackColor`. Set this property to `nil` to reset it to the default
+ value.
+ 
+ This property is only applied to the style if `linePattern` is set to `nil`.
+ Otherwise, it is ignored.
  */
-@property (nonatomic, null_resettable) MGLStyleValue<MGLColor *> *lineColor;
+@property (nonatomic, null_resettable) MGLStyleValue<NSColor *> *lineColor;
 #endif
 
 /**
- Specifies the lengths of the alternating dashes and gaps that form the dash pattern. The lengths are later scaled by the line width. To convert a dash length to points, multiply the length by the current line width.
-
+ Specifies the lengths of the alternating dashes and gaps that form the dash
+ pattern. The lengths are later scaled by the line width. To convert a dash
+ length to points, multiply the length by the current line width.
+ 
  This property is measured in line widths.
-
- This property is only applied to the style if `linePattern` is set to `nil`. Otherwise, it is ignored.
  
- This attribute corresponds to the <a href="https://www.mapbox.com/mapbox-gl-style-spec/#paint-line-dasharray"><code>line-dasharray</code></a> paint property in the Mapbox Style Specification.
+ This property is only applied to the style if `linePattern` is set to `nil`.
+ Otherwise, it is ignored.
+ 
+ This attribute corresponds to the <a
+ href="https://www.mapbox.com/mapbox-gl-style-spec/#paint-line-dasharray"><code>line-dasharray</code></a>
+ layout property in the Mapbox Style Specification.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSArray<NSNumber *> *> *lineDashPattern;
 
-
 @property (nonatomic, null_resettable) MGLStyleValue<NSArray<NSNumber *> *> *lineDasharray __attribute__((unavailable("Use lineDashPattern instead.")));
 
 /**
- Draws a line casing outside of a line's actual path. Value indicates the width of the inner gap.
-
+ Draws a line casing outside of a line's actual path. Value indicates the width
+ of the inner gap.
+ 
  This property is measured in points.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSNumber` object containing the float `0`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSNumber` object containing the float `0`. Set this property to `nil` to reset
+ it to the default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *lineGapWidth;
 
 /**
- The line's offset. For linear features, a positive value offsets the line to the right, relative to the direction of the line, and a negative value to the left. For polygon features, a positive value results in an inset, and a negative value results in an outset.
-
+ The line's offset. For linear features, a positive value offsets the line to
+ the right, relative to the direction of the line, and a negative value to the
+ left. For polygon features, a positive value results in an inset, and a
+ negative value results in an outset.
+ 
  This property is measured in points.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSNumber` object containing the float `0`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSNumber` object containing the float `0`. Set this property to `nil` to reset
+ it to the default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *lineOffset;
 
 /**
  The opacity at which the line will be drawn.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSNumber` object containing the float `1`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSNumber` object containing the float `1`. Set this property to `nil` to reset
+ it to the default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *lineOpacity;
 
 /**
- Name of image in style images to use for drawing image lines. For seamless patterns, image width must be a factor of two (2, 4, 8, ..., 512).
+ Name of image in style images to use for drawing image lines. For seamless
+ patterns, image width must be a factor of two (2, 4, 8, ..., 512).
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSString *> *linePattern;
 
+#if TARGET_OS_IPHONE
 /**
  The geometry's offset.
-
+ 
+ This property is measured in points.
+ 
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing a `CGVector` struct set to 0 points rightward and 0
+ points downward. Set this property to `nil` to reset it to the default value.
+ 
+ This attribute corresponds to the <a
+ href="https://www.mapbox.com/mapbox-gl-style-spec/#paint-line-translate"><code>line-translate</code></a>
+ layout property in the Mapbox Style Specification.
+ */
+@property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineTranslation;
+#else
+/**
+ The geometry's offset.
+ 
  This property is measured in points.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSValue` object containing a `CGVector` struct set to 0 points from the left and 0 points from the top. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing a `CGVector` struct set to 0 points rightward and 0
+ points upward. Set this property to `nil` to reset it to the default value.
+ 
+ This attribute corresponds to the <a
+ href="https://www.mapbox.com/mapbox-gl-style-spec/#paint-line-translate"><code>line-translate</code></a>
+ layout property in the Mapbox Style Specification.
  */
-@property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineTranslate;
+@property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineTranslation;
+#endif
+
+@property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineTranslate __attribute__((unavailable("Use lineTranslation instead.")));
 
 /**
  Controls the translation reference point.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSValue` object containing `MGLLineTranslateAnchorMap`. Set this property to `nil` to reset it to the default value.
-
- This property is only applied to the style if `lineTranslate` is non-`nil`. Otherwise, it is ignored.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing `MGLLineTranslationAnchorMap`. Set this property to
+ `nil` to reset it to the default value.
+ 
+ This property is only applied to the style if `lineTranslation` is non-`nil`.
+ Otherwise, it is ignored.
+ 
+ This attribute corresponds to the <a
+ href="https://www.mapbox.com/mapbox-gl-style-spec/#paint-line-translate-anchor"><code>line-translate-anchor</code></a>
+ layout property in the Mapbox Style Specification.
  */
-@property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineTranslateAnchor;
+@property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineTranslationAnchor;
+
+@property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineTranslateAnchor __attribute__((unavailable("Use lineTranslationAnchor instead.")));
 
 /**
  Stroke thickness.
-
+ 
  This property is measured in points.
  
- The default value of this property is an `MGLStyleValue` object containing an `NSNumber` object containing the float `1`. Set this property to `nil` to reset it to the default value.
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSNumber` object containing the float `1`. Set this property to `nil` to reset
+ it to the default value.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *lineWidth;
 
 @end
 
+/**
+ Methods for wrapping an enumeration value for a style layer attribute in an
+ `MGLLineStyleLayer` object and unwrapping its raw value.
+ */
+@interface NSValue (MGLLineStyleLayerAdditions)
+
+#pragma mark Working with Line Style Layer Attribute Values
+
+/**
+ Creates a new value object containing the given `MGLLineCap` enumeration.
+
+ @param lineCap The value for the new object.
+ @return A new value object that contains the enumeration value.
+ */
++ (instancetype)valueWithMGLLineCap:(MGLLineCap)lineCap;
+
+/**
+ The `MGLLineCap` enumeration representation of the value.
+ */
+@property (readonly) MGLLineCap MGLLineCapValue;
+
+/**
+ Creates a new value object containing the given `MGLLineJoin` enumeration.
+
+ @param lineJoin The value for the new object.
+ @return A new value object that contains the enumeration value.
+ */
++ (instancetype)valueWithMGLLineJoin:(MGLLineJoin)lineJoin;
+
+/**
+ The `MGLLineJoin` enumeration representation of the value.
+ */
+@property (readonly) MGLLineJoin MGLLineJoinValue;
+
+/**
+ Creates a new value object containing the given `MGLLineTranslationAnchor` enumeration.
+
+ @param lineTranslationAnchor The value for the new object.
+ @return A new value object that contains the enumeration value.
+ */
++ (instancetype)valueWithMGLLineTranslationAnchor:(MGLLineTranslationAnchor)lineTranslationAnchor;
+
+/**
+ The `MGLLineTranslationAnchor` enumeration representation of the value.
+ */
+@property (readonly) MGLLineTranslationAnchor MGLLineTranslationAnchorValue;
+
+@end
+
 NS_ASSUME_NONNULL_END