SketchViewModel

require(["esri/widgets/Sketch/SketchViewModel"], function(SketchViewModel) { /* code goes here */ });
Class: esri/widgets/Sketch/SketchViewModel
Inheritance: SketchViewModel Accessor
Since: ArcGIS API for JavaScript 4.5

SketchViewModel simplifies the process of adding temporary geometries to the MapView. It saves the effort of writing lots of code for sketching different geometry types. SketchViewModel is intended for basic usage, without advanced features such as preventing self-intersecting lines or overlapping polygons. If more control is required for creating temporary geometries, then use the Draw class instead.

SketchViewModel provides the logic for Sketch widget, which will be added in a future release. The Sketch widget will simplify the process of adding temporary geometries to the view with minimal code.

Pointer and keyboard gestures for drawing different geometries are described in the tables below.

Sketching points

GestureAction
Left-clickAdds a point at the pointer location.
CAdds a point at the pointer location.

Sketching multipoints

GestureAction
Left-clickAdds a point at the pointer location.
FAdds a point to the multipoint.
CCompletes the multipoint sketch.
ZIncrementally undo actions recorded in the stack.
RIncrementally redo actions recorded in the stack.

Sketching polylines and polygons

GestureAction
Left-clickAdds a vertex at the pointer location.
Left-dragAdds a vertex for each pointer move.
FAdds a vertex to the polyline or polygon.
CCompletes the polyline or polygon sketch.
ZIncrementally undo actions recorded in the stack.
RIncrementally redo actions recorded in the stack.
Ctrl+Left-click or dragForces new vertices to be parallel or perpendicular to the previous vertex
Left-click on the first vertexCompletes the polygon sketch.

Sketching predefined shapes

The following keyboard shortcuts apply when drawing predefined shapes.

GestureAction
Left-click+DragDraws rectangles or circles.
Ctrl+Left-click+DragChanges the shape of the sketch: Rectangle to square or circle to ellipse.
Alt+Left-click+DragCreates a sketch with a center based on initial click, with dimensions calculated based on distance from cursor to center.
Ctrl+Alt+Left-click+DragChanges the shape of the sketch and center to be the initial click location with dimensions based on distance from cursor to center.

Updating geometries

Geometries added by the SketchViewModel can be updated by moving the whole geometry, or moving one or more vertices. To update a geometry, left-click on the geometry and the following actions can be performed.

GestureActionExample
Drag the geometryMove the geometry.Drag a Geometry
Left-click on a vertexSelect a vertex.Select a Vertex
Shift+Left-click on verticesSelect or unselect multiple vertices.Select Vertices
Drag a selected vertexMove a vertex or vertices.Drag vertices
Left-click on view (not on the geometry)Complete the geometry update. If geometry is updated, update-complete event will be fired. If not, update-cancel will be fired.Sketch Update Complete
See also:
Example:
// create a new sketch view model and
// assign symbols for each geometry type
var sketch = new SketchViewModel({
  view: view,
  layer: tempGraphicsLayer,
  pointSymbol: {
    type: "simple-marker",  // autocasts as new SimpleMarkerSymbol()
    style: "square",
    color: "red",
    size: "16px",
    outline: {  // autocasts as new SimpleLineSymbol()
      color: [255, 255, 0],
      width: 3
    }
  },
  polylineSymbol: {
    type: "simple-line",  // autocasts as new SimpleMarkerSymbol()
    color: "#8A2BE2",
    width: "4",
    style: "dash"
  },
  polygonSymbol: {
    type: "simple-fill",  // autocasts as new SimpleMarkerSymbol()
    color: "rgba(138,43,226, 0.8)",
    style: "solid",
    outline: { // autocasts as new SimpleLineSymbol()
      color: "white",
      width: 1
    }
  }
});

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
});

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
NameTypeSummaryClass
String

The name of the class.

more details
more detailsAccessor
Graphic

Graphic representing the temporary geometry that is being drawn on the view.

more details
more detailsSketchViewModel
GraphicsLayer

GraphicsLayer associated with the SketchViewModel.

more details
more detailsSketchViewModel
SimpleMarkerSymbol

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

more details
more detailsSketchViewModel
SimpleFillSymbol

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

more details
more detailsSketchViewModel
SimpleLineSymbol

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

more details
more detailsSketchViewModel
String

The view model's state.

more details
more detailsSketchViewModel
MapView

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

more details
more detailsSketchViewModel

Property Details

declaredClassStringreadonly inherited
Since: ArcGIS API for JavaScript 4.7

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

graphicGraphicreadonly

Graphic representing the temporary geometry that is being drawn on the view.

Since: ArcGIS API for JavaScript 4.6

GraphicsLayer associated with the SketchViewModel. It allows you to organize where temporary graphics are placed when the drawing is completed.

Example:
sketchViewModel.on("draw-complete", function (evt) {
  // add the completed graphic to the temporary graphics layer
  tempGraphicsLayer.add(evt.graphic);
});

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

polygonSymbolSimpleFillSymbol

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

polylineSymbolSimpleLineSymbol

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

stateStringreadonly

The view model's state.

Known Values: ready | disabled

Default Value:disabled

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

Method Overview

NameReturn TypeSummaryClass

Completes the active drawing and fires the draw-complete event.

more details
more detailsSketchViewModel

Creates an instance of the requested draw action type.

more details
more detailsSketchViewModel

Emits an event on the instance.

more details
more detailsSketchViewModel
Boolean

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

more details
more detailsSketchViewModel
Object

Registers an event handler on the instance.

more details
more detailsSketchViewModel

Resets SketchViewModel to prepare for another create operation.

more details
more detailsSketchViewModel

Starts an update operation for the selected geometry and fires update-start event.

more details
more detailsSketchViewModel

Method Details

complete()
Since: ArcGIS API for JavaScript 4.6

Completes the active drawing and fires the draw-complete event. If called mid-drawing, complete() finishes the active drawing and keeps the valid geometry.

create(drawAction, drawOptions)

Creates an instance of the requested draw action type. See the table below for a list of known values and type of draw action it creates.

Known Values: point | multipoint | polyline | polygon | rectangle | circle

Geometry typeDraw action instance
pointPointDrawAction
multipointMultipointDrawAction
polylinePolylineDrawAction
polygonPolygonDrawAction
rectangle/square, circle/ellipseSegmentDrawAction

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

Parameters:
drawAction String

Name of the draw action tool.

drawOptions Object

Object of the drawing options for the geometry to be created.

Specification:
mode String
optional
Default Value: hybrid

The drawing mode. The drawing mode only applies when creating polygon and polyline geometries.

Known Values:

ValueDescription
hybridVertices are added while the pointer is clicked or dragged.
freehandVertices are added while the pointer is dragged.
clickVertices are added when the pointer is clicked.
Example:
// create a new instance of sketch view model
// and associate it with a map view.
var sketch = new SketchViewModel({
  view: view
});

// set up the SketchViewModel to create polygon geometries
sketch.create("polygon", {mode: "freehand"});
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

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:
TypeDescription
BooleanReturns 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:
TypeDescription
ObjectReturns an event handler with a remove() method that can be called to stop listening for the event.
PropertyTypeDescription
removeFunctionWhen called, removes the listener from the event.
See also:
Example:
view.on("click", function(event){
  // event is the event handle returned after the event fires.
  console.log(event.mapPoint);
});
reset()

Resets SketchViewModel to prepare for another create operation. Reset discards the current drawing, if called mid drawing.

update(geometry)
Since: ArcGIS API for JavaScript 4.7

Starts an update operation for the selected geometry and fires update-start event.

Parameter:
geometry Geometry

The geometry to be updated.

Event Overview

NameTypeSummaryClass
{tool: String}

Fires if create() or reset() method is called after draw-start event is fired and before draw-complete event is fired.

more details
more detailsSketchViewModel
{geometry: Geometry}

Fires after complete() method is called.

more details
more detailsSketchViewModel
{tool: String}

Fires after create() method is called.

more details
more detailsSketchViewModel
{geometry: Geometry}

Fires when geometry is selected and then unselected without any updates, or when create() or reset() is called before update-complete event is fired.

more details
more detailsSketchViewModel
{geometry: Geometry}

Fires after user finishes updating a geometry.

more details
more detailsSketchViewModel
{geometry: Geometry}

Fires after user clicks on a geometry to update or when update() method is called.

more details
more detailsSketchViewModel

Event Details

draw-cancel
Since: ArcGIS API for JavaScript 4.7

Fires if create() or reset() method is called after draw-start event is fired and before draw-complete event is fired.

Property:
tool String

The action tool selected in the create() method.

Known Values: point | polyline | polygon | rectangle | circle

draw-complete

Fires after complete() method is called. The sketch can be completed when user double clicks, presses the C key or click the first vertex of the polygon while sketching.

Property:
geometry Geometry

The geometry completed by the sketch view model.

Example:
sketch.on("draw-complete", function (evt) {
  // get the graphic representing the completed
  // geometry and add it to the view.
  view.graphics.add(new Graphic({geometry:evt.geometry, symbol:symbol})
});
draw-start
Since: ArcGIS API for JavaScript 4.7

Fires after create() method is called.

Property:
tool String

The action tool selected in the create() method.

Known Values: point | polyline | polygon | rectangle | circle

update-cancel
Since: ArcGIS API for JavaScript 4.7

Fires when geometry is selected and then unselected without any updates, or when create() or reset() is called before update-complete event is fired.

Property:
geometry Geometry

The geometry selected to be updated.

update-complete
Since: ArcGIS API for JavaScript 4.7

Fires after user finishes updating a geometry.

Property:
geometry Geometry

The updated geometry.

update-start
Since: ArcGIS API for JavaScript 4.7

Fires after user clicks on a geometry to update or when update() method is called.

Property:
geometry Geometry

The geometry selected to be updated.

Searching...

API Reference search results

NameTypeModule

There were no match results from your search criteria.