@arcgis/core/views/draw/PolygonDrawAction.d.ts

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

import type CursorUpdateEvent from "./CursorUpdateEvent.js";
import type DrawAction from "./DrawAction.js";
import type DrawCompleteEvent from "./DrawCompleteEvent.js";
import type VertexAddEvent from "./VertexAddEvent.js";
import type VertexRemoveEvent from "./VertexRemoveEvent.js";
import type { DrawingMode } from "./types.js";
import type { DrawActionProperties } from "./DrawAction.js";

export interface PolygonDrawActionProperties extends DrawActionProperties, Partial<Pick<PolygonDrawAction, "mode">> {}

export interface PolygonDrawActionEvents {
  /**
   * Fires when a vertex is added.
   *
   * @example
   * // listen to PolygonDrawAction.vertex-add
   * // give a visual feedback to the user on the view
   * // as user moving the pointer.
   * action.on("vertex-add", function (evt) {
   *   view.graphics.removeAll();
   *   let polygon = new Polygon({
   *     rings: evt.vertices,
   *     spatialReference: view.spatialReference
   *   });
   *   graphic = createGraphic(polygon);
   *   view.graphics.add(graphic);
   * });
   */
  "vertex-add": VertexAddEvent;
  /**
   * Fires when a vertex is removed.
   *
   * @example
   * // listen to PolygonDrawAction.vertex-remove
   * // give a visual feedback to the user on the view
   * // as user moving the pointer.
   * action.on("vertex-remove", function (evt) {
   *   view.graphics.removeAll();
   *   let polygon = new Polygon({
   *     rings: evt.vertices,
   *     spatialReference: view.spatialReference
   *   });
   *   graphic = createGraphic(polygon);
   *   view.graphics.add(graphic);
   * });
   */
  "vertex-remove": VertexRemoveEvent;
  /**
   * Fires after the pointer moves on the view.
   *
   * @example
   * // listen to PolygonDrawAction.cursor-update
   * // give a visual feedback to the user on the view
   * // as user moving the pointer.
   * action.on("cursor-update", function (evt) {
   *   view.graphics.removeAll();
   *   let polygon = new Polygon({
   *     rings: evt.vertices,
   *     spatialReference: view.spatialReference
   *   });
   *   graphic = createGraphic(polygon);
   *   view.graphics.add(graphic);
   * });
   */
  "cursor-update": CursorUpdateEvent;
  /**
   * Fires after the user has completed drawing a polygon.
   *
   * @example
   * // listen to PolygonDrawAction.draw-complete
   * // add the graphic representing the completed
   * // polygon to the view
   * action.on("draw-complete", function (evt) {
   *   view.graphics.removeAll();
   *   let polygon = new Polygon({
   *     rings: evt.vertices,
   *     spatialReference: view.spatialReference
   *   });
   *   graphic = createGraphic(polygon);
   *   view.graphics.add(graphic);
   * });
   */
  "draw-complete": DrawCompleteEvent;
  /**
   * Fires in response to undo action or when [undo()](https://developers.arcgis.com/javascript/latest/references/core/views/draw/PolygonDrawAction/#undo) is called.
   *
   * @since 4.7
   * @example
   * // Update the graphic on the view as the last action was undone
   * action.on("undo", function (evt) {
   *   view.graphics.removeAll();
   *   let polygon = new Polygon({
   *     rings: evt.vertices,
   *     spatialReference: view.spatialReference
   *   });
   *   graphic = createGraphic(polygon);
   *   view.graphics.add(graphic);
   * });
   */
  undo: VertexAddEvent | VertexRemoveEvent;
  /**
   * Fires in response to redo action or when [redo()](https://developers.arcgis.com/javascript/latest/references/core/views/draw/PolygonDrawAction/#redo) is called.
   *
   * @since 4.7
   * @example
   * // Update the graphic on the view as the last action was redone
   * action.on("redo", function (evt) {
   *   view.graphics.removeAll();
   *   let polygon = new Polygon({
   *     rings: evt.vertices,
   *     spatialReference: view.spatialReference
   *   });
   *   graphic = createGraphic(polygon);
   *   view.graphics.add(graphic);
   * });
   */
  redo: VertexAddEvent | VertexRemoveEvent;
}

/**
 * This class uses different [events](https://developers.arcgis.com/javascript/latest/references/core/views/draw/PolygonDrawAction/#PolygonDrawActionEvents) to generate a set of vertices to create a new [Polygon](https://developers.arcgis.com/javascript/latest/references/core/geometry/Polygon/)
 * geometry using [Draw](https://developers.arcgis.com/javascript/latest/references/core/views/draw/Draw/). When [draw.create("polygon")](https://developers.arcgis.com/javascript/latest/references/core/views/draw/Draw/#create)
 * is called, a reference to PolygonDrawAction is returned. You can listen to [events](https://developers.arcgis.com/javascript/latest/references/core/views/draw/PolygonDrawAction/#PolygonDrawActionEvents) on the
 * PolylineDrawAction instance, which allows users to create polylines that meet criteria specified by the developer.
 *
 * @since 4.5
 * @see [Sample - Prevent drawing a self-intersecting line](https://developers.arcgis.com/javascript/latest/sample-code/draw-line/)
 * @example
 * function enableCreatePolygon(draw, view) {
 *   let action = draw.create("polygon");
 *
 *   // PolygonDrawAction.vertex-add
 *   // Fires when user clicks, or presses the "F" key.
 *   // Can also be triggered when the "R" key is pressed to redo.
 *   action.on("vertex-add", function (evt) {
 *     createPolygonGraphic(evt.vertices);
 *   });
 *
 *   // PolygonDrawAction.vertex-remove
 *   // Fires when the "Z" key is pressed to undo the last added vertex
 *   action.on("vertex-remove", function (evt) {
 *     createPolygonGraphic(evt.vertices);
 *   });
 *
 *   // Fires when the pointer moves over the view
 *   action.on("cursor-update", function (evt) {
 *     createPolygonGraphic(evt.vertices);
 *   });
 *
 *   // Add a graphic representing the completed polygon
 *   // when user double-clicks on the view or presses the "Enter" key
 *   action.on("draw-complete", function (evt) {
 *     createPolygonGraphic(evt.vertices);
 *   });
 * }
 *
 * function createPolygonGraphic(vertices){
 *   view.graphics.removeAll();
 *   let polygon = {
 *     type: "polygon", // autocasts as Polygon
 *     rings: vertices,
 *     spatialReference: view.spatialReference
 *   };
 *
 *   let graphic = new Graphic({
 *     geometry: polygon,
 *     symbol: {
 *       type: "simple-fill", // autocasts as SimpleFillSymbol
 *       color: "purple",
 *       style: "solid",
 *       outline: {  // autocasts as SimpleLineSymbol
 *         color: "white",
 *         width: 1
 *       }
 *     }
 *   });
 *   view.graphics.add(graphic);
 * }
 */
export default class PolygonDrawAction extends DrawAction {
  /**
   * @deprecated
   * Do not directly reference this property.
   * Use EventNames and EventTypes helpers from \@arcgis/core/Evented
   */
  "@eventTypes": PolygonDrawActionEvents;
  constructor(properties?: PolygonDrawActionProperties);
  /**
   * The drawing mode. It is only relevant when the action is first created.
   * Its value cannot be changed during the action lifecycle.
   *
   * **Possible Values**
   *
   * Value | Description |
   * ----- | ----------- |
   * hybrid | Vertices are added while the pointer is clicked or dragged.
   * freehand | Vertices are added while the pointer is dragged.
   * click | Vertices are added when the pointer is clicked.
   *
   * @default "hybrid"
   * @since 4.7
   * @example draw.create("polygon", {mode: "freehand"});
   */
  accessor mode: DrawingMode;
  /**
   * Completes drawing the polygon geometry and fires the [@draw-complete](https://developers.arcgis.com/javascript/latest/references/core/views/draw/PolygonDrawAction/#event-draw-complete) event.
   * Call this method if the drawing logic needs to be completed other than by double-clicking or pressing the "Enter" key.
   */
  complete(): void;
}