Provides the logic for the Sketch widget.

SketchViewModel simplifies the process of adding and updating graphics on the MapView. SketchViewModel is intended to be used with Graphics.

Read more

Pointer and keyboard gestures for creating graphics with different geometries are described in the tables below.

Creating point graphics

Gesture	Action
Left-click	Adds a point graphic at the pointer location.
C	Adds a point graphic at the pointer location.

Creating multipoint graphics

Gesture	Action
Left-click	Adds a point at the pointer location.
F	Adds a point to the multipoint graphic.
C	Completes the multipoint graphic sketch.
Z	Incrementally undo actions recorded in the stack.
R	Incrementally redo actions recorded in the stack.

Creating polyline and polygon graphics

Gesture	Action
Left-click	Adds a vertex at the pointer location.
Left-drag	Adds a vertex for each pointer move.
F	Adds a vertex to the polyline or polygon graphic.
C	Completes the polyline or polygon graphic sketch.
Z	Incrementally undo actions recorded in the stack.
R	Incrementally redo actions recorded in the stack.
Ctrl+Left-click or drag	Forces new vertices to be parallel or perpendicular to the previous vertex.
Left-click on the first vertex	Completes the polygon graphic sketch.

Creating polygon graphics with predefined shapes

The following keyboard shortcuts apply when creating polygon graphics with predefined shapes.

Gesture	Action
Left-click+Drag	Creates a rectangle graphic with dimensions based on the bounding box between initial click and cursor location. Creates a circle graphic with radius based on the distance between initial click and cursor location.
Ctrl+Left-click+Drag	Changes the shape from a rectangle to a square or from a circle to an ellipse.
Alt+Left-click+Drag	Creates a rectangle graphic with a center at initial click, and dimensions based on the distance between the initial click to the cursor location. Creates a circle graphic with a radius based on the bounding box between the initial click and the cursor location.
Ctrl+Alt+Left-click+Drag	Combines the behavior described above.

Updating graphics

The Sketch widget provides users with the ability to move, rotate, scale or reshape graphics during an update operation. To begin updating, Left-click on a graphic. Use Shift+Left-click to add more graphics to the current selection, for bulk updating. Once graphics are selected, the following actions can be performed.

Gesture	Action	Example
Left-click a graphic	Select a graphic to move, rotate or scale.
Shift+Left-click graphics	Select multiple graphics to move, rotate or scale.
Drag the graphic	Move the graphic.
Drag the graphic by rotate handle	Rotate the graphic.
Drag the graphic by scale handle	Scale the graphic.
Z	Incrementally undo actions recorded in the stack.
R	Incrementally redo actions recorded in the stack.
Left-click on view (not the graphic)	Complete the graphic update.

The following update operations can be performed on a single graphic.

Gesture	Action	Example
Left-click the graphic	Select the graphic to move or reshape.
Drag the graphic	Move the graphic.
Left-click on a ghost vertex	Add a new vertex.
Left-click on a vertex	Select a vertex.
Ctrl+Left-click on vertices	Select or unselect multiple vertices.
Drag the selected vertex	Move a vertex or vertices.
Right-click on a vertex	Delete a vertex.
Select multiple vertices and press Backspace or Delete button	Delete multiple vertices.

See also:

• Sketch

• Sketch.scss

• Sample - Sketch temporary geometries

• Sample - Sketch update validation

• Sample - Query statistics by geometry

Example:

// Create a new SketchViewModel and set
// its required parameters
var sketchVM = new SketchViewModel({
  layer: tempGraphicsLayer,
  view: view
});

// Listen to sketchViewModel's create event.
sketchVM.on("create", function(event) {
  // check if the create event's state has changed to complete indicating
  // the graphic create operation is completed.
  if (event.state === "complete") {
    // remove the graphic from the layer. Sketch adds
    // the completed graphic to the layer by default.
    polygonGraphicsLayer.remove(event.graphic);

    // use the graphic.geometry to query features that intersect it
    selectFeatures(event.graphic.geometry);
  }
});

Constructors

new SketchViewModel(properties)

Parameter:

properties Object optional See the properties for a list of all the properties that may be passed into the constructor.

Example:

// Typical usage
var sketch = new SketchViewModel({
  view: view,
  layer: graphicsLayer
});

Property Overview

Property Details

activeToolStringreadonly

Since: ArcGIS API for JavaScript 4.10

Returns the name of the active tool associated with the SketchViewModel instance.

Possible Values: point | multipoint | polyline | polygon | circle | rectangle | move | transform | reshape

createGraphicGraphicreadonly

Since: ArcGIS API for JavaScript 4.10

The graphic that is being created.

declaredClassStringreadonly inherited

Since: ArcGIS API for JavaScript 4.7

The name of the class. The declared class name is formatted as esri.folder.className.

defaultUpdateOptionsObjectreadonly

Since: ArcGIS API for JavaScript 4.10

Default update options set for the SketchViewModel. Update options set on this property will be overwritten if the update options are changed when update() method is called.

Properties:

tool String optional Name of the update tool. The default tool is move for graphics with point and multipoint geometries and transform for graphics with polygon and polyline geometries.

enableRotation Boolean optional Default Value:true Indicates if the rotation operation will be enabled when updating graphics.

enableScaling Boolean optional Default Value:true Indicates if the scale operation will be enabled when updating graphics.

preserveAspectRatio Boolean optional Default Value:false Indicates if the uniform scale operation will be enabled when updating graphics. enableScaling must be set true when setting this property to true.

toggleToolOnClick Boolean optional Default Value:true Indicates if the graphic being updated can be toggled between transform and reshape update options.

layerGraphicsLayer

Since: ArcGIS API for JavaScript 4.6

The GraphicsLayer associated with the SketchViewModel. The SketchViewModel adds new graphics to this layer or can only update graphics stored in this layer.

pointSymbolSimpleMarkerSymbol

A simple marker symbol used for representing the point geometry that is being drawn.

The default value is the following:

{
  type: "simple-marker",
  style: "circle",
  size: 6,
  color: [255, 255, 255],
  outline: {
   color: [50, 50, 50],
    width: 1
  }
}

polygonSymbolSimpleFillSymbol

A simple fill symbol used for representing the polygon geometry that is being drawn.

The default value is the following:

{
  type: "simple-fill",
  color: [150, 150, 150, 0.2],
  outline: {
   color: [50, 50, 50],
    width: 2
  }
}

polylineSymbolSimpleLineSymbol

A simple line symbol used for representing the polyline geometry that is being drawn.

The default value is the following:

{
  type: "simple-line",
  color: [130, 130, 130],
  width: 2
}

stateStringreadonly

The sketch view model's state.

Possible Values: ready | disabled | active

updateGraphicsCollection<Graphic>readonly

Since: ArcGIS API for JavaScript 4.10

An array of graphics that are being updated by the SketchViewModel.

updateOnGraphicClickBoolean

Since: ArcGIS API for JavaScript 4.10

Indicates if a graphic can be selected to be updated. If false, graphics cannot selected to be updated. Set this property to false to add a custom hitTest logic for updating graphics.

viewMapView

The view in which geometries will be sketched by the user.

Method Overview

Method Details

cancel()

Since: ArcGIS API for JavaScript 4.10

Cancels the active operation and fires the create or update event and changes the event's state to cancel.

complete()

Since: ArcGIS API for JavaScript 4.6

Completes the active operation and fires the create or update event and changes the event's state to complete. If called in midst of create operation, complete() finishes the active create operation and keeps the valid geometry.

create(tool, createOptions)

Create a graphic with a geometry specified in tool parameter. When first vertex of the graphic is added, create event will start firing.

Note: Creating a circle geometry does not work in all spatial references.

Parameters:

tool String Name of the create tool. Specifies the geometry type for the graphic to be created. Possible Values: point | multipoint | polyline | polygon | rectangle | circle

createOptions Object optional Options for the graphic to be created. Specification: mode String optional Specifies how the graphic can be created. The create mode applies only when creating polygon, polyline, rectangle and circle geometries. Possible Values: Value Description hybrid Vertices are added while the pointer is clicked or dragged. Applies to and is the default for polygon and polyline. freehand Vertices are added while the pointer is dragged. Applies to polygon, polyline rectangle and circle. Default for rectangle and circle. click Vertices are added when the pointer is clicked.

Example:

// Call create method to create a polygon with freehand option.
sketchVM.create("polygon", {mode: "freehand"});

* // listen to create event, only respond when event's state changes to complete
sketchVM.on("create", function(event) {
  if (event.state === "complete") {
    // remove the graphic from the layer associated with the sketch widget
    // instead use the polygon that user created to query features that
    // intersect it.
    polygonGraphicsLayer.remove(event.graphic);
    selectFeatures(event.graphic.geometry);
  }
});

emit(type, event)

Emits an event on the instance. This method should only be used when creating subclasses of this class.

Parameters:

type String The name of the event.

event Object optional The event payload.

hasEventListener(type){Boolean}

Indicates whether there is an event listener on the instance that matches the provided event name.

Parameter:

type String The name of the event.

Returns:

Type	Description
Boolean	Returns true if the class supports the input event.

on(type, listener){Object}

Registers an event handler on the instance. Call this method to hook an event with a listener.

Parameters:

type String The name of event to listen for.

listener Function The function to call when the event is fired.

Returns:

Type	Description
Object	Returns an event handler with a remove() method that can be called to stop listening for the event. Property Type Description remove Function When called, removes the listener from the event.

See also:

• dojo/on

Example:

view.on("click", function(event){
  // event is the event handle returned after the event fires.
  console.log(event.mapPoint);
});

redo()

Since: ArcGIS API for JavaScript 4.9

Incrementally redo actions recorded in the stack. Calling this method will fire the redo event.

reset()

Resets SketchViewModel to prepare for another create operation. Reset discards the current sketch, if called in middle of create operation.

undo()

Since: ArcGIS API for JavaScript 4.9

Incrementally undo actions recorded in the stack. Calling this method will fire the undo event.

update(graphics, updateOptions)

Since: ArcGIS API for JavaScript 4.10

Initializes an update operation for the specified graphic(s) and fires update event.

Parameters:

Specification:

graphics Graphic[] An array of graphics to be updated. Only graphics added to SketchViewModel's layer property can be updated.

updateOptions Object optional Update options for the graphics to be updated. Specification: tool String optional Name of the update tool. Specifies the update operation for the selected graphics. Possible Values: Value Description transform The default tool for graphics with polygon and polyline geometries. It allows one or multiple graphics to be scaled, rotated and moved by default. Its default behavior can be changed by setting enableRotation, enableScaling or preserveAspectRatio properties when calling update method or setting them on defaultUpdateOptions property when the widget initializes. This tool does not apply if selected graphics have only point or multipoint geometries. reshape It allows the entire graphic or individual vertices of the graphic to be moved. Vertices can be added or removed. This tool can only be used with one graphic and the graphic's geometry has to be polygon or polyline. move The default tool for graphics with point and multipoint geometries. It should be used for specific cases where you just want to move selected polygon and polyline graphics without additional options. Additionally, the move tool does not support toggling to different modes, since move operation is already built into both transform and reshape tools by default. enableRotation Boolean optional Default Value: true Indicates if the rotation operation will be enabled when updating graphics. Only applies if tool is transform. enableScaling Boolean optional Default Value: true Indicates if the scale operation will be enabled when updating graphics. Only applies if tool is transform. preserveAspectRatio Boolean optional Default Value: false Indicates if the uniform scale operation will be enabled when updating graphics. enableScaling must be set true when setting this property to true. Only applies if tool is transform. toggleToolOnClick Boolean optional Default Value: true Indicates if the graphic being updated can be toggled between transform and reshape update options.

Examples:

// start update operation for the selected graphic
// with transform tool. Only allow uniform scaling operation.
sketchVM.update([selectedGraphic], {
  tool: "transform",
  enableRotation: false,
  enableScaling: true,
  preserveAspectRatio: true,
  toggleToolOnClick: false
});

// Listen to sketch's update event to validate graphic's
// location while it is being reshaped or moved
sketchViewModel.on("update", onGraphicUpdate);
function onGraphicUpdate(event) {
  // get the graphic as it is being updated
  const graphic = event.graphics[0];
  // check if the graphic is intersecting school buffers
  intersects = geometryEngine.intersects(buffers, graphic.geometry);

  // change the graphic symbol to valid or invalid symbol
  // depending the graphic location
  graphic.symbol = (intersects) ? invalidSymbol : validSymbol

  // check if the update event's the toolEventInfo.type is move-stop or reshape-stop
  // user finished moving or reshaping the graphic, call complete method.
  // This changes update event state to complete.
  const toolType = event.toolEventInfo.type;
  if (event.toolEventInfo && (toolType === "move-stop" || toolType === "reshape-stop")) {
    if (!intersects) {
      sketchViewModel.complete();
    }
  } else if ((event.state === "cancel" || event.state === "complete")) {
      // graphic update has been completed or cancelled
      // if the graphic is in a bad spot, call sketch's update method again
      // giving user a chance to correct the location of the graphic
      if ((!contains) || (intersects)) {
        sketchViewModel.update({
          tool: "reshape",
          graphics: [graphic],
          toggleToolOnClick: false
        });
      }
  }
}

Event Overview

{graphic: Graphic,state: String,tool: String,toolEventInfo: CreateToolEventInfo,type: String}

{graphics: Graphic[],tool: String,type: String}

{graphics: Graphic[],tool: String,type: String}

{graphics: Graphic[],state: String,tool: String,toolEventInfo: UpdateToolEventInfo}

Event Details

create

Since: ArcGIS API for JavaScript 4.10

Fires when a user starts sketching a graphic, is actively sketching a graphic and completes sketching a graphic.

Properties:

graphic Graphic The graphic that is being created.

state String The current state of the event. Possible Values: Value Description start State changes to start when the first vertex is created. Not applicable when creating points. active State is active while graphic is being created. Not applicable when creating points. complete State changes to complete after the complete() method is called, when the user double clicks, presses the C key or clicks the first vertex of the polygon while creating a graphic. When point is created, the create event is fired with the complete state. cancel State changes to cancel if the create() or reset() methods are called during the create operation and before the state changes to complete.

tool String Name of the create tool. Possible Values: point | multipoint | polyline | polygon | rectangle | circle

toolEventInfo CreateToolEventInfo Returns additional information associated with the create operation such as where the user is clicking the view or where the user is moving the cursor to. Value of this parameter changes to null when the create event's state changes to complete or cancel.

type String The type of the event. For this event, the type is always create.

Example:

// Listen to sketch widget's create event.
sketchVM.on("create", function(event) {
  // check if the create event's state has changed to complete indicating
  // the graphic create operation is completed.
  if (event.state === "complete") {
    // remove the graphic from the layer. Sketch adds
    // the completed graphic to the layer by default.
    polygonGraphicsLayer.remove(event.graphic);

    // use the graphic.geometry to query features that intersect it
    selectFeatures(event.graphic.geometry);
  }
});

redo

Since: ArcGIS API for JavaScript 4.10

Fires in response to redo action during creation of a new graphic or updating existing graphics.

Properties:

graphics Graphic[] An array of graphics that are being updated or created.

tool String Name of the create or update tool that is active. Possible Values: point | multipoint | polyline | polygon | rectangle | circle | move | transform | reshape

type String The type of the event. For this event, the type is always redo.

undo

Since: ArcGIS API for JavaScript 4.10

Fires in response to undo action during creation of a new graphic or updating existing graphics.

Properties:

graphics Graphic[] An array of graphics that are being updated or created.

tool String Name of the create or update tool that is active. Possible Values: point | multipoint | polyline | polygon | rectangle | circle | move | transform | reshape

type String The type of the event. For this event, the type is always undo.

update

Since: ArcGIS API for JavaScript 4.10

Fires when the user starts updating graphics, is actively updating graphics, and completes updating graphics.

Properties:

graphics Graphic[] An array of graphics that are being updated.

state String The state of the event. Possible Values: Value Description start State changes to start when a graphic is selected to be updated. active State is active while graphics are being updated and toolEventInfo parameter is not null. complete State changes to complete after graphics are updated. cancel State changes to cancel when graphics are selected and then unselected without any updates, or when the update, create or reset method is called before the update event's state changes to complete.

tool String Name of the update operation tool. Possible Values: move | transform | reshape

toolEventInfo UpdateToolEventInfo Update operation tool info. Returns additional information associated with the update operation that is taking place for selected graphics and what stage it is at. Value of this parameter changes to null when the update event's state changes to complete.

Example:

// Listen to SketchViewModel's update event to show relevant data in a chart
// as the graphics are being moved
sketchViewModel.on("update", onMove);

// Point graphics at the center and edge of the buffer polygon are being moved.
// Recalculate the buffer with updated geometry and run the query stats using
// the updated buffer and update the chart.
function onMove(event) {
  // If the edge graphic is moving, keep the center graphic
  // at its initial location. Only move edge graphic to resize the buffer.
  if (event.toolEventInfo && event.toolEventInfo.mover.attributes.edge) {
    const toolType = event.toolEventInfo.type;
    if (toolType === "move-start") {
      centerGeometryAtStart = centerGraphic.geometry;
    }
    // keep the center graphic at its initial location when edge point is moving
    else if (toolType === "move" || toolType === "move-stop") {
      centerGraphic.geometry = centerGeometryAtStart;
    }
  }

  // the center or edge graphic is being moved, recalculate the buffer
  const vertices = [
    [centerGraphic.geometry.x, centerGraphic.geometry.y],
    [edgeGraphic.geometry.x, edgeGraphic.geometry.y]
  ];

  // client-side stats query of features that intersect the buffer
  calculateBuffer(vertices);

  // user is clicking on the view... call update method with the center and edge graphics
  if ((event.state === "cancel" || event.state === "complete")) {
    sketchViewModel.update({
      tool: "move",
      graphics: [edgeGraphic, centerGraphic]
    });
  }
}