@arcgis/map-components/dist/components/arcgis-distance-measurement-2d/customElement.d.ts

ArcGIS Map Components

/// <reference path="../../index.d.ts" />
import type MapView from "@arcgis/core/views/MapView.js";
import type DistanceMeasurementAnalysis from "@arcgis/core/analysis/DistanceMeasurementAnalysis.js";
import type SnappingOptions from "@arcgis/core/views/interactive/snapping/SnappingOptions.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { ArcgisReferenceElement } from "../types.js";
import type { DistanceMeasurement2DState } from "./types.js";
import type { T9nMeta } from "@arcgis/lumina/controllers";
import type { Icon as Icon } from "@esri/calcite-components/components/calcite-icon";
import type { SystemOrLengthUnit } from "@arcgis/core/core/units.js";

/**
 * The Distance Measurement 2D component can be added to an [arcgis-map](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-map/)
 * component to calculate and display the length of a polyline.
 *
 * How distances are computed depends on the scene's spatial reference.
 *
 * In **geographic coordinate systems** (GCS), and in **Web Mercator**, lengths are computed geodetically, taking into consideration the curvature of the planet.
 *
 * In **projected coordinate systems** (PCS), apart from Web Mercator, lengths are computed in a Euclidean manner (in their respective PCS).
 *
 * @since 4.28
 */
export abstract class ArcgisDistanceMeasurement2d extends LitElement {
  /**
   * The [DistanceMeasurementAnalysis](https://developers.arcgis.com/javascript/latest/references/core/analysis/DistanceMeasurementAnalysis/)
   * created or modified by the component.
   *
   * When connecting the Distance Measurement 2D component to the [arcgis-map](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-map/)
   * component, it automatically creates an empty analysis and adds it to the Map's
   * [arcgis-map.analyses](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-map/#analyses) collection.
   * You can then wait for the [DistanceMeasurementAnalysisView2D](https://developers.arcgis.com/javascript/latest/references/core/views/2d/analysis/DistanceMeasurementAnalysisView2D/)
   * to be created before accessing the analysis results.
   *
   * ```js
   * // Get the Map component and the Distance Measurement 2D component, and wait until both are ready.
   * const viewElement = document.querySelector("arcgis-map");
   * await viewElement.viewOnReady();
   * const distanceMeasurement2dElement = document.querySelector("arcgis-distance-measurement-2d");
   * await distanceMeasurement2dElement.componentOnReady();
   *
   * // Get the DistanceMeasurementAnalysis created by the Distance Measurement 2D component.
   * const analysis = distanceMeasurement2dElement.analysis;
   *
   * // Get the DistanceMeasurementAnalysisView2D and watch for results.
   * const analysisView = await viewElement.whenAnalysisView(analysis);
   * const handle = reactiveUtils.watch(
   *   () => analysisView?.result,
   *   () => {
   *     console.log("Analysis results:", analysisView.result);
   *   },
   * );
   * ```
   * Whenever the component is destroyed, the analysis is automatically removed from the collection.
   *
   * Alternatively, a programmatically created [DistanceMeasurementAnalysis](https://developers.arcgis.com/javascript/latest/references/core/analysis/DistanceMeasurementAnalysis/)
   * can be provided to the component.
   * Then, the application itself needs to add it to and later remove it from the analyses collection of the Map component.
   *
   * ```js
   * // Create the DistanceMeasurementAnalysis.
   * const distanceMeasurementAnalysis = new DistanceMeasurementAnalysis({
   *   geometry: new Polyline({
   *     paths: [
   *       [
   *         [-118.25, 34.05], // Los Angeles
   *         [-77.02, 38.90], // Washington, D.C.
   *       ]
   *     ],
   *   }),
   *   unit: "miles", // Display length in miles.
   * });
   *
   * // Get the Map component and the Distance Measurement 2D component, and wait until both are ready.
   * const viewElement = document.querySelector("arcgis-map");
   * await viewElement.viewOnReady();
   * const distanceMeasurement2dElement = document.querySelector("arcgis-distance-measurement-2d");
   * await distanceMeasurement2dElement.componentOnReady();
   *
   * // Add the analysis to the analyses collection of the Map component.
   * viewElement.analyses.add(distanceMeasurementAnalysis);
   *
   * // Connect the analysis to the measurement component:
   * distanceMeasurement2dElement.analysis = distanceMeasurementAnalysis;
   * ```
   *
   * @since 5.0
   */
  accessor analysis: DistanceMeasurementAnalysis;
  /**
   * 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-distance-measurement-2d/#destroy) method when you are done to
   * prevent memory leaks.
   *
   * @default false
   */
  accessor autoDestroyDisabled: boolean;
  /**
   * If true, the button that starts a new measurement will be hidden.
   *
   * @default false
   * @since 5.0
   */
  accessor hideStartButton: boolean;
  /**
   * If true, the unit selection dropdown will be hidden.
   *
   * @default false
   * @since 5.0
   */
  accessor hideUnitSelect: boolean;
  /**
   * Indicates whether the component's visualization is hidden in the view.
   *
   * @default false
   * @since 5.0
   */
  accessor hideVisualization: boolean;
  /**
   * Icon which represents the component.
   * Typically used when the component is controlled by another component (e.g. by the Expand component).
   *
   * @default "measure-line"
   * @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  accessor icon: Icon["icon"] | undefined;
  /** The component's default label. */
  accessor label: string | undefined;
  /** @internal */
  protected messages: {
      componentLabel: string;
      distance: string;
      hint: string;
      mode: string;
      modes: {
          auto: string;
          planar: string;
          geodesic: string;
      };
      newMeasurement: string;
      unit: string;
      unsupported: string;
  } & T9nMeta<{
      componentLabel: string;
      distance: string;
      hint: string;
      mode: string;
      modes: {
          auto: string;
          planar: string;
          geodesic: string;
      };
      newMeasurement: string;
      unit: string;
      unsupported: string;
  }>;
  /**
   * 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;
  /**
   * The [SnappingOptions](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/SnappingOptions/) for measuring.
   *
   * @since 4.28
   */
  accessor snappingOptions: SnappingOptions;
  /**
   * The component's state. The values mean the following:
   *
   * * `disabled` -  not ready yet
   * * `ready` - ready for measuring
   * * `measuring` - currently measuring
   * * `measured` - measuring has finished
   */
  get state(): DistanceMeasurement2DState;
  /**
   * Unit system (imperial, metric) or specific unit used for displaying the distance values. Possible values are listed in
   * [unitOptions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-distance-measurement-2d/#unitOptions).
   */
  accessor unit: SystemOrLengthUnit;
  /**
   * List of available units and unit systems (imperial, metric) that are shown in the component's dropdown.
   * By default, the following units are included: `metric`, `imperial`, `inches`, `feet`, `us-feet`, `yards`, `miles`, `nautical-miles`, `meters`, `kilometers`.
   * Possible [unit](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-distance-measurement-2d/#unit) values can only be a subset of this list.
   */
  accessor unitOptions: Array<SystemOrLengthUnit>;
  /**
   * 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-distance-measurement-2d component will be associated with a map or scene component rather than using the `view` property.
   */
  accessor view: MapView | undefined;
  /** Clears the current measurement. */
  clear(): Promise<void>;
  /** Permanently destroy the component. */
  destroy(): Promise<void>;
  /** Starts a new measurement. */
  start(): Promise<void>;
  /** 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: "analysis" | "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 "@eventTypes": {
    arcgisPropertyChange: ArcgisDistanceMeasurement2d["arcgisPropertyChange"]["detail"];
    arcgisReady: ArcgisDistanceMeasurement2d["arcgisReady"]["detail"];
  };
}