diff options
Diffstat (limited to 'platform/ios/docs/guides')
| -rw-r--r-- | platform/ios/docs/guides/For Style Authors.md | 123 | ||||
| -rw-r--r-- | platform/ios/docs/guides/Using Style Functions at Runtime.md | 84 |
2 files changed, 119 insertions, 88 deletions
diff --git a/platform/ios/docs/guides/For Style Authors.md b/platform/ios/docs/guides/For Style Authors.md index 00dba95419..51cd87a766 100644 --- a/platform/ios/docs/guides/For Style Authors.md +++ b/platform/ios/docs/guides/For Style Authors.md @@ -270,12 +270,16 @@ In style JSON | In Objective-C | In Swift ## Setting attribute values Each property representing a layout or paint attribute is set to an -`MGLStyleValue` object, which is either an `MGLConstantStyleValue` object (for -constant values) or an `MGLStyleFunction` object (for style functions). The -style value object is a container for the raw value or function parameters that -you want the attribute to be set to. +`NSExpression` object. `NSExpression` objects play the same role as +[expressions in the Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions), +but you create the former using a very different syntax. `NSExpression`’s format +string syntax is reminiscent of a spreadsheet formula or an expression in a +database query. See the +“[Predicates and Expressions](Predicates and Expressions.md)” guide for an +overview of the expression support in this SDK. This SDK no longer supports +style functions; use expressions instead. -### Constant style values +### Constant values in expressions In contrast to the JSON type that the style specification defines for each layout or paint property, the style value object often contains a more specific @@ -286,10 +290,10 @@ or set. In style JSON | In Objective-C | In Swift --------------|-----------------------|--------- Color | `UIColor` | `UIColor` -Enum | `NSValue` (see `NSValue(MGLAdditions)`) | `NSValue` (see `NSValue(MGLAdditions)`) +Enum | `NSString` | `String` String | `NSString` | `String` -Boolean | `NSNumber.boolValue` | `Bool` -Number | `NSNumber.floatValue` | `Float` +Boolean | `NSNumber.boolValue` | `NSNumber.boolValue` +Number | `NSNumber.floatValue` | `NSNumber.floatValue` Array (`-dasharray`) | `NSArray<NSNumber>` | `[Float]` Array (`-font`) | `NSArray<NSString>` | `[String]` Array (`-offset`, `-translate`) | `NSValue.CGVectorValue` | `NSValue.cgVectorValue` @@ -301,38 +305,73 @@ in Swift are specified in counterclockwise order, in contrast to the clockwise order defined by the style specification. -### Style functions - -A _style function_ allows you to vary the value of a layout or paint attribute -based on the zoom level, data provided by content sources, or both. For more -information about style functions, see “[Using Style Functions at Runtime](using-style-functions-at-runtime.html)”. - -Each kind of style function is represented by a distinct class, but you -typically create style functions as you create any other style value, using -class methods on `MGLStyleValue`: - -In style specification | SDK class | SDK factory method ----------------------------|-----------------------------|------------------- -zoom function | `MGLCameraStyleFunction` | `+[MGLStyleValue valueWithInterpolationMode:cameraStops:options:]` -property function | `MGLSourceStyleFunction` | `+[MGLStyleValue valueWithInterpolationMode:sourceStops:attributeName:options:]` -zoom-and-property function | `MGLCompositeStyleFunction` | `+[MGLStyleValue valueWithInterpolationMode:compositeStops:attributeName:options:]` - -The documentation for each individual style layer property indicates the kinds -of style functions that are enabled for that property. - -When you create a style function, you specify an _interpolation mode_ and a -series of _stops_. Each stop determines the effective value displayed at a -particular zoom level (for camera functions) or the effective value on features -with a particular attribute value in the content source (for source functions). -The interpolation mode tells the SDK how to calculate the effective value -between any two stops: - -In style specification | In the SDK ------------------------------|----------- -`exponential` | `MGLInterpolationModeExponential` -`interval` | `MGLInterpolationModeInterval` -`categorical` | `MGLInterpolationModeCategorical` -`identity` | `MGLInterpolationModeIdentity` +### Expression operators + +In style specification | Method, function, or predicate type | Format string syntax +-----------------------|-------------------------------------|--------------------- +`array` | | +`boolean` | | +`literal` | `+[NSExpression expressionForConstantValue:]` | `%@` representing `NSArray` or `NSDictionary` +`number` | | +`string` | | +`to-boolean` | `boolValue` | +`to-color` | | +`to-number` | `mgl_numberWithFallbackValues:` | +`to-string` | `stringValue` | +`typeof` | | +`geometry-type` | | +`id` | | +`properties` | | +`at` | | +`get` | `+[NSExpression expressionForKeyPath:]` | Key path +`has` | | +`length` | `count:` | `count({1, 2, 2, 3, 4, 7, 9})` +`!` | `NSNotPredicateType` | `NOT (p0 OR … OR pn)` +`!=` | `NSNotEqualToPredicateOperatorType` | `key != value` +`<` | `NSLessThanPredicateOperatorType` | `key < value` +`<=` | `NSLessThanOrEqualToPredicateOperatorType` | `key <= value` +`==` | `NSEqualToPredicateOperatorType` | `key == value` +`>` | `NSGreaterThanPredicateOperatorType` | `key > value` +`>=` | `NSGreaterThanOrEqualToPredicateOperatorType` | `key >= value` +`all` | `NSAndPredicateType` | `p0 AND … AND pn` +`any` | `NSOrPredicateType` | `p0 OR … OR pn` +`case` | `+[NSExpression expressionForConditional:trueExpression:falseExpression:]` | `TERNARY(condition, trueExpression, falseExpression)` +`coalesce` | | +`match` | | +`interpolate` | `mgl_interpolateWithCurveType:parameters:stops:` | +`step` | `mgl_stepWithMinimum:stops:` | +`let` | `mgl_expressionWithContext:` | +`var` | `+[NSExpression expressionForVariable:]` | `$variable` +`concat` | `stringByAppendingString:` | +`downcase` | `lowercase:` | `lowercase('DOWNTOWN')` +`upcase` | `uppercase:` | `uppercase('Elysian Fields')` + +`rgb` | `+[UIColor colorWithRed:green:blue:alpha:]` | +`rgba` | `+[UIColor colorWithRed:green:blue:alpha:]` | +`to-rgba` | | +`-` | `from:subtract:` | `2 - 1` +`*` | `multiply:by:` | `1 * 2` +`/` | `divide:by:` | `1 / 2` +`%` | `modulus:by:` | +`^` | `raise:toPower:` | `2 ** 2` +`+` | `add:to:` | `1 + 2` +`acos` | | +`asin` | | +`atan` | | +`cos` | | +`e` | | `%@` representing `NSNumber` containing `M_E` +`ln` | `ln:` | `ln(2)` +`ln2` | | `%@` representing `NSNumber` containing `M_LN2` +`log10` | `log:` | `log(1)` +`log2` | | +`max` | `max:` | `max({1, 2, 2, 3, 4, 7, 9})` +`min` | `min:` | `min({1, 2, 2, 3, 4, 7, 9})` +`pi` | | `%@` representing `NSNumber` containing `M_PI` +`sin` | | +`sqrt` | `sqrt:` | `sqrt(2)` +`tan` | | +`zoom` | | `$zoom` +`heatmap-density` | | `$heatmapDensity` ## Filtering sources @@ -357,5 +396,5 @@ In style JSON | In the format string `["any", f0, …, fn]` | `p0 OR … OR pn` `["none", f0, …, fn]` | `NOT (p0 OR … OR pn)` -See the `MGLVectorStyleLayer.predicate` documentation for a full description of -the supported operators and operand types. +See the “[Predicates and Expressions](Predicates and Expressions.md)” guide for +a full description of the supported operators and operand types. diff --git a/platform/ios/docs/guides/Using Style Functions at Runtime.md b/platform/ios/docs/guides/Using Style Functions at Runtime.md index c1fcaa00e9..0b4e842e0e 100644 --- a/platform/ios/docs/guides/Using Style Functions at Runtime.md +++ b/platform/ios/docs/guides/Using Style Functions at Runtime.md @@ -27,15 +27,15 @@ The documentation for each individual style layer property notes which style fun ## Stops -Stops are key-value pairs that that determine a style value. With a `MGLCameraSourceFunction` stop, you can use a dictionary with a zoom level for a key and a `MGLStyleValue` for the value. For example, you can use a stops dictionary with zoom levels 0, 10, and 20 as keys, and yellow, orange, and red as the values. A `MGLSourceStyleFunction` uses the relevant attribute value as the key. +Stops are dictionary keys that are associated with layer attribute values. With feature attribute values as stops, you can use a dictionary with a zoom level for a key and an expression or constant value for the value. For example, you can use a stop dictionary with the zoom levels 0, 10, and 20 as keys and the colors yellow, orange, and red as the values. Alternatively, attribute values can be the keys. ```swift -let stops = [ - 0: MGLStyleValue<UIColor>(rawValue: .yellow), - 2.5: MGLStyleValue(rawValue: .orange), - 5: MGLStyleValue(rawValue: .red), - 7.5: MGLStyleValue(rawValue: .blue), - 10: MGLStyleValue(rawValue: .white), +let stops: [Float: UIColor] = [ + 0: .yellow, + 2.5: .orange, + 5: .red, + 7.5: .blue, + 10: .white, ] ``` @@ -57,20 +57,18 @@ let symbolLayer = MGLSymbolStyleLayer(identifier: "place-city-sm", source: symbo let source = MGLShapeSource(identifier: "earthquakes", url: url, options: nil) mapView.style?.addSource(source) -let stops = [ - 0: MGLStyleValue<UIColor>(rawValue: .yellow), - 2.5: MGLStyleValue(rawValue: .orange), - 5: MGLStyleValue(rawValue: .red), - 7.5: MGLStyleValue(rawValue: .blue), - 10: MGLStyleValue(rawValue: .white), +let stops: [Float: UIColor] = [ + 0: .yellow, + 2.5: .orange, + 5: .red, + 7.5: .blue, + 10: .white, ] let layer = MGLCircleStyleLayer(identifier: "circles", source: source) -layer.circleColor = MGLStyleValue(interpolationMode: .exponential, - sourceStops: stops, - attributeName: "mag", - options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .green)]) -layer.circleRadius = MGLStyleValue(rawValue: 10) +layer.circleColor = NSExpression(format: "FUNCTION(mag, 'mgl_interpolateWithCurveType:parameters:stops:', 'linear', nil, %@)", + stops) +layer.circleRadius = NSExpression(forConstantValue: 10) mapView.style?.insertLayer(layer, below: symbolLayer) ``` @@ -89,14 +87,13 @@ The example below increases a layer’s `circleRadius` exponentially based on a ```swift let stops = [ - 12: MGLStyleValue<NSNumber>(rawValue: 0.5), - 14: MGLStyleValue(rawValue: 2), - 18: MGLStyleValue(rawValue: 18), + 12: 0.5, + 14: 2, + 18: 18, ] -layer.circleRadius = MGLStyleValue(interpolationMode: .exponential, - cameraStops: stops, - options: [.interpolationBase: 1.5]) +layer.circleRadius = NSExpression(format: "FUNCTION($zoomLevel, 'mgl_interpolateWithCurveType:parameters:stops:', 'exponential', 1.5, %@)", + stops) ``` ### Interval @@ -106,18 +103,16 @@ layer.circleRadius = MGLStyleValue(interpolationMode: .exponential, When we use the stops dictionary given above with an interval interpolation mode, we create ranges where earthquakes with a magnitude of 0 to just less than 2.5 would be yellow, 2.5 to just less than 5 would be orange, and so on. ```swift -let stops = [ - 0: MGLStyleValue<UIColor>(rawValue: .yellow), - 2.5: MGLStyleValue(rawValue: .orange), - 5: MGLStyleValue(rawValue: .red), - 7.5: MGLStyleValue(rawValue: .blue), - 10: MGLStyleValue(rawValue: .white), +let stops: [Float: UIColor] = [ + 0: .yellow, + 2.5: .orange, + 5: .red, + 7.5: .blue, + 10: .white, ] -layer.circleColor = MGLStyleValue(interpolationMode: .interval, - sourceStops: stops, - attributeName: "mag", - options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .green)]) +layer.circleColor = NSExpression(format: "FUNCTION(mag, 'mgl_stepWithMinimum:stops:', %@, %@)", + UIColor.green, stops) ```  @@ -129,16 +124,16 @@ At each stop, `MGLInterpolationModeCategorical` produces an output value equal t There are three main types of events in the dataset: earthquakes, explosions, and quarry blasts. In this case, the color of the circle layer will be determined by the type of event, with a default value of blue to catch any events that do not fall into any of those categories. ```swift -let categoricalStops = [ - "earthquake": MGLStyleValue<UIColor>(rawValue: .orange), - "explosion": MGLStyleValue(rawValue: .red), - "quarry blast": MGLStyleValue(rawValue: .yellow), +let colors: [String: UIColor] = [ + "earthquake": .orange, + "explosion": .red, + "quarry blast": .yellow, ] +let defaultColor = UIColor.blue -layer.circleColor = MGLStyleValue(interpolationMode: .categorical, - sourceStops: categoricalStops, - attributeName: "type", - options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .blue)]) +layer.circleColor = NSExpression( + format: "TERNARY(FUNCTION(%@, 'valueForKeyPath:', type) != nil, FUNCTION(%@, 'valueForKeyPath:', type), %@)", + colors, colors, defaultColor) ```   @@ -148,10 +143,7 @@ layer.circleColor = MGLStyleValue(interpolationMode: .categorical, `MGLInterpolationModeIdentity` uses the attribute’s value as the style value. For example, you can set the `circleRadius` to the earthquake’s magnitude. Since the attribute value itself will be used as the style value, `sourceStops` should be set to `nil`. ```swift -layer.circleRadius = MGLStyleValue(interpolationMode: .identity, - sourceStops: nil, - attributeName: "mag", - options: [.defaultValue: MGLStyleValue<NSNumber>(rawValue: 0)]) +layer.circleRadius = NSExpression(forKeyPath: "mag") ```  |