DingiStyle

 

@interface DingiStyle : NSObject

The proxy object for the current map style.

DingiStyle provides a set of convenience methods for changing Mapbox default styles using -[DingiMapView styleURL]. Learn more about Mapbox default styles.

It is also possible to directly manipulate the current map style via -[DingiMapView 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 the DingiStyle instance methods below. You can use the -[DingiMapViewDelegate mapView:didFinishLoadingStyle:] or -[DingiMapViewDelegate mapViewDidFinishLoadingMap:] methods as indicators that it’s safe to modify the map’s style.

Accessing Default Styles

  • Returns the URL to the current version of the Mapbox Streets style as of publication.

    Streets is a general-purpose style with detailed road and transit networks.

    DingiMapView and DingiTilePyramidOfflineRegion use Mapbox Streets when no style is specified explicitly.

    Warning

    The return value may change in a future release of the SDK. If you use any feature that depends on a specific aspect of a default style – for instance, the minimum zoom level that includes roads – use the -streetsStyleURLWithVersion: method instead. Such details may change significantly from version to version.

    Declaration

    Objective-C

    @property (readonly, nonatomic, class) NSURL *_Nonnull englishStyleURL;

    Swift

    class var englishStyleURL: URL { get }

  • Returns the URL to the given version of the Mapbox Streets style.

    Streets is a general-purpose style with detailed road and transit networks.

    DingiMapView and DingiTilePyramidOfflineRegion use Mapbox Streets when no style is specified explicitly.

    Declaration

    Objective-C

    + (nonnull NSURL *)englishStyleURLWithVersion:(NSInteger)version;

    Swift

    class func englishStyleURL(withVersion version: Int) -> URL

    Parameters

    version

    A specific version of the style.

  • Returns the URL to the current version of the Mapbox Outdoors style as of publication.

    Outdoors is a general-purpose style tailored to outdoor activities.

    Warning

    The return value may change in a future release of the SDK. If you use any feature that depends on a specific aspect of a default style – for instance, the minimum zoom level that includes roads – use the -outdoorsStyleURLWithVersion: method instead. Such details may change significantly from version to version.

    Declaration

    Objective-C

    @property (readonly, nonatomic, class) NSURL *_Nonnull banglaStyleURL;

    Swift

    class var banglaStyleURL: URL { get }

  • 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 *)banglaStyleURLWithVersion:(NSInteger)version;

    Swift

    class func banglaStyleURL(withVersion version: Int) -> URL

    Parameters

    version

    A specific version of the style.

Accessing Metadata About the Style

  • 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 }

Managing Sources

  • A set containing the style’s sources.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic)
    NSSet<__kindof DingiSource *> *_Nonnull sources;

    Swift

    var sources: Set<AnyHashable> { get set }

  • Values describing animated transitions to changes on a style’s individual paint properties.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) DingiTransition transition;

    Swift

    var transition: DingiTransition { get 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 +[DingiStyle outdoorsStyleURLWithVersion:], DingiMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. This approach also avoids source identifer name changes that will occur in the default style’s sources over time.

    Declaration

    Objective-C

    - (nullable DingiSource *)sourceWithIdentifier:(nonnull NSString *)identifier;

    Swift

    func source(withIdentifier identifier: String) -> DingiSource?

    Return Value

    An instance of a concrete subclass of DingiSource associated with the given identifier, or nil 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 a MGLRedundantSourceIdentifierException.

    Note

    Sources should be added in -[DingiMapViewDelegate mapView:didFinishLoadingStyle:] or -[DingiMapViewDelegate mapViewDidFinishLoadingMap:] to ensure that the map has loaded the style and is ready to accept a new source.

    Declaration

    Objective-C

    - (void)addSource:(nonnull DingiSource *)source;

    Swift

    func addSource(_ source: DingiSource)

    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 +[DingiStyle outdoorsStyleURLWithVersion:], DingiMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. 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 DingiSource *)source;

    Swift

    func removeSource(_ source: DingiSource)

    Parameters

    source

    The source to remove from the current style.

Managing Style Layers

  • 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 DingiStyleLayer *> *_Nonnull layers;

    Swift

    var layers: [DingiStyleLayer] { 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 +[DingiStyle outdoorsStyleURLWithVersion:], DingiMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. This approach also avoids layer identifer name changes that will occur in the default style’s layers over time.

    Declaration

    Objective-C

    - (nullable DingiStyleLayer *)layerWithIdentifier:
    (nonnull NSString *)identifier;

    Swift

    func layer(withIdentifier identifier: String) -> DingiStyleLayer?

    Return Value

    An instance of a concrete subclass of DingiStyleLayer associated with the given identifier, or nil 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 -[DingiMapViewDelegate mapView:didFinishLoadingStyle:] or -[DingiMapViewDelegate mapViewDidFinishLoadingMap:] to ensure that the map has loaded the style and is ready to accept a new layer.

    Declaration

    Objective-C

    - (void)addLayer:(nonnull DingiStyleLayer *)layer;

    Swift

    func addLayer(_ layer: DingiStyleLayer)

    Parameters

    layer

    The layer object to add to the map view. This object must be an instance of a concrete subclass of DingiStyleLayer.

  • 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 -[DingiMapViewDelegate mapView:didFinishLoadingStyle:] or -[DingiMapViewDelegate mapViewDidFinishLoadingMap:] to ensure that the map has loaded the style and is ready to accept a new layer.

    Declaration

    Objective-C

    - (void)insertLayer:(nonnull DingiStyleLayer *)layer atIndex:(NSUInteger)index;

    Swift

    func insertLayer(_ layer: DingiStyleLayer, 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 +[DingiStyle outdoorsStyleURLWithVersion:], DingiMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. 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 DingiStyleLayer *)layer
         belowLayer:(nonnull DingiStyleLayer *)sibling;

    Swift

    func insertLayer(_ layer: DingiStyleLayer, below sibling: DingiStyleLayer)

    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 +[DingiStyle outdoorsStyleURLWithVersion:], DingiMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. 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 DingiStyleLayer *)layer
         aboveLayer:(nonnull DingiStyleLayer *)sibling;

    Swift

    func insertLayer(_ layer: DingiStyleLayer, above sibling: DingiStyleLayer)

    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 +[DingiStyle outdoorsStyleURLWithVersion:], DingiMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. 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 DingiStyleLayer *)layer;

    Swift

    func removeLayer(_ layer: DingiStyleLayer)

    Parameters

    layer

    The layer object to remove from the map view. This object must conform to the DingiStyleLayer protocol.

Managing a Style’s Images

  • 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 +[DingiStyle outdoorsStyleURLWithVersion:], DingiMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. 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) -> UIImage?

    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 an DingiSymbolStyleLayer object to that name.

    Declaration

    Objective-C

    - (void)setImage:(nonnull UIImage *)image forName:(nonnull NSString *)name;

    Swift

    func setImage(_ image: UIImage, 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 +[DingiStyle outdoorsStyleURLWithVersion:], DingiMapView’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL. 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.

Managing the Style's Light

  • Provides global light source for the style.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) DingiLight *_Nonnull light;

    Swift

    var light: DingiLight { get set }

Localizing Map Content

  • Attempts to localize labels in the style into the given locale.

    This method automatically modifies the text property of any symbol style layer in the style whose source is the Mapbox Streets source. On iOS, the user can set the system’s preferred language in Settings, General Settings, Language & Region. On macOS, the user can set the system’s preferred language in the Language & Region pane of System Preferences.

    Declaration

    Objective-C

    - (void)localizeLabelsIntoLocale:(nullable NSLocale *)locale;

    Swift

    func localizeLabels(into locale: Locale?)

    Parameters

    locale

    The locale into which labels should be localized. To use the system’s preferred language, if supported, specify nil. To use the local language, specify a locale with the identifier mul.