diff options
Diffstat (limited to 'platform/darwin/docs')
| -rw-r--r-- | platform/darwin/docs/guides/For Style Authors.md.ejs | 446 | ||||
| -rw-r--r-- | platform/darwin/docs/guides/Migrating to Expressions.md.ejs | 212 | ||||
| -rw-r--r-- | platform/darwin/docs/guides/Predicates and Expressions.md | 950 | ||||
| -rw-r--r-- | platform/darwin/docs/guides/Tile URL Templates.md.ejs | 109 | ||||
| -rw-r--r-- | platform/darwin/docs/guides/Working with GeoJSON Data.md | 101 | ||||
| -rw-r--r-- | platform/darwin/docs/img/data-driven-styling/cast.png | bin | 49974 -> 0 bytes | |||
| -rw-r--r-- | platform/darwin/docs/img/data-driven-styling/exponential-function-1.png | bin | 34835 -> 0 bytes | |||
| -rw-r--r-- | platform/darwin/docs/img/data-driven-styling/exponential-function.png | bin | 34933 -> 0 bytes | |||
| -rw-r--r-- | platform/darwin/docs/img/data-driven-styling/identity.png | bin | 70278 -> 0 bytes | |||
| -rw-r--r-- | platform/darwin/docs/img/data-driven-styling/multiply.png | bin | 50375 -> 0 bytes | |||
| m--------- | platform/darwin/docs/theme | 0 |
11 files changed, 0 insertions, 1818 deletions
diff --git a/platform/darwin/docs/guides/For Style Authors.md.ejs b/platform/darwin/docs/guides/For Style Authors.md.ejs deleted file mode 100644 index 8df541d0f7..0000000000 --- a/platform/darwin/docs/guides/For Style Authors.md.ejs +++ /dev/null @@ -1,446 +0,0 @@ -<% - const os = locals.os; - const iOS = os === 'iOS'; - const macOS = os === 'macOS'; - const cocoaPrefix = iOS ? 'UI' : 'NS'; - const layers = locals.layers; - const renamedProperties = locals.renamedProperties; --%> -<!-- - This file is generated. - Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`. ---> -# Information for Style Authors - -A _style_ defines a map view’s content and appearance. If you’ve authored a -style using -[Mapbox Studio’s Styles editor](https://www.mapbox.com/studio/styles/) or as -JSON in a text editor, you can use that style in this SDK and manipulate it -afterwards in code. This document provides information you can use to ensure a -seamless transition from Mapbox Studio to your application. - -<% if (iOS) { -%> -## Designing for iOS -<% } else { -%> -## Designing for macOS -<% } -%> - -When designing your style, consider the context in which your application shows -the style. There are a number of considerations specific to <%- os %> that may -not be obvious when designing your style in Mapbox Studio on the Web. A map view -is essentially a graphical user interface element, so many of same issues in -user interface design also apply when designing a map style. - -### Color - -Ensure sufficient contrast in your application’s user interface when your map -style is present. Standard user interface elements such as toolbars, sidebars, -and sheets often overlap the map view with a translucent, blurred background, so -make sure the contents of these elements remain legible with the map view -underneath. -<% if (iOS) { -%> -The user location annotation view, the attribution button, any buttons in -callout views, and any items in the navigation bar are influenced by your -application’s tint color, so choose a tint color that contrasts well with your -map style. -<% } -%> -If you intend your style to be used in the dark, consider the impact that Night -Shift may have on your style’s colors. - -### Typography and graphics - -<% if (iOS) { -%> -Choose font and icon sizes appropriate to iOS devices. iPhones and iPads have -smaller screens than the typical browser window in which you would use Mapbox -Studio, especially when multitasking is enabled. Your user’s viewing distance -may be shorter than on a desktop computer. Some of your users may use the Larger -Dynamic Type and Accessibility Text features to increase the size of all text on -the device. You can use the -[runtime styling API](#manipulating-the-style-at-runtime) to adjust your style’s - font and icon sizes accordingly. -<% } -%> - -Design sprite images and choose font weights that look crisp on both -standard-resolution displays and Retina displays. This SDK supports the same -resolutions as <%- os %>. -<% if (iOS) { -%> -Standard-resolution displays are limited to older devices that your application -may or may not support, depending on its minimum deployment target. -<% } else { -%> -Standard-resolution displays are often found on external monitors. Even with -built-in screens, some of your users may use the Larger Text option in Display -Preferences, which is essentially standard resolution, to make text easier to -read. -<% } -%> - -Icon and text labels should be legible regardless of the map’s orientation. -<% if (iOS) { -%> -By default, this SDK makes it easy for your users to rotate or tilt the map -using multitouch gestures. -<% } else { -%> -By default, this SDK makes it easy for your users to rotate or tilt the map -using multitouch trackpad gestures or keyboard shortcuts. -<% } -%> -If you do not intend your design to accommodate rotation and tilting, disable -these gestures using the `MGLMapView.rotateEnabled` and -`MGLMapView.pitchEnabled` properties, respectively, or the corresponding -inspectables in Interface Builder. - -### Interactivity - -Pay attention to whether elements of your style appear to be interactive. -<% if (iOS) { -%> -A text label may look like a tappable button merely due to matching your -application’s tint color or the default blue tint color. -<% } else { -%> -An icon with a shadow or shading effect may appear to be clickable. -<% } -%> -You can make an icon or text label interactive by installing a gesture -recognizer and performing feature querying (e.g., -`-[MGLMapView visibleFeaturesAtPoint:]`) to get details about the selected -feature. -<% if (macOS) { -%> -You can install cursor or tooltip tracking rectangles to indicate interactive -features as an alternative to prominent hover effects. -<% } -%> - -<% if (iOS) { -%> -Make sure your users can easily distinguish any interactive elements from the -surrounding map, such as pins, the user location annotation view, or a route -line. Avoid relying on hover effects to indicate interactive elements. Leave -enough room between interactive elements to accommodate imprecise tapping -gestures. -<% } else { -%> -Make sure your users can easily distinguish any interactive elements from the -surrounding map, such as pins or a route line. If your application supports -printing, consider using the -[runtime styling API](#manipulating-the-style-at-runtime) to optimize your style -for ink economy before printing the map view. -<% } -%> - -<% if (iOS) { -%> -For more information about user interface design, consult Apple’s -[_iOS Human Interface Guidelines_](https://developer.apple.com/ios/human-interface-guidelines/). -To learn more about designing maps for mobile devices, see [Nathaniel Slaughter's blog post](https://www.mapbox.com/blog/designing-maps-for-mobile-devices/) on -the subject. -<% } else { -%> -For more information about user interface design, consult Apple’s -[_macOS Human Interface Guidelines_](https://developer.apple.com/library/content/documentation/UserExperience/Conceptual/OSXHIGuidelines/). -<% } -%> - -## Applying your style - -You set an `MGLMapView` object’s style either in code, by setting the -`MGLMapView.styleURL` property, or in Interface Builder, by setting the “Style -URL” inspectable. The URL must point to a local or remote style JSON file. The -style JSON file format is defined by the -[Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-style-spec/). This -SDK supports the functionality defined by version 8 of the specification unless -otherwise noted in the -[style specification documentation](https://www.mapbox.com/mapbox-gl-style-spec/). - -## Manipulating the style at runtime - -The _runtime styling API_ enables you to modify every aspect of a style -dynamically as a user interacts with your application. The style itself is -represented at runtime by an `MGLStyle` object, which provides access to various -`MGLSource` and `MGLStyleLayer` objects that represent content sources and style -layers, respectively. -<% if (iOS) { -%> -For more information about the capabilities exposed by the runtime styling API, -see “[Runtime Styling](https://www.mapbox.com/ios-sdk/maps/overview/runtime-styling/)”. -<% } -%> - -The names of runtime styling classes and properties on <%- os %> are generally -consistent with the style specification and Mapbox Studio’s Styles editor. Any -exceptions are listed in this document. - -To avoid conflicts with Objective-C keywords or Cocoa terminology, this SDK uses -the following terms for concepts defined in the style specification: - -In the style specification | In the SDK ----------------------------|--------- -bounds | coordinate bounds -filter | predicate -function type | interpolation mode -id | identifier -image | style image -layer | style layer -property | attribute -SDF icon | template image -source | content source - -## Specifying the map’s content - -Each source defined by a style JSON file is represented at runtime by a content -source object that you can use to initialize new style layers. The content -source object is a member of one of the following subclasses of `MGLSource`: - -In style JSON | In the SDK ---------------|----------- -`vector` | `MGLVectorTileSource` -`raster` | `MGLRasterTileSource` -`raster-dem` | `MGLRasterDEMSource` -`geojson` | `MGLShapeSource` -`image` | `MGLImageSource` - -`canvas` and `video` sources are not supported. - -### Tile sources - -Raster and vector tile sources may be defined in TileJSON configuration files. -This SDK supports the properties defined in the style specification, which are a -subset of the keys defined in version 2.1.0 of the -[TileJSON](https://github.com/mapbox/tilejson-spec/tree/master/2.1.0) -specification. As an alternative to authoring a custom TileJSON file, you may -supply various tile source options when creating a raster or vector tile source. -These options are detailed in the `MGLTileSourceOption` documentation: - -In style JSON | In TileJSON | In the SDK ---------------|---------------|----------- -`url` | — | `configurationURL` parameter in `-[MGLTileSource initWithIdentifier:configurationURL:]` -`tiles` | `tiles` | `tileURLTemplates` parameter in `-[MGLTileSource initWithIdentifier:tileURLTemplates:options:]` -`minzoom` | `minzoom` | `MGLTileSourceOptionMinimumZoomLevel` -`maxzoom` | `maxzoom` | `MGLTileSourceOptionMaximumZoomLevel` -`bounds` | `bounds` | `MGLTileSourceOptionCoordinateBounds` -`tileSize` | — | `MGLTileSourceOptionTileSize` -`attribution` | `attribution` | `MGLTileSourceOptionAttributionHTMLString` (but consider specifying `MGLTileSourceOptionAttributionInfos` instead for improved security) -`scheme` | `scheme` | `MGLTileSourceOptionTileCoordinateSystem` -`encoding` | – | `MGLTileSourceOptionDEMEncoding` - -### Shape sources - -Shape sources also accept various options. These options are detailed in the -`MGLShapeSourceOption` documentation: - -In style JSON | In the SDK ------------------|----------- -`data` | `url` parameter in `-[MGLShapeSource initWithIdentifier:URL:options:]` -`maxzoom` | `MGLShapeSourceOptionMaximumZoomLevel` -`buffer` | `MGLShapeSourceOptionBuffer` -`tolerance` | `MGLShapeSourceOptionSimplificationTolerance` -`cluster` | `MGLShapeSourceOptionClustered` -`clusterRadius` | `MGLShapeSourceOptionClusterRadius` -`clusterMaxZoom` | `MGLShapeSourceOptionMaximumZoomLevelForClustering` -`lineMetrics` | `MGLShapeSourceOptionLineDistanceMetrics` - -To create a shape source from local GeoJSON data, first -[convert the GeoJSON data into a shape](working-with-geojson-data.html#converting-geojson-data-into-shape-objects), -then use the `-[MGLShapeSource initWithIdentifier:shape:options:]` method. - -### Image sources - -Image sources accept a non-axis aligned quadrilateral as their geographic coordinates. -These coordinates, in `MGLCoordinateQuad`, are described in counterclockwise order, -in contrast to the clockwise order defined in the style specification. - -## Configuring the map content’s appearance - -Each layer defined by the style JSON file is represented at runtime by a style -layer object, which you can use to refine the map’s appearance. The style layer -object is a member of one of the following subclasses of `MGLStyleLayer`: - -In style JSON | In the SDK ---------------|----------- -<% for (const layer of layers) { -%> -`<%- layer.type %>` | `MGL<%- camelize(layer.type) %>StyleLayer` -<% } -%> - -You configure layout and paint attributes by setting properties on these style -layer objects. The property names generally correspond to the style JSON -properties, except for the use of camelCase instead of kebab-case. Properties -whose names differ from the style specification are listed below: -<% for (const type in renamedProperties) { -%> -<% if (renamedProperties.hasOwnProperty(type)) { -%> - -### <%- camelize(unhyphenate(type)) %> style layers - -In style JSON | In Objective-C | In Swift ---------------|----------------|--------- -<% for (const name in renamedProperties[type]) { -%> -<% if (renamedProperties[type].hasOwnProperty(name)) { -%> -`<%- originalPropertyName(renamedProperties[type][name]) %>` | `MGL<%- camelize(type) %>StyleLayer.<%- objCName(renamedProperties[type][name]) %>` | `MGL<%- camelize(type) %>StyleLayer.<%- objCGetter(renamedProperties[type][name]) %>` -<% } -%> -<% } -%> -<% } -%> -<% } -%> - -## Setting attribute values - -Each property representing a layout or paint attribute is set to an -`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.html)” guide for an -overview of the expression support in this SDK. This SDK no longer supports -style functions; use expressions instead. - -### 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 -Foundation or Cocoa type. General rules for attribute types are listed below. -Pay close attention to the SDK documentation for the attribute you want to get -or set. - -In style JSON | In Objective-C | In Swift ---------------|-----------------------|--------- -Color | `<%- cocoaPrefix %>Color` | `<%- cocoaPrefix %>Color` -Enum | `NSString` | `String` -String | `NSString` | `String` -Boolean | `NSNumber.boolValue` | `NSNumber.boolValue` -Number | `NSNumber.floatValue` | `NSNumber.floatValue` -Array (`-dasharray`) | `NSArray<NSNumber>` | `[Float]` -Array (`-font`) | `NSArray<NSString>` | `[String]` -<% if (iOS) { -%> -Array (`-offset`, `-translate`) | `NSValue.CGVectorValue` | `NSValue.cgVectorValue` -Array (`-padding`) | `NSValue.UIEdgeInsetsValue` | `NSValue.uiEdgeInsetsValue` -<% } else { -%> -Array (`-offset`, `-translate`) | `NSValue` containing `CGVector` | `NSValue` containing `CGVector` -Array (`-padding`) | `NSValue.edgeInsetsValue` | `NSValue.edgeInsetsValue` -<% } -%> - -For padding attributes, note that the arguments to -<% if (iOS) { -%> -`UIEdgeInsetsMake()` in Objective-C and `UIEdgeInsets(top:left:bottom:right:)` -in Swift -<% } else { -%> -`NSEdgeInsetsMake()` in Objective-C and `EdgeInsets(top:left:bottom:right:)` in -Swift -<% } -%> -are specified in counterclockwise order, in contrast to the clockwise order -defined by the style specification. - -<% if (macOS) { -%> -Additionally, on macOS, a screen coordinate of (0, 0) is located at the -lower-left corner of the screen. Therefore, a positive `CGVector.dy` means an -offset or translation upward, while a negative `CGVector.dy` means an offset or -translation downward. This is the reverse of how `CGVector` is interpreted on -iOS. - -<% } -%> -### Expression operators - -Many expression operators defined in the style specification have corresponding -symbols to be used with the `+[NSExpression expressionWithFormat:]`, -`+[NSExpression expressionForFunction:arguments:]`, or -`+[NSExpression expressionForFunction:selectorName:arguments:]` method: - -In style specification | Method, function, or predicate type | Format string syntax ------------------------|-------------------------------------|--------------------- -`array` | | -`boolean` | | -`collator` | `NSComparisonPredicateOptions` | `'Québec' =[cd] 'QUEBEC'` -`literal` | `+[NSExpression expressionForConstantValue:]` | `%@` representing `NSArray` or `NSDictionary` -`number` | | -`string` | | -`to-boolean` | `boolValue` | -`to-color` | | `CAST(var, '<%- cocoaPrefix %>Color')` -`to-number` | `mgl_numberWithFallbackValues:` | `CAST(zipCode, 'NSNumber')` -`to-string` | `stringValue` | `CAST(ele, 'NSString')` -`typeof` | | -`geometry-type` | `NSExpression.geometryTypeVariableExpression` | `$geometryType` -`id` | `NSExpression.featureIdentifierVariableExpression` | `$featureIdentifier` -`properties` | `NSExpression.featureAttributesVariableExpression` | `$featureAttributes` -`at` | `objectFrom:withIndex:` | `array[n]` -`get` | `+[NSExpression expressionForKeyPath:]` | Key path -`has` | `mgl_does:have:` | `mgl_does:have:(self, 'key')` -`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:]` or `MGL_IF` or `+[NSExpression mgl_expressionForConditional:trueExpression:falseExpresssion:]` | `TERNARY(1 = 2, YES, NO)` or `MGL_IF(1 = 2, YES, 2 = 2, YES, NO)` -`coalesce` | `mgl_coalesce:` | `mgl_coalesce({x, y, z})` -`match` | `MGL_MATCH` or `+[NSExpression mgl_expressionForMatchingExpression:inDictionary:defaultExpression:]` | `MGL_MATCH(x, 0, 'zero match', 1, 'one match', 'two match', 'default')` -`interpolate` | `mgl_interpolate:withCurveType:parameters:stops:` or `+[NSExpression mgl_expressionForInterpolatingExpression:withCurveType:parameters:stops:]` | -`step` | `mgl_step:from:stops:` or `+[NSExpression mgl_expressionForSteppingExpression:fromExpression:stops:]` | -`let` | `mgl_expressionWithContext:` | `MGL_LET('ios', 11, 'macos', 10.13, $ios + $macos)` -`var` | `+[NSExpression expressionForVariable:]` | `$variable` -`concat` | `mgl_join:` or `-[NSExpression mgl_expressionByAppendingExpression:]` | `mgl_join({'Old', ' ', 'MacDonald'})` -`downcase` | `lowercase:` | `lowercase('DOWNTOWN')` -`upcase` | `uppercase:` | `uppercase('Elysian Fields')` -<% if (macOS) { -%> -`rgb` | `+[NSColor colorWithCalibratedRed:green:blue:alpha:]` | -`rgba` | `+[NSColor colorWithCalibratedRed:green:blue:alpha:]` | -<% } else { -%> -`rgb` | `+[UIColor colorWithRed:green:blue:alpha:]` | -`rgba` | `+[UIColor colorWithRed:green:blue:alpha:]` | -<% } -%> -`to-rgba` | | `CAST(noindex(var), 'NSArray')` -`-` | `from:subtract:` | `2 - 1` -`*` | `multiply:by:` | `1 * 2` -`/` | `divide:by:` | `1 / 2` -`%` | `modulus:by:` | -`^` | `raise:toPower:` | `2 ** 2` -`+` | `add:to:` | `1 + 2` -`abs` | `abs:` | `abs(-1)` -`acos` | `mgl_acos:` | `mgl_acos(1)` -`asin` | `mgl_asin:` | `mgl_asin(0)` -`atan` | `mgl_atan:` | `mgl_atan(20)` -`ceil` | `ceiling:` | `ceiling(0.99999)` -`cos` | `mgl_cos:` | `mgl_cos(0)` -`e` | | `%@` representing `NSNumber` containing `M_E` -`floor` | `floor:` | `floor(-0.99999)` -`ln` | `ln:` | `ln(2)` -`ln2` | | `%@` representing `NSNumber` containing `M_LN2` -`log10` | `log:` | `log(1)` -`log2` | `mgl_log2:` | `mgl_log2(1024)` -`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` -`round` | `mgl_round:` | `mgl_round(1.5)` -`sin` | `mgl_sin:` | `mgl_sin(0)` -`sqrt` | `sqrt:` | `sqrt(2)` -`tan` | `mgl_tan:` | `mgl_tan(0)` -`zoom` | `NSExpression.zoomLevelVariableExpression` | `$zoomLevel` -`heatmap-density` | `NSExpression.heatmapDensityVariableExpression` | `$heatmapDensity` -`line-progress` | `NSExpression.lineProgressVariableExpression` | `$lineProgress` -`format` | `+[NSExpression mgl_expressionForAttributedExpressions:]` or `mgl_attributed:` | `mgl_attributed({x, y, z})` - -For operators that have no corresponding `NSExpression` symbol, use the -`MGL_FUNCTION()` format string syntax. - -## Filtering sources - -You can filter a shape or vector tile source by setting the -`MGLVectorStyleLayer.predicate` property to an `NSPredicate` object. Below is a -table of style JSON operators and the corresponding operators used in the -predicate format string: - -In style JSON | In the format string ---------------------------|--------------------- -`["has", key]` | `key != nil` -`["!has", key]` | `key == nil` -`["==", key, value]` | `key == value` -`["!=", key, value]` | `key != value` -`[">", key, value]` | `key > value` -`[">=", key, value]` | `key >= value` -`["<", key, value]` | `key < value` -`["<=", key, value]` | `key <= value` -`["in", key, v0, …, vn]` | `key IN {v0, …, vn}` -`["!in", key, v0, …, vn]` | `NOT key IN {v0, …, vn}` -`["all", f0, …, fn]` | `p0 AND … AND pn` -`["any", f0, …, fn]` | `p0 OR … OR pn` -`["none", f0, …, fn]` | `NOT (p0 OR … OR pn)` - -## Specifying the text format - -The following format attributes are defined as `NSString` constans that you -can use to update the formatting of `MGLSymbolStyleLayer.text` property. - -In style JSON | In Objective-C | In Swift ---------------|-----------------------|--------- -`text-font` | `MGLFontNamesAttribute` | `.fontNamesAttribute` -`font-scale` | `MGLFontScaleAttribute` | `.fontScaleAttribute` -`text-color` | `MGLFontColorAttribute` | `.fontColorAttribute` - -See the “[Predicates and Expressions](predicates-and-expressions.html)” guide for -a full description of the supported operators and operand types. diff --git a/platform/darwin/docs/guides/Migrating to Expressions.md.ejs b/platform/darwin/docs/guides/Migrating to Expressions.md.ejs deleted file mode 100644 index 3ea5b33d73..0000000000 --- a/platform/darwin/docs/guides/Migrating to Expressions.md.ejs +++ /dev/null @@ -1,212 +0,0 @@ -<% - const os = locals.os; - const iOS = os === 'iOS'; - const macOS = os === 'macOS'; - const cocoaPrefix = iOS ? 'UI' : 'NS'; - const guide = 'MigratingToExpressions'; --%> -<!-- - This file is generated. - Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`. ---> - -# Migrating from Style Functions to Expressions - -[Runtime Styling](https://www.mapbox.com/ios-sdk/maps/overview/runtime-styling/) enables you to modify every aspect of the map’s appearance dynamically as a user interacts with your application. Developers can specify in advance how a layout or paint attribute will vary as the zoom level changes or how the appearance of individual features vary based on metadata provided by a content source. - -With Mapbox Maps SDK for <%- iOS ? 'iOS v4.0.0' : 'macOS v0.7.0' %>, style functions have been replaced with expressions. These provide even more tools for developers who want to style their maps dynamically. This guide outlines some tips for migrating from style functions to expressions, and offers an overview of some things that developers can do with expressions. - -An expression is represented at runtime by the `NSExpression` class. Expressions can be used to style paint and layout properties based on zoom level, data attributes, or a combination of the two. - -A constant expression can also be assigned to a style property. For example, the opacity of a fill style layer can be set to a constant value between 0 and 1. - -The documentation for each individual style layer property notes which non-constant expressions are enabled for that property. Style functions supported four interpolation modes: exponential, interval, categorical, and identity. - -This guide uses earthquake data from the [U.S. Geological Survey](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php). Under each interpolation mode, the style function implementation will be shown, followed by the current syntax. - -For more information about how to work with GeoJSON data in our <%- os %> SDK, please see our [working with GeoJSON data](working-with-geojson-data.html) guide. To learn more about supported expressions, see our ["Predicates and Expressions"](predicates-and-expressions.html) guide. The "Predicates and Expressions" guide also outlines Mapbox custom functions that can be used to dynamically style a map. - -## Stops -Stops are dictionary keys that are associated with layer attribute values. Constant values no longer need to be wrapped as style values when they are values in a stops dictionary. - - -Style function syntax: - -```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), -] -``` - -Current syntax: -<%- guideExample(guide, 'Stops', os) %> - - -## Interpolation mode - -Style functions supported four interpolation modes: exponential/linear, interval, categorical, and identity. For more information about supported custom expressions, please see the "Predicates and Expressions" guide. - -### Linear - -`+[NSExpression(MGLAdditions) mgl_expressionForInterpolatingExpression:withCurveType:parameters:stops:]` takes the interpolation type as a parameter. If you previously used the default interpolation base, use the curve type `MGLExpressionInterpolationMode.linear`. See the [`mgl_interpolate:withCurveType:parameters:stops:`](predicates-and-expressions.html#code-mgl_interpolate-withcurvetype-parameters-stops-code) documentation for more details. - -The stops dictionary below, shows colors that continuously shift from yellow to orange to red to blue to white based on the attribute value. - -Style function syntax: - -```swift -let url = URL(string: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson")! -let symbolSource = MGLSource(identifier: "source") -let symbolLayer = MGLSymbolStyleLayer(identifier: "place-city-sm", source: symbolSource) - -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 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) -mapView.style?.insertLayer(layer, below: symbolLayer) -``` - -Current syntax: - -<%- guideExample(guide, 'Linear', os) %> - -### Exponential - -If you previously used an interpolation base greater than `0` (other than `1`), you can use `MGLExpressionInterpolationMode.exponential` as the curve type for `+[NSExpression(MGLAdditions) mgl_expressionForInterpolatingExpression:withCurveType:parameters:stops:]` or `'exponential'` as the curve type for [`mgl_interpolate:withCurveType:parameters:stops:`](predicates-and-expressions.html#code-mgl_interpolate-withcurvetype-parameters-stops-code). The `parameters` argument takes that interpolation base. This interpolates between values exponentially, creating an accelerated ramp effect. - -Here’s a visualization from Mapbox Studio (see [Mapbox Studio and iOS](https://www.mapbox.com/ios-sdk/maps/overview/mapbox-studio/)) comparing interpolation base values of `1.5` and `0.5` based on zoom. In order to convert camera style functions, use `$zoomLevel` or `MGL_FUNCTION('zoomLevel')` as the attribute key. - -<img src="img/data-driven-styling/exponential-function.png" height=344/> -<img src="img/data-driven-styling/exponential-function-1.png" height=344/> - -The example below increases a layer’s `circleRadius` exponentially based on a map’s zoom level. The interpolation base is `1.5`. - -Style function syntax: - -```swift -let stops = [ - 12: MGLStyleValue<NSNumber>(rawValue: 0.5), - 14: MGLStyleValue(rawValue: 2), - 18: MGLStyleValue(rawValue: 18), -] - -layer.circleRadius = MGLStyleValue(interpolationMode: .exponential, - cameraStops: stops, - options: [.interpolationBase: 1.5]) -``` - -Current syntax: - -<%- guideExample(guide, 'Exponential', os) %> - -### Interval - -Steps, or intervals, create a range using the keys from the stops dictionary. The range is from the given key to just less than the next key. The attribute values that fall into that range are then styled using the layout or paint value assigned to that key. You can use the `+[NSExpression(MGLAdditions) mgl_expressionForSteppingExpression:fromExpression:stops:]` method or the custom function [`mgl_step:from:stops:`](predicates-and-expressions.html#code-mgl_step-from-stops-code) for cases where you previously used interval interpolation mode. The first parameter takes the feature attribute name and the second parameter (`from:`) optionally takes the default or fallback value for that function. The final parameter takes a stops dictionary as an argument. - -When we use the stops dictionary given above with an `'mgl_step:from:stops:'`, 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. - -Style function syntax: - -```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), -] - -layer.circleColor = MGLStyleValue(interpolationMode: .interval, - sourceStops: stops, - attributeName: "mag", - options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .green)]) -```` - -Current syntax: - -<%- guideExample(guide, 'Interval', os) %> - -### Categorical - -Categorical interpolation mode took a stops dictionary. If the value for a specified feature attribute name matched one in that stops dictionary, the style value for that attribute value would be used. Categorical style functions can now be replaced with `MGL_MATCH`. - -`MGL_MATCH` takes an initial condition, which in this case is an attribute key. This is followed by possible matches for that key and the value to assign to the layer property if there is a match. The final argument can be a default style value that is to be used if none of the specified values match. - -There are three main types of events in the USGS 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. - -Style function syntax: - -```swift -let categoricalStops = [ - "earthquake": MGLStyleValue<UIColor>(rawValue: .orange), - "explosion": MGLStyleValue(rawValue: .red), - "quarry blast": MGLStyleValue(rawValue: .yellow), -] - -layer.circleColor = MGLStyleValue(interpolationMode: .categorical, - sourceStops: categoricalStops, - attributeName: "type", - options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .blue)]) -``` - -Current syntax: -<%- guideExample(guide, 'Categorical', os) %> - -If your use case does not require a default value, you can either apply a predicate to your layer prior to styling it, or use the format string `"valueForKeyPath:"`. - -### Identity - -Identity interpolation mode used the attribute’s value as the style layer property value. In this example, you might set the `circleRadius` to the earthquake’s magnitude. In order to use a feature attribute value to style a layer property, set the property value to `[NSExpression expressionForKeyPath:]`, which take the feature attribute name as an argument. - -Style function syntax: - -```swift -layer.circleRadius = MGLStyleValue(interpolationMode: .identity, - sourceStops: nil, - attributeName: "mag", - options: [.defaultValue: MGLStyleValue<NSNumber>(rawValue: 0)]) -``` - -Current syntax: -<%- guideExample(guide, 'Identity', os) %> - - - -Some built-in functions can be applied to attribute values to style layer property values. To set the circle radius to three times the earthquake’s magnitude, create a `multiply:by:` function that takes the attribute value and the multiplier as arguments, or use a format string. - -<%- guideExample(guide, 'Multiply', os) %> - - - -You can also cast attribute values in order to use them. One example is to cast an integer as an `NSString` and use it as a text value. - -<%- guideExample(guide, 'Cast', os) %> - - - -### Constant Values - -For constant values that do not necessarily change based on camera or attribute values, use `[NSExpression expressionForConstantValue:]` (previously `[MGLStyleValue valueWithRawValue:]`). - -## Resources - -* [USGS Earthquake Feed](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) -* [For Style Authors](for-style-authors.html) -* [Predicates and Expressions](predicates-and-expressions.html) diff --git a/platform/darwin/docs/guides/Predicates and Expressions.md b/platform/darwin/docs/guides/Predicates and Expressions.md deleted file mode 100644 index b2e01b94db..0000000000 --- a/platform/darwin/docs/guides/Predicates and Expressions.md +++ /dev/null @@ -1,950 +0,0 @@ -# Predicates and expressions - -Style layers use predicates and expressions to determine what to display and how -to format it. _Predicates_ are represented by the same `NSPredicate` class that -filters results from Core Data or items in an `NSArray` in Objective-C. -Predicates are based on _expressions_, represented by the `NSExpression` class. -Somewhat unusually, style layers also use expressions on their own. - -This document discusses the specific subset of the predicate and expression -syntax supported by this SDK. For a more general introduction to predicates and -expressions, consult the -_[Predicate Programming Guide](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/Predicates/AdditionalChapters/Introduction.html)_ -in Apple developer documentation. For additional detail on how this SDK has -extended the `NSExpression` class, consult the [`NSExpression(MGLAdditions)`](./Categories/NSExpression(MGLAdditions).html) -section of this documentation. - -## Using predicates to filter vector data - -Most style layer classes display `MGLFeature` objects that you can show or hide -based on the feature’s attributes. Use the `MGLVectorStyleLayer.predicate` -property to include only the features in the source layer that satisfy a -condition that you define. - -### Operators - -The following comparison operators are supported: - -`NSPredicateOperatorType` | Format string syntax -----------------------------------------------|--------------------- -`NSEqualToPredicateOperatorType` | `key = value`<br />`key == value` -`NSGreaterThanOrEqualToPredicateOperatorType` | `key >= value`<br />`key => value` -`NSLessThanOrEqualToPredicateOperatorType` | `key <= value`<br />`key =< value` -`NSGreaterThanPredicateOperatorType` | `key > value` -`NSLessThanPredicateOperatorType` | `key < value` -`NSNotEqualToPredicateOperatorType` | `key != value`<br />`key <> value` -`NSBetweenPredicateOperatorType` | `key BETWEEN { 32, 212 }` - -To test whether a feature has or lacks a specific attribute, compare the -attribute to `NULL` or `NIL`. Predicates created using the -`+[NSPredicate predicateWithValue:]` method are also supported. String -operators and custom operators are not supported. - -The following compound operators are supported: - -`NSCompoundPredicateType` | Format string syntax ---------------------------|--------------------- -`NSAndPredicateType` | `predicate1 AND predicate2`<br />`predicate1 && predicate2` -`NSOrPredicateType` | `predicate1 OR predicate2`<br /><code>predicate1 || predicate2</code> -`NSNotPredicateType` | `NOT predicate`<br />`!predicate` - -The following aggregate operators are supported: - -`NSPredicateOperatorType` | Format string syntax -----------------------------------|--------------------- -`NSInPredicateOperatorType` | `key IN { 'iOS', 'macOS', 'tvOS', 'watchOS' }` -`NSContainsPredicateOperatorType` | `{ 'iOS', 'macOS', 'tvOS', 'watchOS' } CONTAINS key` - -The following comparison predicate options are supported for comparison and -aggregate operators that are used in the predicate: - -`NSComparisonPredicateOptions` | Format string syntax -----------------------------------------|--------------------- -`NSCaseInsensitivePredicateOption` | `'QUEBEC' =[c] 'Quebec'` -`NSDiacriticInsensitivePredicateOption` | `'Québec' =[d] 'Quebec'` - -Other comparison predicate options are unsupported, namely `l` -(for locale sensitivity) and `n` (for normalization). A comparison is -locale-sensitive as long as it is case- or diacritic-insensitive. - -### Operands - -Operands in predicates can be [variables](#variables), [key paths](#key-paths), -or almost anything else that can appear -[inside an expression](#using-expressions-to-configure-layout-and-paint-attributes). - -Automatic type casting is not performed. Therefore, a feature only matches a -predicate if its value for the attribute in question is of the same type as the -value specified in the predicate. Use the `CAST()` operator to convert a key -path or variable into a matching type: - -* To cast a value to a number, use `CAST(key, 'NSNumber')`. -* To cast a value to a string, use `CAST(key, 'NSString')`. -* To cast a value to a color, use `CAST(key, 'UIColor')` on iOS and `CAST(key, 'NSColor')` on macOS. -* To cast an `NSColor` or `UIColor` object to an array, use `CAST(noindex(color), 'NSArray')`. - -For details about the predicate format string syntax, consult the “Predicate -Format String Syntax” chapter of the -_[Predicate Programming Guide](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/Predicates/AdditionalChapters/Introduction.html)_ -in Apple developer documentation. - -## Using expressions to configure layout and paint attributes - -An expression can contain subexpressions of various types. Each of the supported -types of expressions is discussed below. - -### Constant values - -A constant value can be of any of the following types: - -In Objective-C | In Swift -----------------------|--------- -`NSColor` (macOS)<br>`UIColor` (iOS) | `NSColor` (macOS)<br>`UIColor` (iOS) -`NSString` | `String` -`NSString` | `String` -`NSNumber.boolValue` | `NSNumber.boolValue` -`NSNumber.doubleValue` | `NSNumber.doubleValue` -`NSArray<NSNumber>` | `[Float]` -`NSArray<NSString>` | `[String]` -`NSValue.CGVectorValue` (iOS)<br>`NSValue` containing `CGVector` (macOS) | `NSValue.cgVectorValue` (iOS)<br>`NSValue` containing `CGVector` (macOS) -`NSValue.UIEdgeInsetsValue` (iOS)<br>`NSValue.edgeInsetsValue` (macOS) | `NSValue.uiEdgeInsetsValue` (iOS)<br>`NSValue.edgeInsetsValue` (macOS) - -For literal floating-point values, use `-[NSNumber numberWithDouble:]` instead -of `-[NSNumber numberWithFloat:]` to avoid precision issues. - -### Key paths - -A key path expression refers to an attribute of the `MGLFeature` object being -evaluated for display. For example, if a polygon’s `MGLFeature.attributes` -dictionary contains the `floorCount` key, then the key path `floorCount` refers -to the value of the `floorCount` attribute when evaluating that particular -polygon. - -The following special attributes are also available on features that are produced -as a result of clustering multiple point features together in a shape source: - -<table> -<thead> -<tr><th>Attribute</th><th>Type</th><th>Meaning</th></tr> -</thead> -<tbody> -<tr> - <td><code>cluster</code></td> - <td>Bool</td> - <td>True if the feature is a point cluster. If the attribute is false (or not present) then the feature should not be considered a cluster.</td> -</tr> -<tr> - <td><code>cluster_id</code></td> - <td>Number</td> - <td>Identifier for the point cluster.</td> -</tr> -<tr> - <td><code>point_count</code></td> - <td>Number</td> - <td>The number of point features in a given cluster.</td> -</tr> -</tbody> -</table> - -Some characters may not be used directly as part of a key path in a format -string. For example, if a feature’s attribute is named `ISO 3166-1:2006`, an -expression format string of `lowercase(ISO 3166-1:2006)` or a predicate format -string of `ISO 3166-1:2006 == 'US-OH'` would raise an exception. Instead, use a -`%K` placeholder or the `+[NSExpression expressionForKeyPath:]` initializer: - -```objc -[NSPredicate predicateWithFormat:@"%K == 'US-OH'", @"ISO 3166-1:2006"]; -[NSExpression expressionForFunction:@"lowercase:" - arguments:@[[NSExpression expressionForKeyPath:@"ISO 3166-1:2006"]]] -``` - -```swift -NSPredicate(format: "%K == 'US-OH'", "ISO 3166-1:2006") -NSExpression(forFunction: "lowercase:", - arguments: [NSExpression(forKeyPath: "ISO 3166-1:2006")]) -``` - -### Functions - -Of the -[functions predefined](https://developer.apple.com/documentation/foundation/nsexpression/1413747-init#discussion) -by the -[`+[NSExpression expressionForFunction:arguments:]` method](https://developer.apple.com/documentation/foundation/nsexpression/1413747-init), -the following subset is supported in layer attribute values: - -Initializer parameter | Format string syntax -----------------------|--------------------- -`average:` | `average({1, 2, 2, 3, 4, 7, 9})` -`sum:` | `sum({1, 2, 2, 3, 4, 7, 9})` -`count:` | `count({1, 2, 2, 3, 4, 7, 9})` -`min:` | `min({1, 2, 2, 3, 4, 7, 9})` -`max:` | `max({1, 2, 2, 3, 4, 7, 9})` -`add:to:` | `1 + 2` -`from:subtract:` | `2 - 1` -`multiply:by:` | `1 * 2` -`divide:by:` | `1 / 2` -`modulus:by:` | `modulus:by:(1, 2)` -`sqrt:` | `sqrt(2)` -`log:` | `log(10)` -`ln:` | `ln(2)` -`raise:toPower:` | `2 ** 2` -`exp:` | `exp(0)` -`ceiling:` | `ceiling(0.99999)` -`abs:` | `abs(-1)` -`trunc:` | `trunc(6378.1370)` -`floor:` | `floor(-0.99999)` -`uppercase:` | `uppercase('Elysian Fields')` -`lowercase:` | `lowercase('DOWNTOWN')` -`noindex:` | `noindex(0 + 2 + c)` -`length:` | `length('Wapakoneta')` -`castObject:toType:` | `CAST(ele, 'NSString')`<br>`CAST(ele, 'NSNumber')` - -A number of [Mapbox-specific functions](#mapbox-specific-functions) are also -available. - -The following predefined functions are **not** supported: - -Initializer parameter | Format string syntax -----------------------|--------------------- -`median:` | `median({1, 2, 2, 3, 4, 7, 9})` -`mode:` | `mode({1, 2, 2, 3, 4, 7, 9})` -`stddev:` | `stddev({1, 2, 2, 3, 4, 7, 9})` -`random` | `random()` -`randomn:` | `randomn(10)` -`now` | `now()` -`bitwiseAnd:with:` | `bitwiseAnd:with:(5, 3)` -`bitwiseOr:with:` | `bitwiseOr:with:(5, 3)` -`bitwiseXor:with:` | `bitwiseXor:with:(5, 3)` -`leftshift:by:` | `leftshift:by:(23, 1)` -`rightshift:by:` | `rightshift:by:(23, 1)` -`onesComplement:` | `onesComplement(255)` -`distanceToLocation:fromLocation:` | `distanceToLocation:fromLocation:(there, here)` - -### Conditionals - -Conditionals are supported via the built-in -`+[NSExpression expressionForConditional:trueExpression:falseExpression:]` -method and `TERNARY()` operator. If you need to express multiple cases -(“else-if”), you can either nest a conditional within a conditional or use the -[`MGL_IF()`](#code-mgl_if-code) or [`MGL_MATCH()`](#code-mgl_match-code) function. - -### Aggregates - -Aggregate expressions can contain arrays of expressions. In some cases, it is -possible to use the array itself instead of wrapping the array in an aggregate -expression. - -### Variables - -The following variables are defined by this SDK for use with style layers: - -<table> -<thead> -<tr><th>Variable</th><th>Type</th><th>Meaning</th></tr> -</thead> -<tbody> -<tr> - <td><code>$featureIdentifier</code></td> - <td> - Any - <a href="working-with-geojson-data.html#about-geojson-deserialization">GeoJSON data type</a> - </td> - <td> - A value that uniquely identifies the feature in the containing source. - This variable corresponds to the - <code>NSExpression.featureIdentifierVariableExpression</code> property. - </td> -</tr> -<tr> - <td><code>$geometryType</code></td> - <td>String</td> - <td> - The type of geometry represented by the feature. A feature’s type is one - of the following strings: - <ul> - <li> - <code>Point</code> for point features, corresponding to the - <code>MGLPointAnnotation</code> class - </li> - <li> - <code>LineString</code> for polyline features, corresponding to - the <code>MGLPolyline</code> class - </li> - <li> - <code>Polygon</code> for polygon features, corresponding to the - <code>MGLPolygon</code> class - </li> - </ul> - This variable corresponds to the - <code>NSExpression.geometryTypeVariableExpression</code> property. - </td> -</tr> -<tr> - <td><code>$heatmapDensity</code></td> - <td>Number</td> - <td> - The - <a href="https://en.wikipedia.org/wiki/Kernel_density_estimation">kernel density estimation</a> - of a screen point in a heatmap layer; in other words, a relative measure - of how many data points are crowded around a particular pixel. This - variable can only be used with the <code>heatmapColor</code> property. - This variable corresponds to the - <code>NSExpression.heatmapDensityVariableExpression</code> property. - </td> -</tr> -<tr> - <td><code>$zoomLevel</code></td> - <td>Number</td> - <td> - The current zoom level. In style layout and paint properties, this - variable may only appear as the target of a top-level interpolation or - step expression. This variable corresponds to the - <code>NSExpression.zoomLevelVariableExpression</code> property. - </td> -</tr> -<tr> - <td><code>$lineProgress</code></td> - <td>Number</td> - <td> - A number that indicates the relative distance along a line at a given - point along the line. This variable evaluates to 0 at the beginning of the - line and 1 at the end of the line. It can only be used with the - `MGLLineStyleLayer.lineGradient` property. It corresponds to the - <code>NSExpression.lineProgressVariableExpression</code> property. - </td> -</tr> -</tbody> -</table> - -In addition to these variables, you can define your own variables and refer to -them elsewhere in the expression. The syntax for defining a variable makes use -of a [Mapbox-specific function](#mapbox-specific-functions) that takes an -`NSDictionary` as an argument: - -```objc -[NSExpression expressionWithFormat:@"MGL_LET('floorCount', 2, $floorCount + 1)"]; -``` - -```swift -NSExpression(format: "MGL_LET(floorCount, 2, $floorCount + 1)") -``` - -## Mapbox-specific functions - -For compatibility with the Mapbox Style Specification, the following functions -are defined by this SDK. When setting a style layer property, you can call these -functions just like the predefined functions above, using either the -`+[NSExpression expressionForFunction:arguments:]` method or a convenient format -string syntax: - -### `mgl_does:have:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_does:have:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>mgl_does:have:(SELF, '🧀🍔')</code> or <code>mgl_does:have:(%@, '🧀🍔')</code></dd> -</dl> - -Returns a Boolean value indicating whether the dictionary has a value for the -key or whether the evaluated object (`SELF`) has a value for the feature -attribute. Compared to the [`mgl_has:`](#code-mgl_has-code) custom function, -that function’s target is instead passed in as the first argument to this -function. Both functions are equivalent to the syntax `key != NIL` or -`%@[key] != NIL` but can be used outside of a predicate. - -### `mgl_interpolate:withCurveType:parameters:stops:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_interpolate:withCurveType:parameters:stops:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>mgl_interpolate:withCurveType:parameters:stops:(x, 'linear', nil, %@)</code></dd> -</dl> - -Produces continuous, smooth results by interpolating between pairs of input and -output values (“stops”). Compared to the -[`mgl_interpolateWithCurveType:parameters:stops:`](#code-mgl_interpolatewithcurvetype-parameters-stops-code) -custom function, the input expression (that function’s target) is instead passed -in as the first argument to this function. - -### `mgl_step:from:stops:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_step:from:stops:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>mgl_step:from:stops:(x, 11, %@)</code></dd> -</dl> - -Produces discrete, stepped results by evaluating a piecewise-constant function -defined by pairs of input and output values ("stops"). Compared to the -[`mgl_stepWithMinimum:stops:`](#code-mgl_stepwithminimum-stops-code) custom -function, the input expression (that function’s target) is instead passed in as -the first argument to this function. - -### `mgl_join:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_join:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>mgl_join({'Old', 'MacDonald'})</code></dd> -</dl> - -Returns the result of concatenating together all the elements of an array in -order. Compared to the -[`stringByAppendingString:`](#code-stringbyappendingstring-code) custom -function, this function takes only one argument, which is an aggregate -expression containing the strings to concatenate. - -### `mgl_acos:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_acos:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>mgl_acos(1)</code></dd> -</dl> - -Returns the arccosine of the number. - -This function corresponds to the -[`acos`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-acos) -operator in the Mapbox Style Specification. - -### `mgl_asin:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_asin:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>mgl_asin(0)</code></dd> -</dl> - -Returns the arcsine of the number. - -This function corresponds to the -[`asin`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-asin) -operator in the Mapbox Style Specification. - -### `mgl_atan:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_atan:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>mgl_atan(20)</code></dd> -</dl> - -Returns the arctangent of the number. - -This function corresponds to the -[`atan`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-atan) -operator in the Mapbox Style Specification. - -### `mgl_cos:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_cos:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>mgl_cos(0)</code></dd> -</dl> - -Returns the cosine of the number. - -This function corresponds to the -[`cos`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-cos) -operator in the Mapbox Style Specification. - -### `mgl_log2:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_log2:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>mgl_log2(1024)</code></dd> -</dl> - -Returns the base-2 logarithm of the number. - -This function corresponds to the -[`log2`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-log2) -operator in the Mapbox Style Specification. - -### `mgl_round:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_round:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>mgl_round(1.5)</code></dd> -</dl> - -Returns the number rounded to the nearest integer. If the number is halfway -between two integers, this function rounds it away from zero. - -This function corresponds to the -[`round`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-round) -operator in the Mapbox Style Specification. - -### `mgl_sin:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_sin:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>mgl_sin(0)</code></dd> -</dl> - -Returns the sine of the number. - -This function corresponds to the -[`sin`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-sin) -operator in the Mapbox Style Specification. - -### `mgl_tan:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_tan:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>mgl_tan(0)</code></dd> -</dl> - -Returns the tangent of the number. - -This function corresponds to the -[`tan`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-tan) -operator in the Mapbox Style Specification. - -### `mgl_coalesce:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_coalesce:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>mgl_coalesce({x, y, z})</code></dd> -</dl> - -Returns the first non-`nil` value from an array of expressions. - -This function corresponds to the -[`coalesce`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-coalesce) -operator in the Mapbox Style Specification. - -### `mgl_attributed:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_attributed:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>mgl_attributed({x, y, z})</code></dd> -</dl> - -Concatenates and returns the array of `MGLAttributedExpression` objects, for use -with the `MGLSymbolStyleLayer.text` property. - -`MGLAttributedExpression.attributes` valid attributes. - - Key | Value Type - --- | --- - `MGLFontNamesAttribute` | An `NSExpression` evaluating to an `NSString` array. - `MGLFontScaleAttribute` | An `NSExpression` evaluating to an `NSNumber` value. - `MGLFontColorAttribute` | An `NSExpression` evaluating to an `UIColor` (iOS) or `NSColor` (macOS). - -This function corresponds to the -[`format`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-types-format) -operator in the Mapbox Style Specification. - -### `MGL_LET` - -<dl> -<dt>Selector:</dt> -<dd><code>MGL_LET:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>MGL_LET('age', uppercase('old'), 'name', uppercase('MacDonald'), mgl_join({$age, $name}))</code></dd> -<dt>Arguments:</dt> -<dd> - Any number of variable names interspersed with their assigned - <code>NSExpression</code> values, followed by an <code>NSExpression</code> - that may contain references to those variables. -</dd> -</dl> - -Returns the result of evaluating an expression with the given variable values. -Compared to the -[`mgl_expressionWithContext:`](#code-mgl_expressionwithcontext-code) custom -function, this function takes the variable names and values inline before the -expression that contains references to those variables. - -### `MGL_MATCH` - -<dl> -<dt>Selector:</dt> -<dd><code>MGL_MATCH:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>MGL_MATCH(x, 0, 'zero match', 1, 'one match', 2, 'two match', 'default')</code></dd> -<dt>Arguments:</dt> -<dd> - An input expression, then any number of argument pairs, followed by a default - expression. Each argument pair consists of a constant value followed by an - expression to produce as a result of matching that constant value. - If the input value is an aggregate expression, then any of the constant values within - that aggregate expression result in the following argument. This is shorthand for - specifying an argument pair for each of the constant values within that aggregate - expression. It is not possible to match the aggregate expression itself. -</dd> -</dl> - -Returns the result of matching the input expression against the given constant -values. - -This function corresponds to the -`+[NSExpression(MGLAdditions) mgl_expressionForMatchingExpression:inDictionary:defaultExpression:]` -method and the -[`match`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-match) -operator in the Mapbox Style Specification. - -### `MGL_IF` - -<dl> -<dt>Selector:</dt> -<dd><code>MGL_IF:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>MGL_IF(1 = 2, YES, 2 = 2, YES, NO)</code></dd> -<dt>Arguments:</dt> -<dd> - Alternating <code>NSPredicate</code> conditionals and resulting expressions, - followed by a default expression. -</dd> -</dl> - -Returns the first expression that meets the condition; otherwise, the default -value. Unlike -`+[NSExpression expressionForConditional:trueExpression:falseExpression:]` or -the `TERNARY()` syntax, this function can accept multiple “if else” conditions -and is supported on iOS 8._x_ and macOS 10.10._x_; however, each conditional -passed into this function must be wrapped in a constant expression. - -This function corresponds to the -`+[NSExpression(MGLAdditions) mgl_expressionForConditional:trueExpression:falseExpresssion:]` -method and the -[`case`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-case) -operator in the Mapbox Style Specification. - -### `MGL_FUNCTION` - -<dl> -<dt>Selector:</dt> -<dd><code>MGL_FUNCTION:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>MGL_FUNCTION('typeof', mystery)</code></dd> -<dt>Arguments:</dt> -<dd> - Any arguments required by the expression operator. -</dd> -</dl> - -An expression exactly as defined by the -[Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions). - -## Custom functions - -The following custom functions are also available with the -`+[NSExpression expressionForFunction:selectorName:arguments:]` method or the -`FUNCTION()` format string syntax. - -Some of these functions are defined as methods on their respective target -classes, but you should not call them directly outside the context of an -expression, because the result may differ from the evaluated expression’s result -or may result in undefined behavior. - -The Mapbox Style Specification defines some operators for which no custom -function is available. To use these operators in an `NSExpression`, call the -[`MGL_FUNCTION()`](#code-mgl_function-code) function with the same arguments -that the operator expects. - -### `boolValue` - -<dl> -<dt>Selector:</dt> -<dd><code>boolValue</code></dd> -<dt>Format string syntax:</dt> -<dd><code>FUNCTION(1, 'boolValue')</code></dd> -<dt>Target:</dt> -<dd> - An <code>NSExpression</code> that evaluates to a number or string. -</dd> -<dt>Arguments:</dt> -<dd>None.</dd> -</dl> - -A Boolean representation of the target: <code>FALSE</code> when then input is an -empty string, 0, <code>FALSE</code>, <code>NIL</code>, or <code>NaN</code>, -otherwise <code>TRUE</code>. - -### `mgl_has:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_has:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>FUNCTION($featureAttributes, 'mgl_has:', '🧀🍔')</code></dd> -<dt>Target:</dt> -<dd> - An <code>NSExpression</code> that evaluates to an <code>NSDictionary</code> - or the evaluated object (<code>SELF</code>). -</dd> -<dt>Arguments:</dt> -<dd> - An <code>NSExpression</code> that evaluates to an <code>NSString</code> - representing the key to look up in the dictionary or the feature attribute to - look up in the evaluated object (see <code>MGLFeature.attributes</code>). -</dd> -</dl> - -<code>true</code> if the dictionary has a value for the key or if the evaluated -object has a value for the feature attribute. - -This function corresponds to the -[`has`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-has) -operator in the Mapbox Style Specification. See also the -[`mgl_does:have:`](#code-mgl_does-have-code) function, which is used on its own -without the `FUNCTION()` operator. You can also check whether an object has an -attribute by comparing the key path to `NIL`, for example `cheeseburger != NIL` -or `burger.cheese != NIL` - -### `mgl_expressionWithContext:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_expressionWithContext:</code></dd> -<dt>Format string syntax:</dt> -<dd> - <code>FUNCTION($ios + $macos, 'mgl_expressionWithContext:', %@)</code> with - a dictionary containing <code>ios</code> and <code>macos</code> keys -</dd> -<dt>Target:</dt> -<dd> - An <code>NSExpression</code> that may contain references to the variables - defined in the context dictionary. -</dd> -<dt>Arguments:</dt> -<dd> - An <code>NSDictionary</code> with <code>NSString</code>s as keys and - <code>NSExpression</code>s as values. Each key is a variable name and each - value is the variable’s value within the target expression. -</dd> -</dl> - -The target expression with variable subexpressions replaced with the values -defined in the context dictionary. - -This function corresponds to the -[`let`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-let) -operator in the Mapbox Style Specification. See also the -[`MGL_LET`](#code-mgl_let-code) function, which is used on its own without the -`FUNCTION()` operator. - -### `mgl_interpolateWithCurveType:parameters:stops:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_interpolateWithCurveType:parameters:stops:</code></dd> -<dt>Format string syntax:</dt> -<dd> - <code>FUNCTION($zoomLevel, 'mgl_interpolateWithCurveType:parameters:stops:', 'linear', NIL, %@)</code> - with a dictionary containing zoom levels or other constant values as keys -</dd> -<dt>Target:</dt> -<dd> - An <code>NSExpression</code> that evaluates to a number and contains a - variable or key path expression. -</dd> -<dt>Arguments:</dt> -<dd> - The first argument is one of the following strings denoting curve types: - <code>linear</code>, <code>exponential</code>, or <code>cubic-bezier</code>. - - The second argument is an expression providing parameters for the curve: - - <ul> - <li>If the curve type is <code>linear</code>, the argument is <code>NIL</code>.</li> - <li> - If the curve type is <code>exponential</code>, the argument is an - expression that evaluates to a number, specifying the base of the - exponential interpolation. - </li> - <li> - If the curve type is <code>cubic-bezier</code>, the argument is an - array or aggregate expression containing four expressions, each - evaluating to a number. The four numbers are control points for the - cubic Bézier curve. - </li> - </ul> - - The third argument is an <code>NSDictionary</code> object representing the - interpolation’s stops, with numeric zoom levels as keys and expressions as - values. -</dd> -</dl> - -A value interpolated along the continuous mathematical function defined by the -arguments, with the target as the input to the function. - -The input expression is matched against the keys in the stop dictionary. The -keys may be feature attribute values, zoom levels, or heatmap densities. The -values may be constant values or `NSExpression` objects. 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. - -This function corresponds to the -`+[NSExpression(MGLAdditions) mgl_expressionForInterpolatingExpression:withCurveType:parameters:stops:]` -method and the -[`interpolate`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-interpolate) -operator in the Mapbox Style Specification. See also the -[`mgl_interpolate:withCurveType:parameters:stops:`](#code-mgl_interpolate-withcurvetype-parameters-stops-code) -function, which is used on its own without the `FUNCTION()` operator. - -### `mgl_numberWithFallbackValues:` - -<dl> -<dt>Selector:</dt> -<dd> - <code>mgl_numberWithFallbackValues:</code>, - <code>doubleValue</code>, - <code>floatValue</code>, or - <code>decimalValue</code> -</dd> -<dt>Format string syntax:</dt> -<dd><code>FUNCTION(ele, 'mgl_numberWithFallbackValues:', 0)</code></dd> -<dt>Target:</dt> -<dd> - An <code>NSExpression</code> that evaluates to a Boolean value, number, or - string. -</dd> -<dt>Arguments:</dt> -<dd> - Zero or more <code>NSExpression</code>s, each evaluating to a Boolean value - or string. -</dd> -</dl> - -A numeric representation of the target: - -* If the target is <code>NIL</code> or <code>FALSE</code>, the result is 0. -* If the target is true, the result is 1. - * If the target is a string, it is converted to a number as specified by the - “[ToNumber Applied to the String Type](https://tc39.github.io/ecma262/#sec-tonumber-applied-to-the-string-type)” - algorithm of the ECMAScript Language Specification. - * If multiple values are provided, each one is evaluated in order until the - first successful conversion is obtained. - -This function corresponds to the -[`to-number`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-types-to-number) -operator in the Mapbox Style Specification. You can also cast a value to a -number by passing the value and the string `NSNumber` into the `CAST()` -operator. - -### `mgl_stepWithMinimum:stops:` - -<dl> -<dt>Selector:</dt> -<dd><code>mgl_stepWithMinimum:stops:</code></dd> -<dt>Format string syntax:</dt> -<dd> - <code>FUNCTION($zoomLevel, 'mgl_stepWithMinimum:stops:', 0, %@)</code> with - a dictionary with zoom levels or other constant values as keys -</dd> -<dt>Target:</dt> -<dd> - An <code>NSExpression</code> that evaluates to a number and contains a - variable or key path expression. -</dd> -<dt>Arguments:</dt> -<dd> - The first argument is an expression that evaluates to a number, specifying - the minimum value in case the target is less than any of the stops in the - second argument. - - The second argument is an <code>NSDictionary</code> object representing the - interpolation’s stops, with numeric zoom levels as keys and expressions as - values. -</dd> -</dl> - -The output value of the stop whose key is just less than the evaluated target, -or the minimum value if the target is less than the least of the stops’ keys. - -The input expression is matched against the keys in the stop dictionary. The -keys may be feature attribute values, zoom levels, or heatmap densities. The -values may be constant values or `NSExpression` objects. 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. - -This function corresponds to the -`+[NSExpression(MGLAdditions) mgl_expressionForSteppingExpression:fromExpression:stops:]` -method and the -[`step`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-step) -operator in the Mapbox Style Specification. - -### `stringByAppendingString:` - -<dl> -<dt>Selector:</dt> -<dd><code>stringByAppendingString:</code></dd> -<dt>Format string syntax:</dt> -<dd><code>FUNCTION('Old', 'stringByAppendingString:', 'MacDonald')</code></dd> -<dt>Target:</dt> -<dd>An <code>NSExpression</code> that evaluates to a string.</dd> -<dt>Arguments:</dt> -<dd>One or more <code>NSExpression</code>s, each evaluating to a string.</dd> -</dl> - -The target string with each of the argument strings appended in order. - -This function corresponds to the -`-[NSExpression(MGLAdditions) mgl_expressionByAppendingExpression:]` -method and is similar to the -[`concat`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-concat) -operator in the Mapbox Style Specification. See also the -[`mgl_join:`](#code-mgl_join-code) function, which concatenates multiple -expressions and is used on its own without the `FUNCTION()` operator. - -### `stringValue` - -<dl> -<dt>Selector:</dt> -<dd><code>stringValue</code></dd> -<dt>Format string syntax:</dt> -<dd><code>FUNCTION(ele, 'stringValue')</code></dd> -<dt>Target:</dt> -<dd> - An <code>NSExpression</code> that evaluates to a Boolean value, number, or - string. -</dd> -<dt>Arguments:</dt> -<dd>None.</dd> -</dl> - -A string representation of the target: - -* If the target is <code>NIL</code>, the result is the empty string. -* If the target is a Boolean value, the result is the string `true` or `false`. -* If the target is a number, it is converted to a string as specified by the - “[NumberToString](https://tc39.github.io/ecma262/#sec-tostring-applied-to-the-number-type)” - algorithm of the ECMAScript Language Specification. -* If the target is a color, it is converted to a string of the form - `rgba(r,g,b,a)`, where <var>r</var>, <var>g</var>, and <var>b</var> are - numerals ranging from 0 to 255 and <var>a</var> ranges from 0 to 1. -* Otherwise, the target is converted to a string in the format specified by the - [`JSON.stringify()`](https://tc39.github.io/ecma262/#sec-json.stringify) - function of the ECMAScript Language Specification. - -This function corresponds to the -[`to-string`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-types-to-string) -operator in the Mapbox Style Specification. You can also cast a value to a -string by passing the value and the string `NSString` into the `CAST()` -operator. diff --git a/platform/darwin/docs/guides/Tile URL Templates.md.ejs b/platform/darwin/docs/guides/Tile URL Templates.md.ejs deleted file mode 100644 index 2b1de65b42..0000000000 --- a/platform/darwin/docs/guides/Tile URL Templates.md.ejs +++ /dev/null @@ -1,109 +0,0 @@ -<% - const os = locals.os; - const iOS = os === 'iOS'; - //const macOS = os === 'macOS'; - //const cocoaPrefix = iOS ? 'UI' : 'NS'; --%> -<!-- - This file is generated. - Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`. ---> -# Tile URL Templates - -`MGLTileSource` objects, specifically `MGLRasterTileSource` and -`MGLVectorTileSource` objects, can be created using an initializer that accepts -an array of tile URL templates. Tile URL templates are strings that specify the -URLs of the vector tiles or raster tile images to load. A template resembles an -absolute URL, but with any number of placeholder strings that the source -evaluates based on the tile it needs to load. For example: - -* `http://www.example.com/tiles/{z}/{x}/{y}.pbf` could be - evaluated as `http://www.example.com/tiles/14/6/9.pbf`. -* `http://www.example.com/tiles/{z}/{x}/{y}{ratio}.png` could be - evaluated as `http://www.example.com/tiles/14/6/9@2x.png`. - -Tile URL templates are also used to define tilesets in TileJSON manifests or -[`raster`](https://www.mapbox.com/mapbox-gl-js/style-spec/#sources-raster-tiles) -and -[`vector`](https://www.mapbox.com/mapbox-gl-js/style-spec/#sources-vector-tiles) -sources in style JSON files. See the -[TileJSON specification](https://github.com/mapbox/tilejson-spec/tree/master/2.2.0) -for information about tile URL templates in the context of a TileJSON or style -JSON file. - -Tile sources support the following placeholder strings in tile URL templates, -all of which are optional: - -<table> -<thead> -<tr><th>Placeholder string</th><th>Description</th></tr> -</thead> -<tbody> -<tr> - <td><code>{x}</code></td> - <td>The index of the tile along the map’s x axis according to Spherical - Mercator projection. If the value is 0, the tile’s left edge corresponds - to the 180th meridian west. If the value is 2<sup><var>z</var></sup>−1, - the tile’s right edge corresponds to the 180th meridian east.</td> -</tr> -<tr> - <td><code>{y}</code></td> - <td>The index of the tile along the map’s y axis according to Spherical - Mercator projection. If the value is 0, the tile’s tile edge corresponds - to arctan(sinh(π)), or approximately 85.0511 degrees north. If the value - is 2<sup><var>z</var></sup>−1, the tile’s bottom edge corresponds to - −arctan(sinh(π)), or approximately 85.0511 degrees south. The y axis is - inverted if the <code>options</code> parameter contains - <code>MGLTileSourceOptionTileCoordinateSystem</code> with a value of - <code>MGLTileCoordinateSystemTMS</code>.</td> -</tr> -<tr> - <td><code>{z}</code></td> - <td>The tile’s zoom level. At zoom level 0, each tile covers the entire - world map; at zoom level 1, it covers ¼ of the world; at zoom level 2, - <sup>1</sup>⁄<sub>16</sub> of the world, and so on. For tiles loaded by - a <code>MGLRasterTileSource</code> object, whether the tile zoom level - matches the map’s current zoom level depends on the value of the - source’s tile size as specified in the - <code>MGLTileSourceOptionTileSize</code> key of the <code>options</code> - parameter.</td> -</tr> -<tr> - <td><code>{bbox-epsg-3857}</code></td> - <td>The tile’s bounding box, expressed as a comma-separated list of the - tile’s western, southern, eastern, and northern extents according to - Spherical Mercator (EPSG:3857) projection. The bounding box is typically - used with map services conforming to the - <a href="http://www.opengeospatial.org/standards/wms">Web Map Service</a> - protocol.</td> -</tr> -<tr> - <td><code>{quadkey}</code></td> - <td>A quadkey indicating both the tile’s location and its zoom level. The - quadkey is typically used with - <a href="https://msdn.microsoft.com/en-us/library/bb259689.aspx">Bing Maps</a>. - </td> -</tr> -<tr> - <td><code>{ratio}</code></td> - <td>A suffix indicating the resolution of the tile image. The suffix is the - empty string for standard resolution displays and <code>@2x</code> for -<% if (iOS) { -%> - Retina displays, including displays for which <code>UIScreen.scale</code> - is 3. -<% } else { -%> - Retina displays. -<% } -%> - </td> -</tr> -<tr> - <td><code>{prefix}</code></td> - <td>Two hexadecimal digits chosen such that each visible tile has a - different prefix. The prefix is typically used for domain sharding.</td> -</tr> -</tbody> -</table> - -For more information about the `{x}`, `{y}`, and `{z}` placeholder strings, -consult the -[OpenStreetMap Wiki](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames). diff --git a/platform/darwin/docs/guides/Working with GeoJSON Data.md b/platform/darwin/docs/guides/Working with GeoJSON Data.md deleted file mode 100644 index 269bb86039..0000000000 --- a/platform/darwin/docs/guides/Working with GeoJSON Data.md +++ /dev/null @@ -1,101 +0,0 @@ -# Working with GeoJSON Data - -This SDK offers several ways to work with [GeoJSON](http://geojson.org/) files. -GeoJSON is a standard file format for representing geographic data. - -## Adding a GeoJSON file to the map - -You can use -[Mapbox Studio’s Datasets editor](https://www.mapbox.com/studio/datasets/) to -upload a GeoJSON file and include it in your custom map style. The GeoJSON data -will be hosted on Mapbox servers. When a user loads your style, the SDK -automatically loads the GeoJSON data for display. - -Alternatively, if you need to host the GeoJSON file elsewhere or bundle it with -your application, you can use a GeoJSON file as the basis of an `MGLShapeSource` -object. Pass the file’s URL into the -`-[MGLShapeSource initWithIdentifier:URL:options:]` initializer and add the -shape source to the map using the `-[MGLStyle addSource:]` method. The URL may -be a local file URL, an HTTP URL, or an HTTPS URL. - -Once you’ve added the GeoJSON file to the map via an `MGLShapeSource` object, -you can configure the appearance of its data and control what data is visible -using `MGLStyleLayer` objects. You can also -[access the data programmatically](#extracting-geojson-data-from-the-map). - -## Converting GeoJSON data into shape objects - -If you have GeoJSON data in the form of source code (also known as “GeoJSON -text”), you can convert it into an `MGLShape`, `MGLFeature`, or -`MGLShapeCollectionFeature` object that the `MGLShapeSource` class understands -natively. First, create an `NSData` object out of the source code string or file -contents, then pass that data object into the -`+[MGLShape shapeWithData:encoding:error:]` method. Finally, you can pass the -resulting shape or feature object into the -`-[MGLShapeSource initWithIdentifier:shape:options:]` initializer and add it to -the map, or you can use the object and its properties to power non-map-related -functionality in your application. - -To include multiple shapes in the source, create and pass an `MGLShapeCollection` or - `MGLShapeCollectionFeature` object to - `-[MGLShapeSource initWithIdentifier:shape:options:]`. Alternatively, use the - `-[MGLShapeSource initWithIdentifier:features:options:]` or - `-[MGLShapeSource initWithIdentifier:shapes:options:]` method to create a shape source - with an array. `-[MGLShapeSource initWithIdentifier:features:options:]` accepts only `MGLFeature` - instances, such as `MGLPointFeature` objects, whose attributes you can use when - applying a predicate to `MGLVectorStyleLayer` or configuring a style layer’s - appearance. - -## Extracting GeoJSON data from the map - -Any `MGLShape`, `MGLFeature`, or `MGLShapeCollectionFeature` object has an -`-[MGLShape geoJSONDataUsingEncoding:]` method that you can use to create a -GeoJSON source code representation of the object. You can extract a feature -object from the map using a method such as -`-[MGLMapView visibleFeaturesAtPoint:]`. - -## About GeoJSON deserialization - -The process of converting GeoJSON text into `MGLShape`, `MGLFeature`, or -`MGLShapeCollectionFeature` objects is known as “GeoJSON deserialization”. -GeoJSON geometries, features, and feature collections are known in this SDK as -shapes, features, and shape collection features, respectively. - -Each GeoJSON object type corresponds to a type provided by either this SDK or -the Core Location framework: - -GeoJSON object type | SDK type ---------------------|--------- -`Position` (longitude, latitude) | `CLLocationCoordinate2D` (latitude, longitude) -`Point` | `MGLPointAnnotation` -`MultiPoint` | `MGLPointCollection` -`LineString` | `MGLPolyline` -`MultiLineString` | `MGLMultiPolyline` -`Polygon` | `MGLPolygon` -Linear ring | `MGLPolygon.coordinates`, `MGLPolygon.interiorPolygons` -`MultiPolygon` | `MGLMultiPolygon` -`GeometryCollection` | `MGLShapeCollection` -`Feature` | `MGLFeature` -`FeatureCollection` | `MGLShapeCollectionFeature` - -A `Feature` object in GeoJSON corresponds to an instance of an `MGLShape` -subclass conforming to the `MGLFeature` protocol. There is a distinct -`MGLFeature`-conforming class for each type of geometry that a GeoJSON feature -can contain. This allows features to be used as raw shapes where convenient. For -example, some features can be added to a map view as annotations. Note that -identifiers and attributes will not be available for feature querying when a -feature is used as an annotation. - -In contrast to the GeoJSON standard, it is possible for `MGLShape` subclasses -other than `MGLPointAnnotation` to straddle the antimeridian. - -The following GeoJSON data types correspond straightforwardly to Foundation data -types when they occur as feature identifiers or property values: - -GeoJSON data type | Objective-C representation | Swift representation --------------------|----------------------------|--------------------- -`null` | `NSNull` | `NSNull` -`true`, `false` | `NSNumber.boolValue` | `Bool` -Integer | `NSNumber.unsignedLongLongValue`, `NSNumber.longLongValue` | `UInt64`, `Int64` -Floating-point number | `NSNumber.doubleValue` | `Double` -String | `NSString` | `String` diff --git a/platform/darwin/docs/img/data-driven-styling/cast.png b/platform/darwin/docs/img/data-driven-styling/cast.png Binary files differdeleted file mode 100644 index e5b40b4ffa..0000000000 --- a/platform/darwin/docs/img/data-driven-styling/cast.png +++ /dev/null diff --git a/platform/darwin/docs/img/data-driven-styling/exponential-function-1.png b/platform/darwin/docs/img/data-driven-styling/exponential-function-1.png Binary files differdeleted file mode 100644 index 39a8a2a1e4..0000000000 --- a/platform/darwin/docs/img/data-driven-styling/exponential-function-1.png +++ /dev/null diff --git a/platform/darwin/docs/img/data-driven-styling/exponential-function.png b/platform/darwin/docs/img/data-driven-styling/exponential-function.png Binary files differdeleted file mode 100644 index f9824fc5e4..0000000000 --- a/platform/darwin/docs/img/data-driven-styling/exponential-function.png +++ /dev/null diff --git a/platform/darwin/docs/img/data-driven-styling/identity.png b/platform/darwin/docs/img/data-driven-styling/identity.png Binary files differdeleted file mode 100644 index 3355694ec9..0000000000 --- a/platform/darwin/docs/img/data-driven-styling/identity.png +++ /dev/null diff --git a/platform/darwin/docs/img/data-driven-styling/multiply.png b/platform/darwin/docs/img/data-driven-styling/multiply.png Binary files differdeleted file mode 100644 index df42f243e1..0000000000 --- a/platform/darwin/docs/img/data-driven-styling/multiply.png +++ /dev/null diff --git a/platform/darwin/docs/theme b/platform/darwin/docs/theme deleted file mode 160000 -Subproject 75b9170a8b9f85d64f94e3083f8204edce10302 |
