MGLStyle
@interface MGLStyle : NSObject
The proxy object for the current map style.
MGLStyle provides a set of convenience methods for changing Mapbox
default styles using -[MGLMapView styleURL]
.
Learn more about Mapbox default styles.
It is also possible to directly manipulate the current map style
via -[MGLMapView style]
by updating the style’s data sources or layers.
Note
Wait until the map style has finished loading before modifying a map’s style via any of theMGLStyle
instance methods below. You can use the
-[MGLMapViewDelegate mapView:didFinishLoadingStyle:]
or
-[MGLMapViewDelegate mapViewDidFinishLoadingMap:]
methods as indicators
that it’s safe to modify the map’s style.
-
Returns the URL to version 8 of the Mapbox Streets style.
Streets is a general-purpose style with detailed road and transit networks.
MGLMapView
andMGLTilePyramidOfflineRegion
use Mapbox Streets when no style is specified explicitly.Declaration
Objective-C
+ (nonnull NSURL *)streetsStyleURL;
Swift
class func streetsStyleURL() -> URL
-
Returns the URL to the given version of the Mapbox Streets style.
Streets is a general-purpose style with detailed road and transit networks.
MGLMapView
andMGLTilePyramidOfflineRegion
use Mapbox Streets when no style is specified explicitly.Declaration
Objective-C
+ (nonnull NSURL *)streetsStyleURLWithVersion:(NSInteger)version;
Swift
class func streetsStyleURL(withVersion version: Int) -> URL
Parameters
version
The style’s latest released version. As of publication, the current version is
9
. -
Returns the URL to version 8 of the Mapbox Emerald style.
Emerald is a tactile style with subtle textures and dramatic hillshading.
Declaration
Objective-C
+ (nonnull NSURL *)emeraldStyleURL;
Swift
class func emeraldStyleURL() -> URL
-
Returns the URL to the given version of the Mapbox Outdoors style.
Outdoors is a general-purpose style tailored to outdoor activities.
Declaration
Objective-C
+ (nonnull NSURL *)outdoorsStyleURLWithVersion:(NSInteger)version;
Swift
class func outdoorsStyleURL(withVersion version: Int) -> URL
Parameters
version
The style’s latest released version. As of publication, the current version is
9
. -
Returns the URL to version 8 of the Mapbox Light style.
Light is a subtle, light-colored backdrop for data visualizations.
Declaration
Objective-C
+ (nonnull NSURL *)lightStyleURL;
Swift
class func lightStyleURL() -> URL
-
Returns the URL to the given version of the Mapbox Light style.
Light is a subtle, light-colored backdrop for data visualizations.
Declaration
Objective-C
+ (nonnull NSURL *)lightStyleURLWithVersion:(NSInteger)version;
Swift
class func lightStyleURL(withVersion version: Int) -> URL
Parameters
version
The style’s latest released version. As of publication, the current version is
9
. -
Returns the URL to version 8 of the Mapbox Dark style.
Dark is a subtle, dark-colored backdrop for data visualizations.
Declaration
Objective-C
+ (nonnull NSURL *)darkStyleURL;
Swift
class func darkStyleURL() -> URL
-
Returns the URL to the given version of the Mapbox Dark style.
Dark is a subtle, dark-colored backdrop for data visualizations.
Declaration
Objective-C
+ (nonnull NSURL *)darkStyleURLWithVersion:(NSInteger)version;
Swift
class func darkStyleURL(withVersion version: Int) -> URL
Parameters
version
The style’s latest released version. As of publication, the current version is
9
. -
Returns the URL to version 8 of the Mapbox Satellite style.
Satellite is high-resolution satellite and aerial imagery.
Declaration
Objective-C
+ (nonnull NSURL *)satelliteStyleURL;
Swift
class func satelliteStyleURL() -> URL
-
Returns the URL to the given version of the Mapbox Satellite style.
Satellite is high-resolution satellite and aerial imagery.
Declaration
Objective-C
+ (nonnull NSURL *)satelliteStyleURLWithVersion:(NSInteger)version;
Swift
class func satelliteStyleURL(withVersion version: Int) -> URL
Parameters
version
The style’s latest released version. As of publication, the current version is
9
. -
Returns the URL to version 8 of the Mapbox Satellite Streets style.
Satellite Streets combines the high-resolution satellite and aerial imagery of Mapbox Satellite with unobtrusive labels and translucent roads from Mapbox Streets.
Declaration
Objective-C
+ (nonnull NSURL *)hybridStyleURL;
Swift
class func hybridStyleURL() -> URL
-
Returns the URL to the given version of the Mapbox Satellite Streets style.
Satellite Streets combines the high-resolution satellite and aerial imagery of Mapbox Satellite with unobtrusive labels and translucent roads from Mapbox Streets.
Declaration
Objective-C
+ (nonnull NSURL *)satelliteStreetsStyleURLWithVersion:(NSInteger)version;
Swift
class func satelliteStreetsStyleURL(withVersion version: Int) -> URL
Parameters
version
The style’s latest released version. As of publication, the current version is
9
.
-
The name of the style.
You can customize the style’s name in Mapbox Studio.
Declaration
Objective-C
@property (readonly, copy, atomic, nullable) NSString *name;
Swift
var name: String? { get }
-
A set containing the style’s sources.
Declaration
Objective-C
@property (readwrite, strong, nonatomic) NSSet<__kindof MGLSource *> *_Nonnull sources;
Swift
var sources: Set
-
Returns a source with the given identifier in the current style.
Note
Source identifiers are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like
+[MGLStyle outdoorsStyleURLWithVersion:]
,MGLMapView
’s “Style URL” inspectable in Interface Builder, or a manually constructedNSURL
. This approach also avoids source identifer name changes that will occur in the default style’s sources over time.Declaration
Objective-C
- (nullable MGLSource *)sourceWithIdentifier:(nonnull NSString *)identifier;
Swift
func source(withIdentifier identifier: String) -> MGLSource?
Return Value
An instance of a concrete subclass of
MGLSource
associated with the given identifier, ornil
if the current style contains no such source. -
Adds a new source to the current style.
Note
Adding the same source instance more than once will result in a
MGLRedundantSourceException
. Reusing the same source identifier, even with different source instances, will result in aMGLRedundantSourceIdentifierException
.Note
Sources should be added in
-[MGLMapViewDelegate mapView:didFinishLoadingStyle:]
or-[MGLMapViewDelegate mapViewDidFinishLoadingMap:]
to ensure that the map has loaded the style and is ready to accept a new source.Declaration
Objective-C
- (void)addSource:(nonnull MGLSource *)source;
Swift
func addSource(_ source: MGLSource)
Parameters
source
The source to add to the current style.
-
Removes a source from the current style.
Note
Source identifiers are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like
+[MGLStyle outdoorsStyleURLWithVersion:]
,MGLMapView
’s “Style URL” inspectable in Interface Builder, or a manually constructedNSURL
. This approach also avoids source identifer name changes that will occur in the default style’s sources over time.Declaration
Objective-C
- (void)removeSource:(nonnull MGLSource *)source;
Swift
func removeSource(_ source: MGLSource)
Parameters
source
The source to remove from the current style.
-
The layers included in the style, arranged according to their back-to-front ordering on the screen.
Declaration
Objective-C
@property (readwrite, strong, nonatomic) NSArray<__kindof MGLStyleLayer *> *_Nonnull layers;
Swift
var layers: [MGLStyleLayer] { get set }
-
Returns a style layer with the given identifier in the current style.
Note
Layer identifiers are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like
+[MGLStyle outdoorsStyleURLWithVersion:]
,MGLMapView
’s “Style URL” inspectable in Interface Builder, or a manually constructedNSURL
. This approach also avoids layer identifer name changes that will occur in the default style’s layers over time.Declaration
Objective-C
- (nullable MGLStyleLayer *)layerWithIdentifier:(nonnull NSString *)identifier;
Swift
func layer(withIdentifier identifier: String) -> MGLStyleLayer?
Return Value
An instance of a concrete subclass of
MGLStyleLayer
associated with the given identifier, ornil
if the current style contains no such style layer. -
Adds a new layer on top of existing layers.
Note
Adding the same layer instance more than once will result in a
MGLRedundantLayerException
. Reusing the same layer identifer, even with different layer instances, will also result in an exception.Note
Layers should be added in
-[MGLMapViewDelegate mapView:didFinishLoadingStyle:]
or-[MGLMapViewDelegate mapViewDidFinishLoadingMap:]
to ensure that the map has loaded the style and is ready to accept a new layer.Declaration
Objective-C
- (void)addLayer:(nonnull MGLStyleLayer *)layer;
Swift
func addLayer(_ layer: MGLStyleLayer)
Parameters
layer
The layer object to add to the map view. This object must be an instance of a concrete subclass of
MGLStyleLayer
. -
Inserts a new layer into the style at the given index.
Note
Adding the same layer instance more than once will result in a
MGLRedundantLayerException
. Reusing the same layer identifer, even with different layer instances, will also result in an exception.Note
Layers should be added in
-[MGLMapViewDelegate mapView:didFinishLoadingStyle:]
or-[MGLMapViewDelegate mapViewDidFinishLoadingMap:]
to ensure that the map has loaded the style and is ready to accept a new layer.Declaration
Objective-C
- (void)insertLayer:(nonnull MGLStyleLayer *)layer atIndex:(NSUInteger)index;
Swift
func insertLayer(_ layer: MGLStyleLayer, at index: UInt)
Parameters
layer
The layer to insert.
index
The index at which to insert the layer. An index of 0 would send the layer to the back; an index equal to the number of objects in the
layers
property would bring the layer to the front. -
Inserts a new layer below another layer.
Note
Layer identifiers are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like+[MGLStyle outdoorsStyleURLWithVersion:]
,MGLMapView
’s “Style URL” inspectable in Interface Builder, or a manually constructedNSURL
. This approach also avoids layer identifer name changes that will occur in the default style’s layers over time.Inserting the same layer instance more than once will result in a
MGLRedundantLayerException
. Reusing the same layer identifer, even with different layer instances, will also result in an exception.Declaration
Objective-C
- (void)insertLayer:(nonnull MGLStyleLayer *)layer belowLayer:(nonnull MGLStyleLayer *)sibling;
Swift
func insertLayer(_ layer: MGLStyleLayer, below sibling: MGLStyleLayer)
Parameters
layer
The layer to insert.
sibling
An existing layer in the style.
-
Inserts a new layer above another layer.
Note
Layer identifiers are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like+[MGLStyle outdoorsStyleURLWithVersion:]
,MGLMapView
’s “Style URL” inspectable in Interface Builder, or a manually constructedNSURL
. This approach also avoids layer identifer name changes that will occur in the default style’s layers over time.Inserting the same layer instance more than once will result in a
MGLRedundantLayerException
. Reusing the same layer identifer, even with different layer instances, will also result in an exception.Declaration
Objective-C
- (void)insertLayer:(nonnull MGLStyleLayer *)layer aboveLayer:(nonnull MGLStyleLayer *)sibling;
Swift
func insertLayer(_ layer: MGLStyleLayer, above sibling: MGLStyleLayer)
Parameters
layer
The layer to insert.
sibling
An existing layer in the style.
-
Removes a layer from the map view.
Note
Layer identifiers are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like
+[MGLStyle outdoorsStyleURLWithVersion:]
,MGLMapView
’s “Style URL” inspectable in Interface Builder, or a manually constructedNSURL
. This approach also avoids layer identifer name changes that will occur in the default style’s layers over time.Declaration
Objective-C
- (void)removeLayer:(nonnull MGLStyleLayer *)layer;
Swift
func removeLayer(_ layer: MGLStyleLayer)
Parameters
layer
The layer object to remove from the map view. This object must conform to the
MGLStyleLayer
protocol.
-
Currently active style classes, represented as an array of string identifiers.
Declaration
Objective-C
@property (assign, readwrite, nonatomic) NSArray<NSString *> *_Nonnull styleClasses;
Swift
var styleClasses: [String] { get set }
-
Returns a Boolean value indicating whether the style class with the given identifier is currently active.
Declaration
Objective-C
- (BOOL)hasStyleClass:(nonnull NSString *)styleClass;
Swift
func hasStyleClass(_ styleClass: String) -> Bool
Parameters
styleClass
The style class to query for.
Return Value
Whether the style class is currently active.
-
Activates the style class with the given identifier.
Declaration
Objective-C
- (void)addStyleClass:(nonnull NSString *)styleClass;
Swift
func addClass(_ styleClass: String)
Parameters
styleClass
The style class to activate.
-
Deactivates the style class with the given identifier.
Note
Style class names are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like
+[MGLStyle outdoorsStyleURLWithVersion:]
,MGLMapView
’s “Style URL” inspectable in Interface Builder, or a manually constructedNSURL
. This approach also avoids style class name changes that will occur in the default style over time.Declaration
Objective-C
- (void)removeStyleClass:(nonnull NSString *)styleClass;
Swift
func removeStyleClass(_ styleClass: String)
Parameters
styleClass
The style class to deactivate.
-
Returns the image associated with the given name in the style.
Note
Names and their associated images are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like
+[MGLStyle outdoorsStyleURLWithVersion:]
,MGLMapView
’s “Style URL” inspectable in Interface Builder, or a manually constructedNSURL
. This approach also avoids image name changes that will occur in the default style over time.Declaration
Objective-C
- (nullable UIImage *)imageForName:(nonnull NSString *)name;
Swift
func image(forName name: String) -> NSImage?
Parameters
name
The name associated with the image you want to obtain.
Return Value
The image associated with the given name, or
nil
if no image is associated with that name. -
Adds or overrides an image used by the style’s layers.
To use an image in a style layer, give it a unique name using this method, then set the
iconImageName
property of anMGLSymbolStyleLayer
object to that name.Declaration
Objective-C
- (void)setImage:(nonnull UIImage *)image forName:(nonnull NSString *)name;
Swift
func setImage(_ image: NSImage, forName name: String)
Parameters
image
The image for the name.
name
The name of the image to set to the style.
-
Removes a name and its associated image from the style.
Note
Names and their associated images are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like
+[MGLStyle outdoorsStyleURLWithVersion:]
,MGLMapView
’s “Style URL” inspectable in Interface Builder, or a manually constructedNSURL
. This approach also avoids image name changes that will occur in the default style over time.Declaration
Objective-C
- (void)removeImageForName:(nonnull NSString *)name;
Swift
func removeImage(forName name: String)
Parameters
name
The name of the image to remove.
-
The duration in seconds to animate any changes to the style URL or to layout and paint attributes.
By default, this property is set to zero seconds, so any changes take effect without animation.
Declaration
Objective-C
@property (assign, readwrite, nonatomic) NSTimeInterval transitionDuration;
Swift
var transitionDuration: TimeInterval { get set }
-
The delay in seconds to before applying any changes to the style URL or to layout and paint attributes.
By default, this property is set to zero seconds, so any changes begin to animate immediately.
Declaration
Objective-C
@property (assign, readwrite, nonatomic) NSTimeInterval transitionDelay;
Swift
var transitionDelay: TimeInterval { get set }