@nativescript-community/ui-mapbox 6.2.19 → 6.2.20

package/index.ios.d.ts

@@ -2,19 +2,62 @@ 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;
+/**
+ * Map View Class instantiated from XML
+ *
+ * This class is created by the NativeScript XML view parsing
+ * code.
+ */
 export declare class MapboxView extends MapboxViewBase {
     private nativeMapView;
     private delegate;
     private settings;
     private initialized;
     private initCountHack;
+    /**
+     * programmatically include settings
+     */
     setConfig(settings: any): void;
     getNativeMapView(): any;
     createNativeView(): Object;
+    /**
+     * init the native view.
+     *
+     * FIXME: It appears that the order of events is different between iOS and Android.
+     * In the demo under Android, the main-page event handler is called first then the one
+     * in the plugin. Under iOS it's the reverse.
+     *
+     * The symptom is that any properties that reference a binding aren't available
+     * at the time this method is called. For example {{access_token}}.
+     *
+     * I'm sure there is something I do not understand about how this is supposed to work
+     * and that the handstands below are not necessary.
+     */
     onLoaded(): void;
     initNativeView(): void;
+    /**
+     * when the view is destroyed.
+     *
+     * This is called by the framework when the view is destroyed (made not visible).
+     *
+     * However, it does not seem to be called when the page is unloaded.
+     *
+     * @link https://docs.nativescript.org/plugins/ui-plugin-custom
+     */
     disposeNativeView(): Promise<void>;
+    /**
+     * returns a reference to the class Mapbox API shim instance
+     *
+     * @see Mapbox
+     */
     getMapboxApi(): any;
+    /**
+     * initialize the map
+     *
+     * @see MGLMapViewDelegateImpl
+     *
+     * @todo FIXME: figure out why the accessToken property (which is using a binding in the demo XML) isn't set before we arrive here.
+     */
     initMap(): void;
     onLayout(left: number, top: number, right: number, bottom: number): void;
 }
@@ -22,12 +65,37 @@ export declare class Mapbox extends MapboxCommon implements MapboxApi {
     private _mapboxViewInstance;
     private eventCallbacks;
     private userLocationRenderMode;
+    /**
+     * set the mapboxViewInstance
+     *
+     * @see MapboxView::initMap();
+     */
     setMapboxViewInstance(mapboxViewInstance: any): void;
+    /**
+     * event handler shim
+     *
+     * Initialize our event handler shim so that we can intercept events here.
+     *
+     * @param { MapboxView } mapboxView
+     */
     initEventHandlerShim(settings: any, mapboxNativeViewInstance: any): void;
+    /**
+     * register a map event handler
+     *
+     * The NativeScript ContentView base class as on() and off() methods.
+     */
     onMapEvent(eventName: any, id: any, callback: any, nativeMapView?: any): void;
     offMapEvent(eventName: any, id: any, nativeMapView?: any): void;
+    /**
+     * If click events registered and a feature found for the event, then fire listener.
+     */
     private checkForClickEvent;
     private _addMarkers;
+    /**
+     * create an display the map
+     *
+     * @todo FIXME: This method is not called. See MapboxView::initMap().
+     */
     show(options: ShowOptions): Promise<any>;
     hide(): Promise<void>;
     unhide(): Promise<void>;
@@ -38,6 +106,9 @@ export declare class Mapbox extends MapboxCommon implements MapboxApi {
     onStop(nativeMap?: any): Promise<void>;
     onLowMemory(nativeMap?: any): Promise<void>;
     onDestroy(nativeMap?: any): Promise<void>;
+    /**
+     * explicitly set a map style
+     */
     setMapStyle(style: string | MapStyle, nativeMap?: any): Promise<void>;
     getImage(imageId: string, nativeMap?: any): Promise<ImageSource>;
     addImage(imageId: string, image: string, nativeMap?: any): Promise<void>;
@@ -51,15 +122,58 @@ export declare class Mapbox extends MapboxCommon implements MapboxApi {
     setTilt(options: SetTiltOptions, nativeMap?: any): Promise<void>;
     getTilt(nativeMap?: any): Promise<number>;
     getUserLocation(nativeMap?: any): Promise<UserLocation>;
+    /**
+     * convert string to camera mode constant.
+     *
+     * Supported modes on iOS are different than on Android.
+     *
+     * @todo come up with a reasonable set of cross platform defaults.
+     */
     _stringToCameraMode(mode: UserLocationCameraMode): any;
     _stringToRenderMode(mode: any): any;
     _convertCameraMode(mode: MGLUserTrackingMode): UserLocationCameraMode;
+    /**
+     * show a user location marker
+     *
+     * This method must not be called before location permissions have been granted.
+     *
+     * Supported options under iOS are:
+     *
+     * - renderMode
+     * - cameraMode
+     * - clickListener
+     *
+     * Other options are ignored. Compare with the android version that supports a
+     * different set of options.
+     *
+     * @param {object} options
+     */
     showUserLocationMarker(options: any, nativeMap?: any): Promise<void>;
+    /**
+     * hide the user location marker
+     *
+     * @todo unfinished
+     */
     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>;
+    /**
+     * ignored on iOS
+     */
     forceUserLocationUpdate(location: any, nativeMap?: any): void;
     queryRenderedFeatures(options: QueryRenderedFeaturesOptions, nativeMap?: any): Promise<Feature[]>;
     querySourceFeatures(sourceId: string, options?: QuerySourceFeaturesOptions, nativeMap?: any): Promise<Feature[]>;
+    /**
+     * @deprecated
+     */
     addPolygon(options: AddPolygonOptions, nativeMap?: any): Promise<void>;
     addPolyline(options: AddPolylineOptions, nativeMap?: any): Promise<void>;
     private removePolyById;
@@ -67,9 +181,19 @@ export declare class Mapbox extends MapboxCommon implements MapboxApi {
     removePolygons(ids?: any[], nativeMap?: any): Promise<void>;
     removePolylines(ids?: any[], nativeMap?: any): Promise<void>;
     animateCamera(options: AnimateCameraOptions, nativeMap?: any): Promise<void>;
+    /**
+     * sets a map level click listener
+     *
+     */
     setOnMapClickListener(listener: (data: LatLng) => void, nativeMap?: any): Promise<void>;
     setOnMapLongClickListener(listener: (data: LatLng) => void, nativeMap?: any): Promise<void>;
     setOnScrollListener(listener: (data?: LatLng) => void, nativeMap?: any): Promise<void>;
+    /**
+     * simulates onMoveBegin single event callback
+     *
+     * This will call the listener provided once per pan akin to the way
+     * onMoveBegin on the Android side works.
+     */
     setOnMoveBeginListener(listener: (data?: LatLng) => void, nativeMap?: any): Promise<void>;
     setOnMoveEndListener(listener: () => void, nativeMap?: any): Promise<void>;
     setOnFlingListener(listener: () => void, nativeMap?: any): Promise<void>;
@@ -82,11 +206,66 @@ export declare class Mapbox extends MapboxCommon implements MapboxApi {
     listOfflineRegions(options?: ListOfflineRegionsOptions): Promise<OfflineRegion[]>;
     deleteOfflineRegion(options: DeleteOfflineRegionOptions): Promise<void>;
     addExtrusion(options: AddExtrusionOptions, nativeMap?: any): Promise<void>;
+    /**
+     * update a geojson source
+     *
+     */
     updateSource(id: string, options: UpdateSourceOptions, nativeMap?: any): Promise<void>;
+    /**
+     * add a vector or geojson 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.
+     * - 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, nativeMapView?: any): Promise<void>;
+    /**
+     * remove layer by ID
+     *
+     * Removes a layer given a layer id
+     *
+     * @param {string} id
+     */
     removeLayer(id: string, nativeMapViewInstance?: 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.
+     *
+     * The process for adding a point to a line is different in the iOS sdk than in
+     * the Android java sdk.
+     *
+     * @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/ios/maps/examples/runtime-animate-line/
+     */
     addLinePoint(id: string, lnglat: any, sourceId?: string, nativeMapView?: any): Promise<void>;
     addGeoJsonClustered(options: AddGeoJsonClusteredOptions, nativeMapViewInstance?: any): Promise<void>;
     trackUser(options: TrackUserOptions, nativeMap?: any): Promise<void>;