@arcgis/core/widgets/AreaMeasurement2D.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 AreaMeasurement2DViewModel from "./AreaMeasurement2D/AreaMeasurement2DViewModel.js";
import type { Icon } from "@esri/calcite-components/components/calcite-icon";
import type { SystemOrAreaUnit } from "../core/units.js";
import type { WidgetProperties } from "./Widget.js";
import type { SnappingOptionsProperties } from "../views/interactive/snapping/SnappingOptions.js";
import type { AreaMeasurement2DViewModelProperties } from "./AreaMeasurement2D/AreaMeasurement2DViewModel.js";

export interface AreaMeasurement2DProperties extends WidgetProperties, Partial<Pick<AreaMeasurement2D, "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-area"
   * @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 area values.
   * Possible values are listed in [unitOptions](https://developers.arcgis.com/javascript/latest/references/core/widgets/AreaMeasurement2D/#unitOptions).
   *
   * @example
   * // To create the AreaMeasurement2D widget that displays area in square US feet
   * let measurementWidget = new AreaMeasurement2D({
   *   view: view,
   *   unit: "square-us-feet"
   * });
   *
   * // To display the current measurement unit
   * console.log("Current unit: ", measurementWidget.unit);
   */
  unit?: SystemOrAreaUnit | null;
  /**
   * List of available units and unit systems (imperial, metric) for displaying the area values.
   * By default, the following units are included: `metric`, `imperial`, `square-inches`, `square-feet`, `square-us-feet`, `square-yards`, `square-miles`, `square-meters`, `square-kilometers`, `acres`, `ares`, `hectares`.
   * Possible [unit](https://developers.arcgis.com/javascript/latest/references/core/widgets/AreaMeasurement2D/#unit) values can only be a subset of this list.
   *
   * @example
   * // To display the available units to the console
   * let measurementWidget = new AreaMeasurement2D({
   *   view: view
   * });
   * console.log("All units: ", measurementWidget.unitOptions.join(", "));
   */
  unitOptions?: SystemOrAreaUnit[] | 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
   * [AreaMeasurement2DViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/AreaMeasurement2D/AreaMeasurement2DViewModel/)
   * class to access all properties and methods on the widget.
   *
   * @example
   * // Use the ViewModel to access and set advanced settings
   * let measurementWidget = new AreaMeasurement2D({
   *   viewModel: {
   *     view: view,
   *     unit: "square-us-feet"
   *   }
   * });
   * view.ui.add(measurementWidget, "top-right");
   */
  viewModel?: AreaMeasurement2DViewModelProperties;
}

/**
 * The AreaMeasurement2D widget calculates and displays the area and perimeter of a polygon in a
 * [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/). How the area and perimeter are computed depends on the map's spatial reference:
 * * In geographic coordinate systems (GCS) and in Web Mercator, they are computed geodetically.
 * * In projected coordinate systems (PCS), apart from Web Mercator, they are computed in a Euclidean manner (in their respective PCS).
 *
 * [![measurement-area-2d](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/AreaMeasurement2D_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
 * [AreaMeasurement3D](https://developers.arcgis.com/javascript/latest/references/core/widgets/AreaMeasurement3D/).
 *
 * > [!WARNING]
 * >
 * > **Note:**
 * > Snapping is disabled by default. This can be enabled by setting the [snappingOptions](https://developers.arcgis.com/javascript/latest/references/core/widgets/AreaMeasurement2D/#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 [Area Measurement 2D](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-area-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 [AreaMeasurement2DViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/AreaMeasurement2D/AreaMeasurement2DViewModel/)
 * @see [DistanceMeasurement2D](https://developers.arcgis.com/javascript/latest/references/core/widgets/DistanceMeasurement2D/)
 * @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 AreaMeasurement2D widget to your map
 * let measurementWidget = new AreaMeasurement2D({
 *   view: view
 * });
 * view.ui.add(measurementWidget, "top-right");
 */
export default class AreaMeasurement2D extends Widget<AreaMeasurement2DProperties> {
  /**
   * @example
   * // Typical usage
   * const measurementWidget = new AreaMeasurement2D({
   *   view: view
   * });
   * view.ui.add(measurementWidget, "top-right");
   */
  constructor(properties?: AreaMeasurement2DProperties);
  /**
   * 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-area"
   * @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 area values.
   * Possible values are listed in [unitOptions](https://developers.arcgis.com/javascript/latest/references/core/widgets/AreaMeasurement2D/#unitOptions).
   *
   * @example
   * // To create the AreaMeasurement2D widget that displays area in square US feet
   * let measurementWidget = new AreaMeasurement2D({
   *   view: view,
   *   unit: "square-us-feet"
   * });
   *
   * // To display the current measurement unit
   * console.log("Current unit: ", measurementWidget.unit);
   */
  get unit(): SystemOrAreaUnit;
  set unit(value: SystemOrAreaUnit | null | undefined);
  /**
   * List of available units and unit systems (imperial, metric) for displaying the area values.
   * By default, the following units are included: `metric`, `imperial`, `square-inches`, `square-feet`, `square-us-feet`, `square-yards`, `square-miles`, `square-meters`, `square-kilometers`, `acres`, `ares`, `hectares`.
   * Possible [unit](https://developers.arcgis.com/javascript/latest/references/core/widgets/AreaMeasurement2D/#unit) values can only be a subset of this list.
   *
   * @example
   * // To display the available units to the console
   * let measurementWidget = new AreaMeasurement2D({
   *   view: view
   * });
   * console.log("All units: ", measurementWidget.unitOptions.join(", "));
   */
  get unitOptions(): SystemOrAreaUnit[];
  set unitOptions(value: SystemOrAreaUnit[] | 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 AreaMeasurement2D({
   *   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
   * [AreaMeasurement2DViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/AreaMeasurement2D/AreaMeasurement2DViewModel/)
   * class to access all properties and methods on the widget.
   *
   * @example
   * // Use the ViewModel to access and set advanced settings
   * let measurementWidget = new AreaMeasurement2D({
   *   viewModel: {
   *     view: view,
   *     unit: "square-us-feet"
   *   }
   * });
   * view.ui.add(measurementWidget, "top-right");
   */
  get viewModel(): AreaMeasurement2DViewModel;
  set viewModel(value: AreaMeasurement2DViewModelProperties);
}