Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: Draw

dojo.require("esri.toolbars.draw");

Description

(Added at v1.0)
Toolbar that supports functionality to create new geometries by drawing them: points (POINT or MULTI_POINT), lines (LINE, POLYLINE, or FREEHAND_POLYLINE), polygons (FREEHAND_POLYGON or POLYGON), or rectangles (EXTENT). To edit geometries of existing graphics, use the Edit Toolbar.

Mouse behavior when drawing features
  • For POINT, click to add a point.
  • For MULTI_POINT, click to add points, double-click to add the last point of the multi-point.
  • For POLYLINE and POLYGON, click to add vertices, double-click to add the last vertex.
  • For FREEHAND_POLYLINE and FREEHAND_POLYGON, press mouse down where to start, draw the feature, then let go when finished drawing.
  • For LINE, EXTENT, press mouse down where to start and let go where to end the feature.
The default text strings used by the draw toolbar can be modified by setting the values to a new string in your application. For example, in the code snippet below the text for the tooltip that appears when new points are added is modified:
 esri.bundle.toolbars.draw.addPoint = "Add a new tree to the map";
To view all the customizable widget strings view any of the samples in a browser with debugging tools open and type console.dir(esri.bundle) in the console. Debugging tools are available as an integrated part of most modern browsers.

Samples

Search for samples that use this class.

Constructors

NameSummary
new esri.toolbars.Draw(map, options?)Creates a new Draw object.

Constants

NameDescription
ARROWDraws an arrow.
CIRCLEDraws a circle.
DOWN_ARROWDraws an arrow that points down.
ELLIPSEDraws an ellipse.
EXTENTDraws an extent box.
FREEHAND_POLYGONDraws a freehand polygon.
FREEHAND_POLYLINEDraws a freehand polyline.
LEFT_ARROWDraws an arrow that points left.
LINEDraws a line.
MULTI_POINTDraws a Multipoint.
POINTDraws a point.
POLYGONDraws a polygon.
POLYLINEDraws a polyline.
RECTANGLEDraws a rectangle.
RIGHT_ARROWDraws an arrow that points right.
TRIANGLEDraws a triangle.
UP_ARROWDraws an arrow that points up.

Properties

NameTypeSummary
fillSymbolSimpleFillSymbolSymbol to be used when drawing a Polygon or Extent.
lineSymbolSimpleLineSymbolSymbol to be used when drawing a Polyline.
markerSymbolSimpleMarkerSymbolSymbol to be used when drawing a Point or Multipoint.
respectDrawingVertexOrderBooleanWhen set to false, the geometry is modified to be topologically correct.

Methods

NameReturn typeSummary
activate(geometryType, options?)NoneActivates the toolbar for drawing geometries.
deactivate()NoneDeactivates the toolbar and reactivates map navigation.
finishDrawing()NoneFinishes drawing the geometry and fires the onDrawEnd event.
setFillSymbol(fillSymbol)NoneSets the fill symbol.
setLineSymbol(lineSymbol)NoneSets the line symbol.
setMarkerSymbol(markerSymbol)NoneSets the marker symbol.
setRespectDrawingVertexOrder(set)NoneSets whether the polygon geometry should be modified to be topologically correct.

Events

[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.

Events

NameEvent ObjectSummary
draw-complete
{
  geographicGeometry: <Geometry>,
  geometry: <Geometry>
}
Fired when the user has completed drawing.
draw-end
{
  geometry: <Geometry>
}
This event is deprecated. Use draw-complete instead.
Constructor Details

new esri.toolbars.Draw(map, options?)

Creates a new Draw object. A map is a required parameter.
Parameters:
<Map> map Required Map the toolbar is associated with.
<Object> options Optional Parameters that define the functionality of the draw toolbar. See the options for a list of valid values.
options properties:
<Number> drawTime Optional Determines how much time to wait before adding a new point when using a freehand tool. The default value is 75.
<Boolean> showTooltips Optional If true, tooltips are displayed when creating new graphics with the draw toolbar.
require([
  "esri/map", "esri/toolbars/draw", ... 
], function(Map, Draw, ... ) {
  var map = new Map( ... );
  var toolbar = new Draw(map, { showTooltips: false });
  ...
});
<Number> tolerance Optional Determines how far the mouse moves before adding a new point when using one of the freehand tools. The default value is 8.
<Number> tooltipOffset Optional Determines how far to offset the tool tip from the mouse pointer. The default value is 15.
Sample:
  toolbar = new esri.toolbars.Draw(map, {
    tooltipOffset:20,
    drawTime:90
  });
Property Details

<SimpleFillSymbol> fillSymbol

Symbol to be used when drawing a Polygon or Extent.
See also: setFillSymbol()

<SimpleLineSymbol> lineSymbol

Symbol to be used when drawing a Polyline.
See also: setLineSymbol()

<SimpleMarkerSymbol> markerSymbol

Symbol to be used when drawing a Point or Multipoint.

<Boolean> respectDrawingVertexOrder

When set to false, the geometry is modified to be topologically correct. When set to true, the input geometry is not modified.
Known values: true | false
Default value: false
Method Details

activate(geometryType, options?)

Activates the toolbar for drawing geometries. Activating the toolbar disables map navigation.
Parameters:
<String> geometryType Required The type of geometry drawn. See the Constants table for valid values.
<Object> options Optional Options that define the functionality of the draw toolbar. See the object specifications table below for the structure of the options object.
Object Specifications:
<options>
<Number> drawTime Required Determines how much time to wait before adding a new point when using a freehand tool. The default value is 75.
<Boolean> showTooltips Required If true, tooltips are displayed when creating new graphics with the draw toolbar. The default value is true.
<Number> tolerance Required Determines how far the mouse moves before adding a new point when using one of the freehand tools. The default value is 8.
<Number> tooltipOffset Required Determines how far to offset the tool tip from the mouse pointer. The default value is 15.
Sample:
toolbar.activate(esri.toolbars.Draw.POINT);
See also: deactivate()

deactivate()

Deactivates the toolbar and reactivates map navigation.
See also: activate()

finishDrawing()

Finishes drawing the geometry and fires the onDrawEnd event. Use this method to finish drawing a polyline, polygon or multipoint when working with the compact build on a touch supported device like the iPhone. (Added at v2.0)
Sample:

drawToolbar.finishDrawing();

See also: on("draw-end")

setFillSymbol(fillSymbol)

Sets the fill symbol.
Parameters:
<FillSymbol> fillSymbol Required The fill symbol.
See also: fillSymbol

setLineSymbol(lineSymbol)

Sets the line symbol.
Parameters:
<LineSymbol> lineSymbol Required The line symbol.
See also: lineSymbol

setMarkerSymbol(markerSymbol)

Sets the marker symbol.
Parameters:
<MarkerSymbol> markerSymbol Required The marker symbol.
See also: markerSymbol

setRespectDrawingVertexOrder(set)

Sets whether the polygon geometry should be modified to be topologically correct.
Parameters:
<Boolean> set Required When set to false, the geometry is modified to be topologically correct. When set to true, the input geometry is not modified.
Event Details
[ On Style Events | Connect Style Event ]

draw-complete

Fired when the user has completed drawing. It returns the geometry of the drawn feature with the feature's geographic coordinates. (Added at v3.6)
Event Object Properties:
<Geometry> geographicGeometry Geometry of the drawn shape in geographic coordinates (latitude, longitude). Only available when the map's spatial reference is Web Mercator or Geographic (4326).
<Geometry> geometry Geometry of the shape that was drawn. Coordinates of this geometry have the same spatial reference of the map.

draw-end

This event is deprecated. Use draw-complete instead. Fires when drawing has ended.
Event Object Properties:
<Geometry> geometry Geometry drawn on the client.
Sample:
require([
  "esri/toolbars/draw", "esri/graphic", ... 
], function(Draw, Graphic, ... ) {
  function createToolbar(map) {
    var toolbar = new Draw(map);
    toolbar.on("draw-end", addToMap);
  }
  function addToMap(evt) {
    var graphic = new Graphic(evt.geometry, symbol);
    map.graphics.add(graphic);
  }
  ...
});
See also: finishDrawing()