@arcgis/core/widgets/DistanceMeasurement2D.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

import type MapView from "../views/MapView.js";
import type SnappingOptions from "../views/interactive/snapping/SnappingOptions.js";
import type Widget from "./Widget.js";
import type DistanceMeasurement2DViewModel from "./DistanceMeasurement2D/DistanceMeasurement2DViewModel.js";
import type { Icon } from "@esri/calcite-components/components/calcite-icon";
import type { SystemOrLengthUnit } from "../core/units.js";
import type { WidgetProperties } from "./Widget.js";
import type { SnappingOptionsProperties } from "../views/interactive/snapping/SnappingOptions.js";
import type { DistanceMeasurement2DViewModelProperties } from "./DistanceMeasurement2D/DistanceMeasurement2DViewModel.js";

export interface DistanceMeasurement2DProperties extends WidgetProperties, Partial<Pick<DistanceMeasurement2D, "view">> {
  /**
   * Icon which represents the widget. It is typically used when the widget is controlled by another
   * one (e.g. in the Expand widget).
   *
   * @default "measure-line"
   * @since 4.27
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  icon?: Icon["icon"] | null;
  /**
   * The widget's default label.
   *
   * @since 4.11
   */
  label?: string | null;
  /**
   * The [SnappingOptions](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/SnappingOptions/) for sketching.
   * It supports [self](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/SnappingOptions/#selfEnabled) and
   * [feature](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/SnappingOptions/#featureEnabled) snapping.
   *
   * @beta
   * @since 4.32
   */
  snappingOptions?: SnappingOptionsProperties;
  /**
   * 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/core/widgets/DistanceMeasurement2D/#unitOptions).
   *
   * @example
   * // To create the DistanceMeasurement2D widget that displays distance in yards
   * let measurementWidget = new DistanceMeasurement2D({
   *   view: view,
   *   unit: "yards"
   * });
   *
   * // To display the current measurement unit
   * console.log('Current unit: ', measurementWidget.unit);
   */
  unit?: SystemOrLengthUnit | null;
  /**
   * List of available units and unit systems (imperial, metric) for displaying the distance values.
   * 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/core/widgets/DistanceMeasurement2D/#unit) values can only be a subset of this list.
   *
   * @example
   * // To display the available units to the console
   * let measurementWidget = new DistanceMeasurement2D({
   *   view: view
   * });
   * console.log('All units: ', measurementWidget.unitOptions.join(", "));
   */
  unitOptions?: SystemOrLengthUnit[] | null;
  /**
   * The view model for this widget. This is a class that contains all the logic
   * (properties and methods) that controls this widget's behavior. See the
   * [DistanceMeasurement2DViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/DistanceMeasurement2D/DistanceMeasurement2DViewModel/)
   * class to access all properties and methods on the widget.
   *
   * @example
   * // Use the ViewModel to access and set advanced settings
   * let measurementWidget = new DistanceMeasurement2D({
   *   viewModel: {
   *     view: view,
   *     unit: "feet"
   *   }
   * });
   * view.ui.add(measurementWidget, "top-right");
   */
  viewModel?: DistanceMeasurement2DViewModelProperties;
}

/**
 * The DistanceMeasurement2D widget calculates and displays the distance between two or more points
 * in a [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/). How distances are computed depends on the map's spatial reference:
 * * In geographic coordinate systems (GCS) and in Web Mercator, distances are computed geodetically.
 * * In projected coordinate systems (PCS), apart from Web Mercator, distances are computed in a Euclidean manner (in their respective PCS).
 *
 * [![measurement-line-2d](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/DistanceMeasurement2D_widget.png)](https://developers.arcgis.com/javascript/latest/sample-code/widgets-measurement-2d/)
 *
 * ### Undo / Redo
 *
 * Gesture | Action |
 * ---------|---------|
 * Z | Incrementally undoes actions recorded in the stack. |
 * R | Incrementally redos actions recorded in the stack. |
 *
 * This widget is designed to work with 2D MapViews. For measurements with 3D SceneViews, use
 * [DirectLineMeasurement3D](https://developers.arcgis.com/javascript/latest/references/core/widgets/DirectLineMeasurement3D/).
 *
 * > [!WARNING]
 * >
 * > **Note:**
 * > Snapping is disabled by default. This can be enabled by setting the [snappingOptions](https://developers.arcgis.com/javascript/latest/references/core/widgets/DistanceMeasurement2D/#snappingOptions) property.
 * > Please refer to [FeatureSnappingLayerSource](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/FeatureSnappingLayerSource/) for additional information on what layer sources are supported.
 *
 * @deprecated since version 5.0. Use the [Distance Measurement 2D](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-distance-measurement-2d/) component instead. For information on widget deprecation, read about [Esri's move to web components](https://developers.arcgis.com/javascript/latest/components-transition-plan/).
 * @since 4.10
 * @see [Sample - Measurement in 2D](https://developers.arcgis.com/javascript/latest/sample-code/widgets-measurement-2d/)
 * @see [DistanceMeasurement2DViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/DistanceMeasurement2D/DistanceMeasurement2DViewModel/)
 * @see [AreaMeasurement2D](https://developers.arcgis.com/javascript/latest/references/core/widgets/AreaMeasurement2D/)
 * @see [DefaultUI](https://developers.arcgis.com/javascript/latest/references/core/views/ui/DefaultUI/)
 * @see [MapView.theme](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/#theme)
 * @example
 * // To add the DistanceMeasurement2D widget to the map
 * let measurementWidget = new DistanceMeasurement2D({
 *   view: view
 * });
 * view.ui.add(measurementWidget, "top-right");
 */
export default class DistanceMeasurement2D extends Widget<DistanceMeasurement2DProperties> {
  /**
   * @example
   * // To add the DistanceMeasurement2D widget to the map
   * let measurementWidget = new DistanceMeasurement2D({
   *   view: view
   * });
   * view.ui.add(measurementWidget, "top-right");
   */
  constructor(properties?: DistanceMeasurement2DProperties);
  /**
   * Icon which represents the widget. It is typically used when the widget is controlled by another
   * one (e.g. in the Expand widget).
   *
   * @default "measure-line"
   * @since 4.27
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  get icon(): Icon["icon"];
  set icon(value: Icon["icon"] | null | undefined);
  /**
   * The widget's default label.
   *
   * @since 4.11
   */
  get label(): string;
  set label(value: string | null | undefined);
  /**
   * The [SnappingOptions](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/SnappingOptions/) for sketching.
   * It supports [self](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/SnappingOptions/#selfEnabled) and
   * [feature](https://developers.arcgis.com/javascript/latest/references/core/views/interactive/snapping/SnappingOptions/#featureEnabled) snapping.
   *
   * @beta
   * @since 4.32
   */
  get snappingOptions(): SnappingOptions;
  set snappingOptions(value: SnappingOptionsProperties);
  /**
   * 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/core/widgets/DistanceMeasurement2D/#unitOptions).
   *
   * @example
   * // To create the DistanceMeasurement2D widget that displays distance in yards
   * let measurementWidget = new DistanceMeasurement2D({
   *   view: view,
   *   unit: "yards"
   * });
   *
   * // To display the current measurement unit
   * console.log('Current unit: ', measurementWidget.unit);
   */
  get unit(): SystemOrLengthUnit;
  set unit(value: SystemOrLengthUnit | null | undefined);
  /**
   * List of available units and unit systems (imperial, metric) for displaying the distance values.
   * 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/core/widgets/DistanceMeasurement2D/#unit) values can only be a subset of this list.
   *
   * @example
   * // To display the available units to the console
   * let measurementWidget = new DistanceMeasurement2D({
   *   view: view
   * });
   * console.log('All units: ', measurementWidget.unitOptions.join(", "));
   */
  get unitOptions(): SystemOrLengthUnit[];
  set unitOptions(value: SystemOrLengthUnit[] | null | undefined);
  /**
   * A reference to the [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/). Set this to link the widget
   * to a specific view.
   *
   * @example
   * // Typical usage
   * let measurementWidget = new DistanceMeasurement2D({
   *   view: view
   * });
   * view.ui.add(measurementWidget, "top-right");
   */
  accessor view: MapView | null | undefined;
  /**
   * The view model for this widget. This is a class that contains all the logic
   * (properties and methods) that controls this widget's behavior. See the
   * [DistanceMeasurement2DViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/DistanceMeasurement2D/DistanceMeasurement2DViewModel/)
   * class to access all properties and methods on the widget.
   *
   * @example
   * // Use the ViewModel to access and set advanced settings
   * let measurementWidget = new DistanceMeasurement2D({
   *   viewModel: {
   *     view: view,
   *     unit: "feet"
   *   }
   * });
   * view.ui.add(measurementWidget, "top-right");
   */
  get viewModel(): DistanceMeasurement2DViewModel;
  set viewModel(value: DistanceMeasurement2DViewModelProperties);
}