@nativescript-community/ui-mapbox 6.2.15 → 6.2.20

package/index.android.d.ts

@@ -1,21 +1,102 @@
+/**
+ * Android Implementation
+ *
+ * @todo FIXME: The gcFix() implementation currently assumes only one map visible at a time.
+ */
 import { ImageSource } from '@nativescript/core';
 import { AddExtrusionOptions, AddGeoJsonClusteredOptions, AddPolygonOptions, AddPolylineOptions, AddSourceOptions, AnimateCameraOptions, DeleteOfflineRegionOptions, DownloadOfflineRegionOptions, Feature, LatLng, LayerCommon, ListOfflineRegionsOptions, MapStyle, MapboxApi, MapboxCommon, MapboxMarker, MapboxViewBase, OfflineRegion, QueryRenderedFeaturesOptions, QuerySourceFeaturesOptions, SetCenterOptions, SetTiltOptions, SetViewportOptions, SetZoomLevelOptions, ShowOptions, TrackUserOptions, UpdateSourceOptions, UserLocation, UserLocationCameraMode, Viewport } from './common';
 export * from './common';
 export declare function setLogLevel(level: 'none' | 'info' | 'debug' | 'error' | 'fault' | 'verbose'): void;
+/**
+ * A map view created in XML.
+ *
+ * This is the class that is created when the Mapbox XML tag
+ * is encountered while parsing a view.
+ *
+ * Angular components need to register the Mapbox tag as follows:
+ *
+ * import { registerElement } from "nativescript-angular/element-registry";
+ * registerElement( "Mapbox", () => require("nativescript-mapbox").MapboxView);
+ *
+ * The registerElement call is what binds the XML tag to the class that creates it.
+ *
+ * @see MapboxViewBase
+ */
 export declare class MapboxView extends MapboxViewBase {
     private nativeMapView;
     private settings;
     private initialized;
     constructor();
+    /**
+     * programmatically include settings
+     */
     setConfig(settings: any): void;
     getNativeMapView(): any;
+    /**
+     * Return the Mapbox() API Shim instance
+     *
+     * This returns a reference to the Mapbox API shim class instance.
+     * See class Mapbox below.
+     *
+     * @see Mapbox
+     */
     getMapboxApi(): any;
+    /**
+     * Creates the native view.
+     *
+     * This method is supposed to create the native view. NativeScript caches
+     * and re-uses views to save on memory and increase performance. Unfortunately,
+     * the inner details of exactly how this is done is challenging to tease apart.
+     *
+     * The problem is that in order to create the Mapbox view we need the access token from
+     * the XML, but in the case of a pure NativeScript app with property binding
+     * (see the demo), the properties don't seem to be available until the page is loaded.
+     *
+     * As a workaround, I wait until the page is loaded to configure the map. See initNativeView.
+     *
+     * It seems to me there should be a better way.
+     *
+     * @link https://docs.nativescript.org/core-concepts/properties#views-lifecycle-and-recycling
+     *
+     * @todo check this.
+     */
     createNativeView(): Object;
     onLoaded(): void;
     initNativeView(): void;
+    /**
+     * when the view is destroyed.
+     *
+     * This is called by the framework when the view is actually destroyed.
+     * NativeScript, by design, tries to cache native views because
+     * creating native views is expensive.
+     *
+     * @link https://docs.nativescript.org/plugins/ui-plugin-custom
+     */
     disposeNativeView(): void;
+    /**
+     * initialize the map
+     *
+     * This method creates a new mapbox API instance and, through the show() method of the Mapbox API,
+     * creates a Mapbox native map view.
+     *
+     * @see show()
+     *
+     * @link https://docs.nativescript.org/core-concepts/events
+     *
+     * @todo FIXME: this.nativeMapView is unused and never actually set to anything.
+     */
     private initMap;
 }
+/**
+ * A NativeScript shim for the Mapbox API.
+ *
+ * This implements a Typescript shim over the Native Mapbox GL Android API.
+ *
+ * It is created in one of two ways:
+ *
+ * - directly via let mapbox = new Mapbox(); mapbox.show( ... )
+ * - via the Mapbox XML tag in which case a MapboxView object is created which hosts a reference to this class. (See MapboxView::getMapboxAPI())
+ */
 export declare class Mapbox extends MapboxCommon implements MapboxApi {
     private _mapboxMapInstance;
     private _mapboxViewInstance;
@@ -49,11 +130,49 @@ export declare class Mapbox extends MapboxCommon implements MapboxApi {
     private eventCallbacks;
     _markerIconDownloadCache: any[];
     constructor(view: any);
+    /**
+     * not used
+     */
     setMapboxViewInstance(mapboxViewInstance: any): void;
+    /**
+     * show the map programmatically.
+     *
+     * This method is used to programmatically display a map. It is also called
+     * by the MapboxView::init() method which initializes the map when the Mapbox
+     * XML tags is encountered
+     *
+     * options may additionally include:
+     *
+     * - context
+     * - parentView
+     * - onLocationPermissionGranted
+     * - onLocationPermissionDenied
+     * - onMapReady
+     *
+     * @see MapboxView::init()
+     *
+     * @todo FIXME: the timeout delay before showing the map works around some race condition. The source error needs to be figured out.
+     */
     show(options: ShowOptions): Promise<any>;
+    /**
+     * hide the map
+     */
     hide(): Promise<void>;
     unhide(): Promise<void>;
+    /**
+     * destroy the map programmatically
+     *
+     * Destroy the map instance.
+     */
     destroy(nativeMap?: any): Promise<void>;
+    /**
+     * Clear Event Listeners
+     *
+     * Explicitly clear all registered event listeners. It's not clear to me whether or not this
+     * is strictly necessary as I imagine these should all get cleaned up when the map is destroyed
+     * but given the complication of NativeScript's garbage collection scheme it seems like a good
+     * idea to remove these handlers explicitly.
+     */
     private clearEventListeners;
     onStart(nativeMap?: any): Promise<void>;
     onResume(nativeMapViewInstance?: any): Promise<void>;
@@ -61,13 +180,73 @@ export declare class Mapbox extends MapboxCommon implements MapboxApi {
     onStop(nativeMap?: any): Promise<void>;
     onLowMemory(nativeMap?: any): Promise<void>;
     onDestroy(nativeMap?: any): Promise<void>;
+    /**
+     * event handler shim
+     *
+     * Initialize our event handler shim so that we can intercept events here.
+     *
+     * @param { any } settings
+     * @param { MapboxView } mapboxView
+     */
     initEventHandlerShim(settings: any, mapboxNativeViewInstance: any): void;
+    /**
+     * register on click handlers.
+     *
+     * The native mapbox API does not, apparently, support click handlers
+     * on circles, but it does for markers and polylines. WTF?
+     *
+     * Here we attempt to replicate the mapbox-gl-js behaviour of being
+     * able to assign an onClick handler to a layer by it's layer id.
+     *
+     * @param {string} event - the event to subscribe to. i.e. 'click'.
+     * @param {string} id - the id of the layer
+     * @param {function} callback - the callback to invoke when the layer is clicked on.
+     * @param {object] nativeMapView - reference to the native Map view.
+     *
+     * @link https://github.com/mapbox/mapbox-android-demo/issues/540
+     */
     onMapEvent(eventName: any, id: any, callback: any, nativeMapView?: any): void;
+    /**
+     * remove an event handler for a layer
+     *
+     * This will remove all event handlers (that we manage here) for
+     * the given layer id and event.
+     */
     offMapEvent(eventName: any, id: any, nativeMapView?: any): void;
+    /**
+     * If click events registered and a feature found for the event, then fire listener.
+     */
     private checkForClickEvent;
+    /**
+     * handles a line click event
+     *
+     * Given a click on a line overlay, find the id of the underlying line layer
+     * an invoke any registered callbacks.
+     */
     private handleLineClickEvent;
     hasFineLocationPermission(): Promise<boolean>;
-    requestFineLocationPermission(): Promise<[import("@nativescript-community/perms").Status, boolean]>;
+    /**
+     * Request fine locaion permission
+     *
+     * @link https://docs.mapbox.com/android/core/overview/#permissionsmanager
+     */
+    requestFineLocationPermission(): Promise<import("@nativescript-community/perms").Result>;
+    /**
+     * set the map style
+     *
+     * The 7.X version of the SDK uses a builder class for forming
+     * URLs.
+     *
+     * NOTE: The style must be explicitly set using this method in the onMapReady() handler.
+     *
+     * @param {string | MapStyle } style - a style following the Mapbox style specification or a URL to a style.
+     * @param {any} nativeMapViewInstance - native map view (com.mapbox.mapboxsdk.maps.MapView)
+     *
+     * @see MapboxViewCommonBase:setMapStyle()
+     *
+     * @link https://docs.mapbox.com/android/api/map-sdk/7.1.2/com/mapbox/mapboxsdk/maps/Style.Builder.html
+     * @link https://docs.mapbox.com/android/api/map-sdk/7.1.2/com/mapbox/mapboxsdk/maps/MapboxMap.html#setStyle-java.lang.String-com.mapbox.mapboxsdk.maps.Style.OnStyleLoaded-
+     */
     setMapStyle(style: string | MapStyle, nativeMapViewInstance?: any): Promise<void>;
     getImage(imageId: string, nativeMap?: any): Promise<ImageSource>;
     addImage(imageId: string, image: string, nativeMap?: any): Promise<void>;
@@ -77,7 +256,16 @@ export declare class Mapbox extends MapboxCommon implements MapboxApi {
     iconCache: {
         [k: string]: com.mapbox.mapboxsdk.annotations.Icon;
     };
+    /**
+     *
+     * @deprecated
+     * @link https://github.com/mapbox/mapbox-plugins-android/tree/master/plugin-annotation
+     */
     _addMarkers(markers: MapboxMarker[], nativeMap?: any): void;
+    /**
+     *
+     * @deprecated
+     */
     _removeMarkers(ids?: any, nativeMap?: any): void;
     setCenter(options: SetCenterOptions, nativeMap?: any): Promise<void>;
     getCenter(nativeMap?: any): Promise<LatLng>;
@@ -85,14 +273,38 @@ export declare class Mapbox extends MapboxCommon implements MapboxApi {
     getZoomLevel(nativeMap?: any): Promise<number>;
     setTilt(options: SetTiltOptions, nativeMap?: any): Promise<void>;
     getTilt(nativeMap?: any): Promise<number>;
+    /**
+     * get users current location
+     *
+     * @link https://docs.mapbox.com/android/api/map-sdk/9.0.0/com/mapbox/mapboxsdk/location/LocationComponent.html#getLastKnownLocation--
+     */
     getUserLocation(): Promise<UserLocation>;
+    /**
+     * @link https://www.mapbox.com/android-docs/api/mapbox-java/libjava-geojson/3.4.1/com/mapbox/geojson/Feature.html
+     */
     queryRenderedFeatures(options: QueryRenderedFeaturesOptions): Promise<Feature[]>;
     querySourceFeatures(sourceId: string, options?: QuerySourceFeaturesOptions): Promise<Feature[]>;
+    /**
+     *
+     * @deprecated
+     */
     addPolygon(options: AddPolygonOptions, nativeMap?: any): Promise<void>;
+    /**
+     *
+     * @deprecated
+     */
     addPolyline(options: AddPolylineOptions, nativeMap?: any): Promise<void>;
     removePolygons(ids?: any[], nativeMap?: any): Promise<void>;
     removePolylines(ids?: any[], nativeMap?: any): Promise<void>;
     animateCamera(options: AnimateCameraOptions, nativeMap?: any): Promise<void>;
+    /**
+     * set an on map click listener.
+     *
+     * The new Mapbox Native SDK allows for multiple listeners on an event and follows the standard
+     * pattern of returning 'true' when a handler has handled the event and others shouldn't.
+     *
+     * Not returning a boolean from the listener function will cause a crash.
+     */
     setOnMapClickListener(listener: (data: LatLng) => boolean, nativeMap?: MapboxView): Promise<void>;
     setOnMapLongClickListener(listener: (data: LatLng) => boolean, nativeMap?: any): Promise<void>;
     setOnMoveBeginListener(listener: (data?: LatLng) => void, nativeMap?: any): Promise<void>;
@@ -109,26 +321,145 @@ export declare class Mapbox extends MapboxCommon implements MapboxApi {
     deleteOfflineRegion(options: DeleteOfflineRegionOptions): Promise<void>;
     _getOfflineManager(): any;
     addExtrusion(options: AddExtrusionOptions, nativeMap?: any): Promise<void>;
+    /**
+     * update a geojson source
+     *
+     */
     updateSource(id: string, options: UpdateSourceOptions, nativeMap?: any): Promise<void>;
+    /**
+     * add a geojson or vector source
+     *
+     * Add a source that can then be referenced in the style specification
+     * passed to addLayer().
+     *
+     * @link https://docs.mapbox.com/mapbox-gl-js/api/#map#addsource
+     */
     addSource(id: string, options: AddSourceOptions, nativeMap?: any): Promise<void>;
+    /**
+     * remove source by id
+     */
     removeSource(id: string, nativeMap?: any): Promise<void>;
+    /**
+     * a rough analogue to the mapbox-gl-js addLayer() method
+     *
+     * It would be nice if this {N} API matched the mapbox-gl-js API which
+     * would make it much easier to share mapping applications between the web
+     * and {N} apps.
+     *
+     * This method accepts a Mapbox-GL-JS style specification JSON object with some
+     * limitations:
+     *
+     * - the source: must be a GeoJSON object, vector source definition, or an id of a source added via addSource()
+     * - only a subset of paint properties are available.
+     *
+     * @param {object} style - a style following the Mapbox style specification.
+     * @param {any} nativeMapView - native map view (com.mapbox.mapboxsdk.maps.MapView)
+     *
+     * @link https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers
+     */
     addLayer(style: any, belowLayerId?: string, nativeMap?: any): Promise<void>;
+    /**
+     * remove layer by ID
+     *
+     * Removes a layer given a layer id
+     *
+     * @param {string} id
+     */
     removeLayer(id: string, nativeMap?: any): Promise<void>;
+    /**
+     * @deprecated
+     * Add a point to a line
+     *
+     * This method appends a point to a line and is useful for drawing a users track.
+     *
+     * @param {id} id - id of line to add a point to.
+     * @param {array} lnglat - [lng,lat] to append to the line.
+     *
+     * @link https://github.com/mapbox/mapbox-gl-native/issues/13983
+     * @link https://docs.mapbox.com/android/api/mapbox-java/libjava-geojson/3.0.1/com/mapbox/geojson/Feature.html#Feature--
+     * @link https://docs.oracle.com/javase/8/docs/api/java/util/List.html
+     */
     addLinePoint(id: string, lnglat: any, sourceId?: string, nativeMapView?: any): Promise<void>;
     addGeoJsonClustered(options: AddGeoJsonClusteredOptions, nativeMap?: any): Promise<void>;
+    /**
+     * constantly center the map on the users location.
+     */
     trackUser(options: TrackUserOptions, nativeMap?: any): Promise<void>;
     private static getAndroidColor;
     _getMapStyle(input: any): any;
+    /**
+     * Mapbox Map Options
+     *
+     * @link https://github.com/mapbox/mapbox-gl-native/wiki/Android-6.x-to-7.x-migration-guide
+     * @link https://github.com/mapbox/mapbox-gl-native/blob/master/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMapOptions.java
+     * @link https://docs.mapbox.com/android/api/map-sdk/7.1.2/com/mapbox/mapboxsdk/maps/MapboxMapOptions.html
+     */
     _getMapboxMapOptions(settings: any): com.mapbox.mapboxsdk.maps.MapboxMapOptions;
+    /**
+     * convert string to camera mode constant.
+     *
+     * @link https://docs.mapbox.com/android/api/map-sdk/8.1.0/com/mapbox/mapboxsdk/location/modes/CameraMode.html
+     */
     _stringToCameraMode(mode: UserLocationCameraMode): any;
+    /**
+     * convert string to render mode
+     */
     _stringToRenderMode(mode: any): any;
     _convertCameraMode(mode: any): UserLocationCameraMode;
     _fineLocationPermissionGranted(): boolean;
     _getRegionName(offlineRegion: com.mapbox.mapboxsdk.offline.OfflineRegion): string;
     _getRegionMetadata(offlineRegion: com.mapbox.mapboxsdk.offline.OfflineRegion): any;
+    /**
+     * show a user location marker
+     *
+     * This method must not be called before location permissions have been granted.
+     *
+     * Supported options are:
+     *
+     * - foregroundTintColor
+     * - foregroundStaleTintColor
+     * - backgroundTintColor
+     * - bearingTintColor
+     * - elevation
+     * - accuracyColor
+     * - accuracyAlpha
+     * - useDefaultLocationEngine
+     * - renderMode
+     * - cameraMode
+     * - clickListener
+     * - cameraTrackingChangeListener
+     *
+     * @param {object} options
+     *
+     * @link https://github.com/mapbox/mapbox-android-demo/blob/master/MapboxAndroidDemo/src/main/java/com/mapbox/mapboxandroiddemo/examples/location/LocationComponentOptionsActivity.java
+     * @link https://developer.android.com/reference/android/graphics/Color
+     *
+     * @todo at least with simulated data, the location is only updated once hence adding support for forceLocation method.
+     */
     showUserLocationMarker(options: any, nativeMap?: any): Promise<void>;
+    /**
+     * hide (destroy) the user location marker
+     *
+     * This method destroys the user location marker.
+     */
     hideUserLocationMarker(nativeMap?: any): Promise<void>;
+    /**
+     * Change the mode of the user location marker
+     *
+     * Used to change the camera tracking and render modes of an existing
+     * marker.
+     *
+     * The marker must be configured using showUserLocationMarker before this method
+     * can called.
+     */
     changeUserLocationMarkerMode(renderModeString: any, cameraModeString: UserLocationCameraMode, nativeMap?: any): Promise<void>;
+    /**
+     * force updating of user location
+     *
+     * This method forces the user location marker, if displayed, to move to a new location
+     *
+     * @todo figure out why the user location marker is not updating.
+     */
     forceUserLocationUpdate(location: any, nativeMap?: any): Promise<void>;
     getLayer(name: string, nativeMap?: any): Promise<LayerCommon>;
     getLayers(nativeMap?: any): Promise<LayerCommon[]>;