Install in Dash
For Style Authors Reference
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 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 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.
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. This
SDK supports the functionality defined by version 8 of the specification unless
otherwise noted in the
style specification documentation.
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
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,
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
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,
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” 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') |
in |
NSInPredicateOperatorType |
needle IN haystack or haystack CONTAINS needle or ANY haystack = needle |
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') |
within |
NSInPredicateOperatorType |
SELF IN %@ or %@ CONTAINS SELF where %@ is an MGLShape |
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) |
distance |
mgl_distanceFrom(%@) where %@ is an MGLShape |
|
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” guide for a full description of the supported operators and operand types.