MBMMapEvents

 

@interface MBMMapEvents : NSObject

List of supported event types by the Map and MapSnapshotter objects, and event data format specification for each event.

Simplified diagram for events emitted by the Map object.

┌─────────────┐ ┌─────────┐ ┌──────────────┐ │ Application │ │ Map │ │ResourceLoader│ └──────┬──────┘ └────┬────┘ └───────┬──────┘ │ │ │ ├───────setStyleURI────────▶│ │ │ ├───────────get style───────────▶│ │ │ │ │ │◀─────────style data────────────┤ │ │ │ │ ├─parse style─┐ │ │ │ │ │ │ StyleDataLoaded ◀─────────────┘ │ │◀────{“type”: “style”}─────┤ │ │ ├─────────get sprite────────────▶│ │ │ │ │ │◀────────sprite data────────────┤ │ │ │ │ ├──────parse sprite───────┐ │ │ │ │ │ │ StyleDataLoaded ◀─────────────────────────┘ │ │◀───{“type”: “sprite”}─────┤ │ │ ├─────get source TileJSON(s)────▶│ │ │ │ │ SourceDataLoaded │◀─────parse TileJSON data───────┤ │◀──{“type”: “metadata”}────┤ │ │ │ │ │ │ │ │ StyleDataLoaded │ │ │◀───{“type”: “sources”}────┤ │ │ ├──────────get tiles────────────▶│ │ │ │ │◀───────StyleLoaded────────┤ │ │ │ │ │ SourceDataLoaded │◀─────────tile data─────────────┤ │◀────{“type”: “tile”}──────┤ │ │ │ │ │ │ │ │◀────RenderFrameStarted────┤ │ │ ├─────render─────┐ │ │ │ │ │ │ ◀────────────────┘ │ │◀───RenderFrameFinished────┤ │ │ ├──render, all tiles loaded──┐ │ │ │ │ │ │ ◀────────────────────────────┘ │ │◀────────MapLoaded─────────┤ │ │ │ │ │ │ │ │◀─────────MapIdle──────────┤ │ │ ┌ ─── ─┴─ ─── ┐ │ │ │ offline │ │ │ └ ─── ─┬─ ─── ┘ │ │ │ │ ├─────────setCamera────────▶│ │ │ ├───────────get tiles───────────▶│ │ │ │ │ │┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │◀─────────MapIdle──────────┤ waiting for connectivity │ │ │ ││ Map renders cached data │ │ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ │ │ │ │

  • The Map’s style has been fully loaded, and the Map has rendered all visible tiles.

    Event data format (Object).

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSString *MapLoaded;

    Swift

    class var mapLoaded: String! { get }

  • Describes an error that has occured while loading the Map. The ‘type’ property defines what resource could not be loaded and the ‘message’ property will contain a descriptive error message.

    Event data format (Object): . ├── type - String (“style” | “sprite” | “source” | “tile” | “glyphs”) └── message - String

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSString *MapLoadingError;

    Swift

    class var mapLoadingError: String! { get }

  • The Map has entered the idle state. The Map is in the idle state when there are no ongoing transitions and the Map has rendered all available tiles. The event will not be emitted if Map#setUserAnimationInProgress and / or Map#setGestureInProgress is set to true.

    Event data format (Object).

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSString *MapIdle;

    Swift

    class var mapIdle: String! { get }

  • The requested style data has been loaded. The ‘type’ property defines what kind of style data has been loaded. Event may be emitted synchronously, for example, when StyleManager#setStyleJSON is used to load style.

    Based on an event data ‘type’ property value, following use-cases may be implemented:

    • ‘style’: Style is parsed, style layer properties could be read and modified, style layers and sources could be added or removed before rendering is started.
    • ‘sprite’: Style’s sprite sheet is parsed and it is possible to add or update images.
    • ‘sources’: All sources defined by the style are loaded and their properties could be read and updated if needed.

    Event data format (Object): . └── type - String (“style” | “sprite” | “sources”)

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSString *StyleDataLoaded;

    Swift

    class var styleDataLoaded: String! { get }

  • The requested style has been fully loaded, including the style, specified sprite and sources’ metadata.

    Event data format (Object).

    Note: The style specified sprite would be marked as loaded even with sprite loading error (An error will be emitted via \link MapEvents: MapLoadingError \endlink). Sprite loading error is not fatal and we don’t want it to block the map rendering, thus this event will still be emitted if style and sources are fully loaded.

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSString *StyleLoaded;

    Swift

    class var styleLoaded: String! { get }

  • A style has a missing image. This event is emitted when the Map renders visible tiles and one of the required images is missing in the sprite sheet. Subscriber has to provide the missing image by calling StyleManager#addStyleImage method.

    Event data format (Object): . └── id - String

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSString *StyleImageMissing;

    Swift

    class var styleImageMissing: String! { get }

  • An image added to the Style is no longer needed and can be removed using StyleManager#removeStyleImage method.

    Event data format (Object): . └── id - String

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSString *StyleImageRemoveUnused;

    Swift

    class var styleImageRemoveUnused: String! { get }

  • Source data has been loaded. Event may be emitted synchronously in cases when source’s metadata is available when source is added to the style.

    The ‘id’ property defines the source id.

    The ‘type’ property defines if source’s metadata (e.g., TileJSON) or tile has been loaded. The property of ‘metadata’ value might be useful to identify when particular source’s metadata is loaded, thus all source’s properties are readable and can be updated before map will start requesting data to be rendered.

    The ‘loaded’ property will be set to ‘true’ if all source’s data required for Map’s visible viewport, are loaded. The ‘tile-id’ property defines the tile id if the ‘type’ field equals ‘tile’.

    Event data format (Object): . ├── id - String ├── type - String (“metadata” | “tile”) ├── loaded - optional Boolean └── tile-id optional Object ├── z Number (zoom level) ├── x Number (x coorinate) └── y Number (y coorinate)

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSString *SourceDataLoaded;

    Swift

    class var sourceDataLoaded: String! { get }

  • Source has been added with StyleManager#addStyleSource runtime API. The event is emitted synchronously, therefore, it is possible to immediately read added source’s properties.

    Event data format (Object): . └── id - String

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSString *SourceAdded;

    Swift

    class var sourceAdded: String! { get }

  • Source has been removed with StyleManager#removeStyleSource runtime API. The event is emitted synchronously, thus, StyleManager#getStyleSources will be in sync when the Observer receives notification.

    Event data format (Object): . └── id - String

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSString *SourceRemoved;

    Swift

    class var sourceRemoved: String! { get }

  • The Map started rendering a frame.

    Event data format (Object).

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSString *RenderFrameStarted;

    Swift

    class var renderFrameStarted: String! { get }

  • The Map finished rendering a frame. The ‘render-mode’ property tells whether the Map has all data (“full”) required to render the visible viewport. The ‘needs-repaint’ property provides information about ongoing transitions that trigger Map repaint. The ‘placement-changed’ property tells if the symbol placement has been changed in the visible viewport.

    Event data format (Object): . ├── render-mode - String (“partial” | “full”) ├── needs-repaint - Boolean └── placement-changed - Boolean

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSString *RenderFrameFinished;

    Swift

    class var renderFrameFinished: String! { get }

  • Camera has changed. This event is emitted whenever the visible viewport changes due to the invocation of Map#setSize, Map#setBounds methods or when the camera is modified by calling Map camera methods. The event is emitted synchronously, so that an updated camera state can be fetched immediately.

    Event data format (Object).

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSString *CameraChanged;

    Swift

    class var cameraChanged: String! { get }

  • ResourceRequest event allows client to observe resource requests made by a Map or MapSnapshotter objects.

    Event data format (Object): . ├── data-source - String (“resource-loader” | “network” | “database” | “asset” | “file-system”) ├── request - Object │ ├── url - String │ ├── kind - String (“unknown” | “style” | “source” | “tile” | “glyphs” | “sprite-image” | “sprite-json” | “image”) │ ├── priority - String (“regular” | “low”) │ └── loading-method - Array [“cache” | “network”] ├── response - optional Object │ ├── no-content - Boolean │ ├── not-modified - Boolean │ ├── must-revalidate - Boolean │ ├── source - String (“network” | “cache” | “tile-store” | “local-file”) │ ├── size - Number (size in bytes) │ ├── modified - optional String, rfc1123 timestamp │ ├── expires - optional String, rfc1123 timestamp │ ├── etag - optional String │ └── error - optional Object │ ├── reason - String (“success” | “not-found” | “server” | “connection” | “rate-limit” | “other”) │ └── message - String └── cancelled - Boolean

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSString *ResourceRequest;

    Swift

    class var resourceRequest: String! { get }