Mapbox Maps SDK for macOS
Put interactive, scalable world maps into your native Cocoa application with the open-source Mapbox Maps SDK for macOS.
- Mapbox-curated map styles and OpenStreetMap-based vector tiles make it easy to get started.
- Customize every aspect of the map’s appearance in code or visually using 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, including iOS, 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.
Installation
There are three ways to install the Mapbox Maps SDK for macOS:
Manually
Download the latest Mapbox Maps SDK for macOS release from GitHub – look for a release that begins with “macos-”.
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, 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 to integrate it into your project.
Via CocoaPods
Create a Podfile with the following specification:
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.
Then, in a storyboard or XIB:
- 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.)
- In the Identity inspector, set the view’s custom class to
MGLMapView
. - 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.
- 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:
- Switch to the Assistant Editor.
- Import the
Mapbox
module. - 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:
// ViewController.m
@import Mapbox;
@interface ViewController : NSViewController
@property (strong) IBOutlet MGLMapView *mapView;
@end
// ViewController.swift
import Mapbox
class ViewController: NSViewController {
@IBOutlet var mapView: MGLMapView!
}
-- 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. The Mapbox Maps SDK for iOS has API documentation and online 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 are certainly welcome.
Changes in version 0.12.0
Styles and rendering
MGLSymbolStyleLayer.text
can now be set to rich text with varying fonts and text sizes. (#12624)- Added an
MGLSymbolStyleLayer.symbolZOrder
property for forcing point features in a symbol layer to be layered in the same order that they are specified in the layer’s associated source. (#12783) - Fixed a crash when the
MGLBackgroundStyleLayer.backgroundPattern
,MGLFillExtrusionStyleLayer.fillExtrusionPattern
,MGLFillStyleLayer.fillPattern
, orMGLLineStyleLayer.linePattern
property evaluates tonil
for a particular feature. (#12896) - Fixed a crash when using the
MGL_LET
,MGL_MATCH
,MGL_IF
, orMGL_FUNCTION
functions without a colon inside anNSExpression
orNSPredicate
format string. (#13189) - Fixed a crash setting the
MGLLineStyleLayer.lineGradient
property to an expression containing the$lineProgress
variable. Added anNSExpression.lineProgressVariableExpression
class property that returns an expression for the$lineProgress
variable. (#13192) - Fixed an issue where features in
MGLFillStyleLayer
andMGLLineStyleLayer
would occasionally flicker when zooming in and out. (#12982) - Feature querying can now return point features represented by icons that have both the
MGLSymbolStyleLayer.iconRotation
andMGLSymbolStyleLayer.iconOffset
properties applied. (#13105) - Fixed a crash when casting an
NSColor
to anNSColor
inside anNSExpression
. (#12864) NIL
cast to anNSNumber
now evaluates to 0 inside anNSExpression
. (#12864)- Fixed a crash when applying the
to-array
operator to an empty array inside a JSON expression. (#12864) - Added the
MGLCollisionBehaviorPre4_0
Info.plist key to restore the collision detection behavior in version 0.6 of the SDK. (#12941)
Offline maps
- Network requests by
MGLMapView
are now prioritized over offline pack downloads. (#13019) - Added
-[MGLOfflineStorage addContentsOfFile:withCompletionHandler:]
and-[MGLOfflineStorage addContentsOfURL:withCompletionHandler:]
methods to add pregenerated offline packs to offline storage. (#12791) - Added the
-[MGLOfflineStorage putResourceWithUrl:data:modified:expires:etag:mustRevalidate:]
method to allow pre-warming of the ambient cache. (#13119) - Fixed an issue where some tiles were rendered incorrectly when the device was unable to connect to the Internet. (#12931)
Other changes
- Added
MGLAltitudeForZoomLevel()
andMGLZoomLevelForAltitude()
methods for converting between zoom levels used byMGLMapView
and altitudes used byMGLMapCamera
. (#12986) - Deprecated the
+[MGLMapCamera cameraLookingAtCenterCoordinate:fromDistance:pitch:heading:]
method in favor of+[MGLMapCamera cameraLookingAtCenterCoordinate:altitude:pitch:heading:]
and+[MGLMapCamera cameraLookingAtCenterCoordinate:acrossDistance:pitch:heading:]
. (#12966) - Fixed an issue where
+[MGLMapCamera cameraLookingAtCenterCoordinate:fromEyeCoordinate:eyeAltitude:]
created a camera looking from the wrong eye coordinate. (#12966) - Added an
MGLMapCamera.viewingDistance
property based on the existingMGLMapCamera.altitude
property. (#12966) - Fixed an issue where the map view could not be panned after setting
MGLMapView.visibleCoordinateBounds
to a coordinate bounds that spanned exactly the longitudes −180° and 180°. (#13006) - Fixed an issue where
-[MGLMapSnapshotter startWithQueue:completionHandler:]
failed to call its completion handler in some cases. (#12355) - Fixed an issue where snapshots had the wrong heading and pitch. (#13123)
- Fixed an issue where
MGLMapView
produced a designable error in Interface Builder storyboards in Xcode 10. (#12883)