diff options
Diffstat (limited to 'platform/macos/docs')
| -rw-r--r-- | platform/macos/docs/doc-README.md | 9 | ||||
| -rw-r--r-- | platform/macos/docs/guides/For Style Authors.md | 427 | ||||
| -rw-r--r-- | platform/macos/docs/guides/Info.plist Keys.md | 35 | ||||
| -rw-r--r-- | platform/macos/docs/guides/Migrating to Expressions.md | 267 | ||||
| -rw-r--r-- | platform/macos/docs/guides/Tile URL Templates.md | 98 | ||||
| -rw-r--r-- | platform/macos/docs/img/screenshot.jpg | bin | 411181 -> 0 bytes | |||
| -rw-r--r-- | platform/macos/docs/pod-README.md | 98 |
7 files changed, 0 insertions, 934 deletions
diff --git a/platform/macos/docs/doc-README.md b/platform/macos/docs/doc-README.md deleted file mode 100644 index 8ce2df39a4..0000000000 --- a/platform/macos/docs/doc-README.md +++ /dev/null @@ -1,9 +0,0 @@ -# [Mapbox Maps SDK for macOS](https://github.com/mapbox/mapbox-gl-native/tree/master/platform/macos/) - -The Mapbox Maps SDK for macOS is an open-source framework for embedding interactive map views with scalable, customizable vector maps into Cocoa applications on macOS 10.11.0 and above using Objective-C, Swift, Interface Builder, or AppleScript. The SDK takes stylesheets that conform to the [Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-style-spec/), applies them to vector tiles that conform to the [Mapbox Vector Tile Specification](https://www.mapbox.com/developers/vector-tiles/), and renders them using OpenGL. - - - -For setup information, consult the README.md that comes with this documentation. For further instructions, consult the [Mapbox Maps SDK for macOS documentation](https://mapbox.github.io/mapbox-gl-native/macos/). The [Mapbox Maps SDK for iOS](https://www.mapbox.com/ios-sdk/) has [API documentation](https://www.mapbox.com/ios-sdk/api/) and [online examples](https://www.mapbox.com/ios-sdk/examples/) that apply to the macOS SDK with few differences, mostly around unimplemented features like user location tracking. A [full changelog](https://github.com/mapbox/mapbox-gl-native/blob/master/platform/macos/CHANGELOG.md) is also available. - -Mapbox does not officially support the macOS SDK to the same extent as the iOS SDK; however, [bug reports and pull requests](https://github.com/mapbox/mapbox-gl-native/issues/) are certainly welcome. diff --git a/platform/macos/docs/guides/For Style Authors.md b/platform/macos/docs/guides/For Style Authors.md deleted file mode 100644 index 399ba6804b..0000000000 --- a/platform/macos/docs/guides/For Style Authors.md +++ /dev/null @@ -1,427 +0,0 @@ -<!-- - 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. - -## 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 macOS 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 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 - - -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 macOS. -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. -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. -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. -You can install cursor or tooltip tracking rectangles to indicate interactive -features as an alternative to prominent hover effects. - -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. - -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. - -The names of runtime styling classes and properties on macOS 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 ---------------|----------- -`background` | `MGLBackgroundStyleLayer` -`circle` | `MGLCircleStyleLayer` -`fill` | `MGLFillStyleLayer` -`fill-extrusion` | `MGLFillExtrusionStyleLayer` -`heatmap` | `MGLHeatmapStyleLayer` -`hillshade` | `MGLHillshadeStyleLayer` -`line` | `MGLLineStyleLayer` -`raster` | `MGLRasterStyleLayer` -`symbol` | `MGLSymbolStyleLayer` - -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: - -### Circle style layers - -In style JSON | In Objective-C | In Swift ---------------|----------------|--------- -`circle-pitch-scale` | `MGLCircleStyleLayer.circleScaleAlignment` | `MGLCircleStyleLayer.circleScaleAlignment` -`circle-translate` | `MGLCircleStyleLayer.circleTranslation` | `MGLCircleStyleLayer.circleTranslation` -`circle-translate-anchor` | `MGLCircleStyleLayer.circleTranslationAnchor` | `MGLCircleStyleLayer.circleTranslationAnchor` - -### Fill style layers - -In style JSON | In Objective-C | In Swift ---------------|----------------|--------- -`fill-antialias` | `MGLFillStyleLayer.fillAntialiased` | `MGLFillStyleLayer.isFillAntialiased` -`fill-translate` | `MGLFillStyleLayer.fillTranslation` | `MGLFillStyleLayer.fillTranslation` -`fill-translate-anchor` | `MGLFillStyleLayer.fillTranslationAnchor` | `MGLFillStyleLayer.fillTranslationAnchor` - -### Fill extrusion style layers - -In style JSON | In Objective-C | In Swift ---------------|----------------|--------- -`fill-extrusion-vertical-gradient` | `MGLFillExtrusionStyleLayer.fillExtrusionHasVerticalGradient` | `MGLFillExtrusionStyleLayer.fillExtrusionHasVerticalGradient` -`fill-extrusion-translate` | `MGLFillExtrusionStyleLayer.fillExtrusionTranslation` | `MGLFillExtrusionStyleLayer.fillExtrusionTranslation` -`fill-extrusion-translate-anchor` | `MGLFillExtrusionStyleLayer.fillExtrusionTranslationAnchor` | `MGLFillExtrusionStyleLayer.fillExtrusionTranslationAnchor` - -### Line style layers - -In style JSON | In Objective-C | In Swift ---------------|----------------|--------- -`line-dasharray` | `MGLLineStyleLayer.lineDashPattern` | `MGLLineStyleLayer.lineDashPattern` -`line-translate` | `MGLLineStyleLayer.lineTranslation` | `MGLLineStyleLayer.lineTranslation` -`line-translate-anchor` | `MGLLineStyleLayer.lineTranslationAnchor` | `MGLLineStyleLayer.lineTranslationAnchor` - -### Raster style layers - -In style JSON | In Objective-C | In Swift ---------------|----------------|--------- -`raster-brightness-max` | `MGLRasterStyleLayer.maximumRasterBrightness` | `MGLRasterStyleLayer.maximumRasterBrightness` -`raster-brightness-min` | `MGLRasterStyleLayer.minimumRasterBrightness` | `MGLRasterStyleLayer.minimumRasterBrightness` -`raster-hue-rotate` | `MGLRasterStyleLayer.rasterHueRotation` | `MGLRasterStyleLayer.rasterHueRotation` -`raster-resampling` | `MGLRasterStyleLayer.rasterResamplingMode` | `MGLRasterStyleLayer.rasterResamplingMode` - -### Symbol style layers - -In style JSON | In Objective-C | In Swift ---------------|----------------|--------- -`icon-allow-overlap` | `MGLSymbolStyleLayer.iconAllowsOverlap` | `MGLSymbolStyleLayer.iconAllowsOverlap` -`icon-ignore-placement` | `MGLSymbolStyleLayer.iconIgnoresPlacement` | `MGLSymbolStyleLayer.iconIgnoresPlacement` -`icon-image` | `MGLSymbolStyleLayer.iconImageName` | `MGLSymbolStyleLayer.iconImageName` -`icon-optional` | `MGLSymbolStyleLayer.iconOptional` | `MGLSymbolStyleLayer.isIconOptional` -`icon-rotate` | `MGLSymbolStyleLayer.iconRotation` | `MGLSymbolStyleLayer.iconRotation` -`icon-size` | `MGLSymbolStyleLayer.iconScale` | `MGLSymbolStyleLayer.iconScale` -`icon-keep-upright` | `MGLSymbolStyleLayer.keepsIconUpright` | `MGLSymbolStyleLayer.keepsIconUpright` -`text-keep-upright` | `MGLSymbolStyleLayer.keepsTextUpright` | `MGLSymbolStyleLayer.keepsTextUpright` -`text-max-angle` | `MGLSymbolStyleLayer.maximumTextAngle` | `MGLSymbolStyleLayer.maximumTextAngle` -`text-max-width` | `MGLSymbolStyleLayer.maximumTextWidth` | `MGLSymbolStyleLayer.maximumTextWidth` -`symbol-avoid-edges` | `MGLSymbolStyleLayer.symbolAvoidsEdges` | `MGLSymbolStyleLayer.symbolAvoidsEdges` -`text-field` | `MGLSymbolStyleLayer.text` | `MGLSymbolStyleLayer.text` -`text-allow-overlap` | `MGLSymbolStyleLayer.textAllowsOverlap` | `MGLSymbolStyleLayer.textAllowsOverlap` -`text-font` | `MGLSymbolStyleLayer.textFontNames` | `MGLSymbolStyleLayer.textFontNames` -`text-size` | `MGLSymbolStyleLayer.textFontSize` | `MGLSymbolStyleLayer.textFontSize` -`text-ignore-placement` | `MGLSymbolStyleLayer.textIgnoresPlacement` | `MGLSymbolStyleLayer.textIgnoresPlacement` -`text-justify` | `MGLSymbolStyleLayer.textJustification` | `MGLSymbolStyleLayer.textJustification` -`text-optional` | `MGLSymbolStyleLayer.textOptional` | `MGLSymbolStyleLayer.isTextOptional` -`text-rotate` | `MGLSymbolStyleLayer.textRotation` | `MGLSymbolStyleLayer.textRotation` -`text-writing-mode` | `MGLSymbolStyleLayer.textWritingModes` | `MGLSymbolStyleLayer.textWritingModes` -`icon-translate` | `MGLSymbolStyleLayer.iconTranslation` | `MGLSymbolStyleLayer.iconTranslation` -`icon-translate-anchor` | `MGLSymbolStyleLayer.iconTranslationAnchor` | `MGLSymbolStyleLayer.iconTranslationAnchor` -`text-translate` | `MGLSymbolStyleLayer.textTranslation` | `MGLSymbolStyleLayer.textTranslation` -`text-translate-anchor` | `MGLSymbolStyleLayer.textTranslationAnchor` | `MGLSymbolStyleLayer.textTranslationAnchor` - -## 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 | `NSColor` | `NSColor` -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]` -Array (`-offset`, `-translate`) | `NSValue` containing `CGVector` | `NSValue` containing `CGVector` -Array (`-padding`) | `NSValue.edgeInsetsValue` | `NSValue.edgeInsetsValue` - -For padding attributes, note that the arguments to -`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. - -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, 'NSColor')` -`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')` -`rgb` | `+[NSColor colorWithCalibratedRed:green:blue:alpha:]` | -`rgba` | `+[NSColor colorWithCalibratedRed: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/macos/docs/guides/Info.plist Keys.md b/platform/macos/docs/guides/Info.plist Keys.md deleted file mode 100644 index 35ecf67e36..0000000000 --- a/platform/macos/docs/guides/Info.plist Keys.md +++ /dev/null @@ -1,35 +0,0 @@ -# Info.plist Keys - -The Mapbox Maps SDK for macOS supports custom `Info.plist` keys in your application in order to configure various settings. - -## MGLMapboxAccessToken - -Set the [Mapbox access token](https://www.mapbox.com/help/define-access-token/) to be used by all instances of `MGLMapView` in the current application. - -Mapbox-hosted vector tiles and styles require an API access token, which you can obtain from the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). Access tokens associate requests to Mapbox’s vector tile and style APIs with your Mapbox account. They also deter other developers from using your styles without your permission. - -As an alternative, you can use `MGLAccountManager.accessToken` to set a token in code. See [our guide](https://www.mapbox.com/help/ios-private-access-token/) for some tips on keeping access tokens in open source code private. - -## MGLMapboxAPIBaseURL - -Use this key if you need to customize the API base URL used throughout the SDK. If unset, the default Mapbox API is used. - -The default value is `https://api.mapbox.com`. - -## MGLIdeographicFontFamilyName - -The name of the font family to use for client-side text rendering of CJK ideographs. - -Set `MGLIdeographicFontFamilyName` in your containing application's Info.plist to font family name(s) that will be available at run time, such as “PingFang TC” or “Marker Felt”. This plist key accepts: - -- A string value of a single font family name. - -- An array of font family names. Fonts will be used in the defined order, eventually falling back to default system font if none are available. - -- A boolean value `NO` to disable client-side rendering of CJK glyphs — remote fonts specified in your style will be used instead. - -## MGLCollisionBehaviorPre4_0 - -If this key is set to YES (`true`), collision detection is performed only between symbol style layers based on the same source, as in versions 0.1–0.7 of the Mapbox Maps SDK for iOS. In other words, symbols in an `MGLSymbolStyleLayer` based on one source (for example, an `MGLShapeSource`) may overlap with symbols in another layer that is based on a different source (such as the Mapbox Streets source). This is the case regardless of the `MGLSymbolStyleLayer.iconAllowsOverlap`, `MGLSymbolStyleLayer.iconIgnoresPlacement`, `MGLSymbolStyleLayer.textAllowsOverlap`, and `MGLSymbolStyleLayer.textIgnoresPlacement` properties. - -Beginning in version 0.7, the SDK also performs collision detection between style layers based on different sources by default. For the default behavior, omit the `MGLCollisionBehaviorPre4_0` key or set it to NO (`false`). This property is so named because version 0.7 of the Mapbox Maps SDK for macOS corresponds to version 4.0 of the Mapbox Maps SDK for iOS. diff --git a/platform/macos/docs/guides/Migrating to Expressions.md b/platform/macos/docs/guides/Migrating to Expressions.md deleted file mode 100644 index 44e14a6eec..0000000000 --- a/platform/macos/docs/guides/Migrating to Expressions.md +++ /dev/null @@ -1,267 +0,0 @@ -<!-- - 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 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 macOS 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: -```swift -let stops: [NSNumber: NSColor] = [ - 0: .yellow, - 2.5: .orange, - 5: .red, - 7.5: .blue, - 10: .white, -] -``` - - -## 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: - -```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: [NSNumber: NSColor] = [ - 0: .yellow, - 2.5: .orange, - 5: .red, - 7.5: .blue, - 10: .white, -] - -let layer = MGLCircleStyleLayer(identifier: "circles", source: source) -layer.circleColor = NSExpression(format: "mgl_interpolate:withCurveType:parameters:stops:(mag, 'linear', nil, %@)", - stops) -layer.circleRadius = NSExpression(forConstantValue: 10) -mapView.style?.insertLayer(layer, below: symbolLayer) -``` - -### 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: - -```swift -let stops = [ - 12: 0.5, - 14: 2, - 18: 18, -] - -layer.circleRadius = NSExpression(format: "mgl_interpolate:withCurveType:parameters:stops:($zoomLevel, 'exponential', 1.5, %@)", - stops) -``` - -### 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: - -```swift -let stops: [NSNumber: NSColor] = [ - 0: .yellow, - 2.5: .orange, - 5: .red, - 7.5: .blue, - 10: .white, -] - -layer.circleColor = NSExpression(format: "mgl_step:from:stops:(mag, %@, %@)", - NSColor.green, stops) -``` - -### 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: -```swift -let defaultColor = NSColor.blue -layer.circleColor = NSExpression( -format: "MGL_MATCH(type, 'earthquake', %@, 'explosion', %@, 'quarry blast', %@, %@)", - NSColor.orange, NSColor.red, NSColor.yellow, defaultColor) -``` - -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: -```swift -layer.circleRadius = NSExpression(forKeyPath: "mag") -``` - - - -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. - -```swift -layer.circleRadius = NSExpression(forFunction: "multiply:by:", arguments: [NSExpression(forKeyPath: "mag"), 3]) -``` - - - -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. - -```swift -let magnitudeLayer = MGLSymbolStyleLayer(identifier: "mag-layer", source: source) -magnitudeLayer.text = NSExpression(format: "CAST(mag, 'NSString')") -mapView.style?.addLayer(magnitudeLayer) -``` - - - -### 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/macos/docs/guides/Tile URL Templates.md b/platform/macos/docs/guides/Tile URL Templates.md deleted file mode 100644 index e71bcab0a4..0000000000 --- a/platform/macos/docs/guides/Tile URL Templates.md +++ /dev/null @@ -1,98 +0,0 @@ -<!-- - 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 - 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/macos/docs/img/screenshot.jpg b/platform/macos/docs/img/screenshot.jpg Binary files differdeleted file mode 100644 index 4af752b299..0000000000 --- a/platform/macos/docs/img/screenshot.jpg +++ /dev/null diff --git a/platform/macos/docs/pod-README.md b/platform/macos/docs/pod-README.md deleted file mode 100644 index 6fd0926443..0000000000 --- a/platform/macos/docs/pod-README.md +++ /dev/null @@ -1,98 +0,0 @@ -# [Mapbox Maps SDK for macOS](https://github.com/mapbox/mapbox-gl-native/tree/master/platform/macos/) - -Put interactive, scalable world maps into your native Cocoa application with the open-source Mapbox Maps SDK for macOS. - -* Mapbox-curated [map styles](https://www.mapbox.com/maps/) and [OpenStreetMap-based](https://www.mapbox.com/vector-tiles/mapbox-streets-v7/) [vector tiles](https://www.mapbox.com/vector-tiles/) make it easy to get started. -* Customize every aspect of the map’s appearance in code or visually using [Mapbox Studio](https://www.mapbox.com/mapbox-studio/). -* High-performance OpenGL rendering and multitouch gestures keep your users happy. -* A well-designed, fully documented API helps you stay productive. -* Develop across [multiple platforms](https://www.mapbox.com/maps/), including [iOS](https://docs.mapbox.com/ios/maps/), using the same styles and similar APIs. - - - -The Mapbox Maps SDK for macOS is compatible with macOS 10.11.0 and above for Cocoa applications developed in Objective-C, Swift, Interface Builder, or AppleScript. For hybrid applications, consider [Mapbox GL JS](https://www.mapbox.com/mapbox-gl-js/). - -## Installation - -There are three ways to install the Mapbox Maps SDK for macOS: - -### Manually - -1. Download the [latest Mapbox Maps SDK for macOS release](https://github.com/mapbox/mapbox-gl-native/releases/) from GitHub – look for a release that begins with “macos-”. - -1. Open the project editor, select your application target, then go to the General tab. Drag Mapbox.framework into the “Embedded Binaries” section. (Don’t drag it into the “Linked Frameworks and Libraries” section; Xcode will add it there automatically.) In the sheet that appears, make sure “Copy items if needed” is checked, then click Finish. - -### Via Carthage - -The Mapbox Maps SDK for macOS is a binary-only dependency, so you’ll need Carthage 0.19 or above. In your [Cartfile](https://github.com/Carthage/Carthage/blob/master/Documentation/Artifacts.md#binary-only-frameworks), specify this dependency (plus an optional version requirement): - -``` -binary "https://mapbox.github.io/mapbox-gl-native/macos/Mapbox-macOS-SDK.json" -``` - -After running `carthage update`, you’ll find Mapbox.framework in the Carthage/Build/ folder. Follow [these instructions](https://github.com/Carthage/Carthage#if-youre-building-for-os-x) to integrate it into your project. - -### Via CocoaPods - -Create a [Podfile](https://guides.cocoapods.org/syntax/podfile.html) with the following specification: - -```rb -platform :osx, '10.11' - -target 'TargetNameForYourApp' do - pod 'Mapbox-macOS-SDK', '~> x.y' -end -``` - -where _x.y_ is the current version. In Terminal, run `pod install`. - -## Usage - -Mapbox vector tiles require a Mapbox account and API access token. In the project editor, select the application target, then go to the Info tab. Under the “Custom macOS Application Target Properties” section, set `MGLMapboxAccessToken` to your access token. You can obtain an access token from the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). - -Then, in a storyboard or XIB: - -1. Add a view to your view controller or window. (Drag Custom View from the Object library to the View Controller scene on the Interface Builder canvas. In a XIB, drag it instead to the window on the canvas.) -2. In the Identity inspector, set the view’s custom class to `MGLMapView`. -3. MGLMapView needs to be layer-backed: - * You can make the window layer-backed by selecting the window and checking Full Size Content View in the Attributes inspector. This allows the map view to underlap the title bar and toolbar. - * Alternatively, if you don’t want the entire window to be layer-backed, you can make just the map view layer-backed by selecting it and checking its entry under the View Effects inspector’s Core Animation Layer section. -4. Add a map feedback item to your Help menu. (Drag Menu Item from the Object library into Main Menu ‣ Help ‣ Menu.) Title it “Improve This Map” or similar, and connect it to the `giveFeedback:` action of First Responder. - -If you need to manipulate the map view programmatically: - -1. Switch to the Assistant Editor. -1. Import the `Mapbox` module. -1. Connect the map view to a new outlet in your view controller class. (Control-drag from the map view in Interface Builder to a valid location in your view controller implementation.) The resulting outlet declaration should look something like this: - -```objc -// ViewController.m -@import Mapbox; - -@interface ViewController : NSViewController - -@property (strong) IBOutlet MGLMapView *mapView; - -@end -``` - -```swift -// ViewController.swift -import Mapbox - -class ViewController: NSViewController { - @IBOutlet var mapView: MGLMapView! -} -``` - -```applescript --- AppDelegate.applescript -script AppDelegate - property parent : class "NSObject" - property theMapView : missing value -end script -``` - -Full API documentation is included in this package, within the `documentation` folder, and [online](https://mapbox.github.io/mapbox-gl-native/macos/). The [Mapbox Maps SDK for iOS](https://docs.mapbox.com/ios/maps/) has [API documentation](https://docs.mapbox.com/ios/api/maps/) and [online examples](https://docs.mapbox.com/ios/maps/examples/) that apply to the Mapbox Maps SDK for macOS with few differences, mostly around unimplemented features like user location tracking. - -Mapbox does not officially support the macOS SDK to the same extent as the iOS SDK; however, [bug reports and pull requests](https://github.com/mapbox/mapbox-gl-native/issues/) are certainly welcome. |
