@arcgis/map-components/dist/components/arcgis-locate/customElement.d.ts

ArcGIS Map Components

/// <reference path="../../index.d.ts" />
import type MapView from "@arcgis/core/views/MapView.js";
import type SceneView from "@arcgis/core/views/SceneView.js";
import type Graphic from "@arcgis/core/Graphic.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { ArcgisReferenceElement, IconName } from "../types.js";
import type { T9nMeta } from "@arcgis/lumina/controllers";
import type { GoToOverride } from "@arcgis/core/widgets/support/types.js";
import type { State } from "./types.js";
import type { Button as Button } from "@esri/calcite-components/components/calcite-button";

/**
 * The Locate component animates the Map or Scene to the user's current location.
 *
 * This component uses the browser's [Geolocation API](https://developer.mozilla.org/docs/Web/API/Geolocation_API) which is only available in [secure contexts](https://developer.mozilla.org/docs/Web/Security/Defenses/Secure_Contexts), such as HTTPS.
 * `localhost` is considered "potentially secure" and can be used for testing.
 *
 * > [!WARNING]
 * >
 * > **Note**
 * >
 * > To avoid unexpected navigation, especially when using custom spatial references, configure the view [constraints](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-map/#constraints)
 * > such as `extent`, `minZoom`, and `maxZoom`.
 * > This helps when the geolocated position is inaccurate or causes the map to navigate
 * > to a location that is no longer visible because it is outside of
 * > a layer's `fullExtent`.
 *
 * @since 4.28
 */
export abstract class ArcgisLocate extends LitElement {
  /**
   * If true, the component will not be destroyed automatically when it is
   * disconnected from the document. This is useful when you want to move the
   * component to a different place on the page, or temporarily hide it. If this
   * is set, make sure to call the [destroy()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-locate/#destroy) method when you are done to
   * prevent memory leaks.
   *
   * @default false
   */
  accessor autoDestroyDisabled: boolean;
  accessor geolocationOptions: PositionOptions | undefined;
  /**
   * Indicates whether to navigate the view to the position and scale of the geolocated result.
   *
   * @default false
   */
  accessor goToLocationDisabled: boolean;
  /**
   * This function provides the ability to override either the [arcgis-map.goTo()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-map/#goTo) or [arcgis-scene.goTo()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#goTo) methods.
   *
   * @since 4.33
   * @example
   * ```js
   * component.goToOverride = function(view, goToParams) {
   *   goToParams.options = {
   *     duration: updatedDuration
   *   };
   *   return view.goTo(goToParams.target, goToParams.options);
   * };
   * ```
   */
  accessor goToOverride: GoToOverride | undefined;
  /** The graphic used to show the user's location on the map. */
  accessor graphic: Graphic;
  /**
   * Icon displayed in the component's button.
   *
   * @default "gps-off"
   * @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  accessor icon: IconName | undefined;
  /** The component's default label. */
  accessor label: string | undefined;
  /**
   * Replace localized message strings with your own strings.
   *
   * _**Note**: Individual message keys may change between releases._
   */
  accessor messageOverrides: {
      componentLabel?: string | undefined;
      title?: string | undefined;
      currentLocation?: string | undefined;
      timestamp?: string | undefined;
      latitude?: string | undefined;
      longitude?: string | undefined;
      accuracy?: string | undefined;
      altitude?: string | undefined;
      altitudeAccuracy?: string | undefined;
      heading?: string | undefined;
      speed?: string | undefined;
      permissionError?: string | undefined;
      timeoutError?: string | undefined;
      positionUnavailable?: string | undefined;
      cancel?: string | undefined;
  };
  /** @internal */
  protected messages: Partial<{
      componentLabel: string;
      title: string;
      currentLocation: string;
      timestamp: string;
      latitude: string;
      longitude: string;
      accuracy: string;
      altitude: string;
      altitudeAccuracy: string;
      heading: string;
      speed: string;
      permissionError: string;
      timeoutError: string;
      positionUnavailable: string;
      cancel: string;
  }> & T9nMeta<{
      componentLabel: string;
      title: string;
      currentLocation: string;
      timestamp: string;
      latitude: string;
      longitude: string;
      accuracy: string;
      altitude: string;
      altitudeAccuracy: string;
      heading: string;
      speed: string;
      permissionError: string;
      timeoutError: string;
      positionUnavailable: string;
      cancel: string;
  }>;
  /** @default false */
  accessor popupDisabled: boolean;
  /**
   * By assigning the `id` attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.
   *
   * @see [Associate components with a Map or Scene component](https://developers.arcgis.com/javascript/latest/programming-patterns/#associate-components-with-a-map-or-scene-component)
   */
  accessor referenceElement: ArcgisReferenceElement | string | undefined;
  /**
   * Indicates the scale to set on the view when navigating to the position of the geolocated
   * result, after a location is returned from the [@arcgisSuccess](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-locate/#event-arcgisSuccess) event.
   *
   * @default null
   */
  accessor scale: number | undefined;
  /** The current state of the component. */
  get state(): State;
  /**
   * The view associated with the component. 
   *   > **Note:** The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this `view` property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-locate component will be associated with a map or scene component rather than using the `view` property.
   */
  accessor view: MapView | SceneView | undefined;
  /**
   * Specifies the size of the component.
   *
   * @default "m"
   * @since 5.0
   */
  accessor visualScale: Button["scale"];
  /**
   * This function provides the ability to interrupt and cancel the process of
   * programmatically obtaining the location of the user's device.
   */
  cancelLocate(): Promise<void>;
  /** Permanently destroy the component. */
  destroy(): Promise<void>;
  locate(): Promise<GeolocationPosition | null>;
  readonly arcgisError: import("@arcgis/lumina").TargetedEvent<this, { error: GeolocationPositionError; }>;
  /** Emitted when the value of a property is changed. Use this to listen to changes to properties. */
  readonly arcgisPropertyChange: import("@arcgis/lumina").TargetedEvent<this, { name: "state"; }>;
  /** Emitted when the component associated with a map or scene view is ready to be interacted with. */
  readonly arcgisReady: import("@arcgis/lumina").TargetedEvent<this, void>;
  readonly arcgisSuccess: import("@arcgis/lumina").TargetedEvent<this, { position: GeolocationPosition; }>;
  readonly "@eventTypes": {
    arcgisError: ArcgisLocate["arcgisError"]["detail"];
    arcgisPropertyChange: ArcgisLocate["arcgisPropertyChange"]["detail"];
    arcgisReady: ArcgisLocate["arcgisReady"]["detail"];
    arcgisSuccess: ArcgisLocate["arcgisSuccess"]["detail"];
  };
}