Leaflet Draw Documentation

## Leaflet Draw API reference

This documentation is has been transcribed from the original README.MD to jsdoc's or natural docs style for use with Leafdoc. If you identify a typo or have a suggestion for this documentation, please feel free toedit the js comment blocks in the src directory, build with 'jake docs' and submit a pull request.

## Leaflet 1.0+ Examples

- Full Demo
- Popup
- Snapping
- Edit Handlers

## Leaflet 0.7+ Examples

- Full Demo
- Popup
- Snapping
- Edit Handlers

## L.Draw

To add the draw toolbar set the option drawControl: true in the map options.

### Usage example

         var map = L.map('map', {drawControl: true}).setView([51.505, -0.09], 13);
         L.tileLayer('http://{s}.tile.osm.org/{z}/{x}/{y}.png', {
             attribution: '&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors'
         }).addTo(map);

### Adding the edit toolbar

To use the edit toolbar you must initialise the Leaflet.draw control and manually add it to the map.

         var map = L.map('map').setView([51.505, -0.09], 13);
         L.tileLayer('http://{s}.tile.osm.org/{z}/{x}/{y}.png', {
             attribution: '&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors'
         }).addTo(map);
         // FeatureGroup is to store editable layers
         var drawnItems = new L.FeatureGroup();
         map.addLayer(drawnItems);
         var drawControl = new L.Control.Draw({
             edit: {
                 featureGroup: drawnItems
             }
         });
         map.addControl(drawControl);

The key here is the featureGroup option. This tells the plugin which FeatureGroup contains the layers that should be editable. The featureGroup can contain 0 or more features with geometry types Point, LineString, and Polygon. Leaflet.draw does not work with multigeometry features such as MultiPoint, MultiLineString, MultiPolygon, or GeometryCollection. If you need to add multigeometry features to the draw plugin, convert them to a FeatureCollection of non-multigeometries (Points, LineStrings, or Polygons).

## L.drawLocal

The core toolbar class of the API — it is used to create the toolbar ui

### Usage example

         var modifiedDraw = L.drawLocal.extend({
             draw: {
                 toolbar: {
                     buttons: {
                         polygon: 'Draw an awesome polygon'
                     }
                 }
             }
         });

The default state for the control is the draw toolbar just below the zoom control. This will allow map users to draw vectors and markers. Please note the edit toolbar is not enabled by default.

## L.Draw.Toolbar

The toolbar class of the API — it is used to create the ui This will be depreciated

### Usage example

       var toolbar = L.Toolbar();
       toolbar.addToolbar(map);

### Disabling a toolbar

If you do not want a particular toolbar in your app you can turn it off by setting the toolbar to false.

         var drawControl = new L.Control.Draw({
             draw: false,
             edit: {
                 featureGroup: editableLayers
             }
         });

### Disabling a toolbar item

If you want to turn off a particular toolbar item, set it to false. The following disables drawing polygons and markers. It also turns off the ability to edit layers.

         var drawControl = new L.Control.Draw({
             draw: {
                 polygon: false,
                 marker: false
             },
             edit: {
                 featureGroup: editableLayers,
                 edit: false
             }
         });

### Methods

#### Methods for modifying the toolbar

Method | Returns | Description
--- | --- | ---
`initialize(options)` | `void` | Toolbar constructor
`enabled()` | `boolean` | Gets a true/false of whether the toolbar is enabled
`disable()` | `void` | Disables the toolbar
`addToolbar(map)` | `L.DomUtil` | Adds the toolbar to the map and returns the toolbar dom element
`removeToolbar()` | `void` | Removes the toolbar and drops the handler event listeners

## L.Draw.Event

Use `L.Draw.Event.EVENTNAME` constants to ensure events are correct.

### Usage example

    map.on(L.Draw.Event.CREATED; function (e) {
       var type = e.layerType;
           layer = e.layer;
       if (type === 'marker') {
           // Do marker specific actions
       }
       // Do whatever else you need to. (save to db; add to map etc)
       map.addLayer(layer);
    });

         map.on('draw:edited'; function (e) {
             var layers = e.layers;
             layers.eachLayer(function (layer) {
                 //do whatever you want; most likely save back to db
             });
         });

### Events

Event | Data | Description
--- | --- | ---
`draw:created` | `PolyLine` | Polygon; Rectangle; Circle; Marker | String Layer that was just created. The type of layer this is. One of: `polyline`; `polygon`; `rectangle`; `circle`; `marker` Triggered when a new vector or marker has been created.
`draw:edited` | `LayerGroup` | List of all layers just edited on the map. Triggered when layers in the FeatureGroup; initialised with the plugin; have been edited and saved.
`draw:deleted` | `LayerGroup` | List of all layers just removed from the map. Triggered when layers have been removed (and saved) from the FeatureGroup.
`draw:drawstart` | `String` | The type of layer this is. One of:`polyline`; `polygon`; `rectangle`; `circle`; `marker` Triggered when the user has chosen to draw a particular vector or marker.
`draw:drawstop` | `String` | The type of layer this is. One of: `polyline`; `polygon`; `rectangle`; `circle`; `marker` Triggered when the user has finished a particular vector or marker.
`draw:drawvertex` | `LayerGroup` | List of all layers just being added from the map. Triggered when a vertex is created on a polyline or polygon.
`draw:editstart` | `String` | The type of edit this is. One of: `edit` Triggered when the user starts edit mode by clicking the edit tool button.
`draw:editmove` | `ILayer` | Layer that was just moved. Triggered as the user moves a rectangle; circle or marker.
`draw:editresize` | `ILayer` | Layer that was just moved. Triggered as the user resizes a rectangle or circle.
`draw:editvertex` | `LayerGroup` | List of all layers just being edited from the map. Triggered when a vertex is edited on a polyline or polygon.
`draw:editstop` | `String` | The type of edit this is. One of: `edit` Triggered when the user has finshed editing (edit mode) and saves edits.
`draw:deletestart` | `String` | The type of edit this is. One of: `remove` Triggered when the user starts remove mode by clicking the remove tool button.
`draw:deletestop` | `String` | The type of edit this is. One of: `remove` Triggered when the user has finished removing shapes (remove mode) and saves.

## L.Draw.Feature

### Methods

Method | Returns | Description
--- | --- | ---
`initialize()` | `void` |
`enable()` | `void` | Enables this handler
`addHooks()` | `void` | Add's event listeners to this handler
`removeHooks()` | `void` | Removes event listeners from this handler
`setOptions(object)` | `void` | Sets new options to this handler

## L.Draw.SimpleShape

### Methods

Method | Returns | Description
--- | --- | ---
`initialize()` | `void` |
`addHooks()` | `void` |
`removeHooks()` | `void` |

▶ Methods inherited from L.Draw.Feature

Method | Returns | Description
--- | --- | ---
`enable()` | `void` | Enables this handler
`setOptions(object)` | `void` | Sets new options to this handler

## L.Draw.Marker

### Methods

Method | Returns | Description
--- | --- | ---
`initialize()` | `void` |
`addHooks()` | `void` |
`removeHooks()` | `void` |

▶ Methods inherited from L.Draw.Feature

Method | Returns | Description
--- | --- | ---
`enable()` | `void` | Enables this handler
`setOptions(object)` | `void` | Sets new options to this handler

## L.Draw.Circle

### Methods

Method | Returns | Description
--- | --- | ---
`initialize()` | `void` |

▶ Methods inherited from L.Draw.SimpleShape

Method | Returns | Description
--- | --- | ---
`addHooks()` | `void` |
`removeHooks()` | `void` |

▶ Methods inherited from L.Draw.Feature

Method | Returns | Description
--- | --- | ---
`enable()` | `void` | Enables this handler
`setOptions(object)` | `void` | Sets new options to this handler

## L.Draw.Polyline

### Methods

Method | Returns | Description
--- | --- | ---
`initialize()` | `void` |
`addHooks()` | `void` |
`removeHooks()` | `void` |
`deleteLastVertex()` | `void` |
`addVertex()` | `void` |
`completeShape()` | `void` |

▶ Methods inherited from L.Draw.Feature

Method | Returns | Description
--- | --- | ---
`enable()` | `void` | Enables this handler
`setOptions(object)` | `void` | Sets new options to this handler

## L.Draw.Rectangle

### Methods

Method | Returns | Description
--- | --- | ---
`initialize()` | `void` |

▶ Methods inherited from L.Draw.SimpleShape

Method | Returns | Description
--- | --- | ---
`addHooks()` | `void` |
`removeHooks()` | `void` |

▶ Methods inherited from L.Draw.Feature

Method | Returns | Description
--- | --- | ---
`enable()` | `void` | Enables this handler
`setOptions(object)` | `void` | Sets new options to this handler

## L.Draw.Polygon

### Methods

Method | Returns | Description
--- | --- | ---
`initialize()` | `void` |

▶ Methods inherited from L.Draw.Polyline

Method | Returns | Description
--- | --- | ---
`addHooks()` | `void` |
`removeHooks()` | `void` |
`deleteLastVertex()` | `void` |
`addVertex()` | `void` |
`completeShape()` | `void` |

▶ Methods inherited from L.Draw.Feature

Method | Returns | Description
--- | --- | ---
`enable()` | `void` | Enables this handler
`setOptions(object)` | `void` | Sets new options to this handler

## L.Edit.SimpleShape

### Methods

Method | Returns | Description
--- | --- | ---
`intialize()` | `void` |
`addHooks()` | `void` |
`removeHooks()` | `void` |
`updateMarkers()` | `void` |

## L.Edit.Marker

### Methods

Method | Returns | Description
--- | --- | ---
`initialize()` | `void` |
`addHooks()` | `void` |
`removeHooks()` | `void` |

## L.Edit.Circle

### Methods

▶ Methods inherited from L.Edit.SimpleShape

Method | Returns | Description
--- | --- | ---
`intialize()` | `void` |
`addHooks()` | `void` |
`removeHooks()` | `void` |
`updateMarkers()` | `void` |

## L.Edit.Polyline

### Methods

Method | Returns | Description
--- | --- | ---
`initialize()` | `void` |
`addHooks()` | `void` |
`removeHooks()` | `void` |
`updateMarkers()` | `void` |

## L.Edit.Rectangle

### Methods

▶ Methods inherited from L.Edit.SimpleShape

Method | Returns | Description
--- | --- | ---
`intialize()` | `void` |
`addHooks()` | `void` |
`removeHooks()` | `void` |
`updateMarkers()` | `void` |

## L.EditToolbar.Edit

### Methods

Method | Returns | Description
--- | --- | ---
`intialize()` | `void` |
`enable()` | `void` |
`disable()` | `void` |
`addHooks()` | `void` |
`removeHooks()` | `void` |
`revertLayers()` | `void` |
`save()` | `void` |

## L.EditToolbar.Delete

### Methods

Method | Returns | Description
--- | --- | ---
`intialize()` | `void` |
`enable()` | `void` |
`disable()` | `void` |
`addHooks()` | `void` |
`removeHooks()` | `void` |
`revertLayers()` | `void` |
`save()` | `void` |

## L.GeometryUtil

### Methods

Method | Returns | Description
--- | --- | ---
`geodesicArea()` | `number` |
`readableArea()` | `string` |
`readableDistance(distance, isMetric, useFeet, isNauticalMile)` | `string` | Converts metric distance to distance string.

## L.LatLngUtil

### Methods

Method | Returns | Description
--- | --- | ---
`cloneLatLngs()` | `L.LatLngs[]` | Clone the latLng point or points or nested points and return an array with those points
`cloneLatLng(LatLng)` | `L.LatLng` | Clone the latLng and return a new LatLng object.

## L.LineUtil

### Methods

Method | Returns | Description
--- | --- | ---
`segmentsIntersect()` | `boolean` | Checks to see if two line segments intersect. Does not handle degenerate cases. http://compgeom.cs.uiuc.edu/~jeffe/teaching/373/notes/x06-sweepline.pdf

## L.Polygon

### Methods

Method | Returns | Description
--- | --- | ---
`intersects()` | `boolean` | Checks a polygon for any intersecting line segments. Ignores holes.

## L.Polyline

### Methods

Method | Returns | Description
--- | --- | ---
`intersects()` | `boolean` | Check to see if this polyline has any linesegments that intersect. NOTE: does not support detecting intersection for degenerate cases.
`newLatLngIntersects()` | `boolean` | Check for intersection if new latlng was added to this polyline. NOTE: does not support detecting intersection for degenerate cases.
`newPointIntersects()` | `boolean` | Check for intersection if new point was added to this polyline. newPoint must be a layer point. NOTE: does not support detecting intersection for degenerate cases.

## L.Map.TouchExtend

### Methods

Method | Returns | Description
--- | --- | ---
`initialize()` | `void` | Sets TouchExtend private accessor variables
`addHooks()` | `void` | Adds dom listener events to the map container
`removeHooks()` | `void` | Removes dom listener events from the map container

## L.Control.Draw

### Methods

Method | Returns | Description
--- | --- | ---
`initialize()` | `void` | Initializes draw control, toolbars from the options
`onAdd()` | `container` | Adds the toolbar container to the map
`onRemove()` | `void` | Removes the toolbars from the map toolbar container
`setDrawingOptions(options)` | `void` | Sets options to all toolbar instances

## L.Draw.Tooltip

The tooltip class — it is used to display the tooltip while drawing This will be depreciated

### Usage example

        var tooltip = L.Draw.Tooltip();

### Methods

#### Methods for modifying draw state

Method | Returns | Description
--- | --- | ---
`initialize(map)` | `void` | Tooltip constructor
`dispose()` | `void` | Remove Tooltip DOM and unbind events
`updateContent(labelText)` | `this` | Changes the tooltip text to string in function call
`updatePosition(latlng)` | `this` | Changes the location of the tooltip
`showAsError()` | `this` | Applies error class to tooltip
`removeError()` | `this` | Removes the error class from the tooltip

## L.DrawToolbar

### Methods

Method | Returns | Description
--- | --- | ---
`initialize()` | `void` |
`getModeHandlers()` | `void` |
`getActions()` | `void` |
`setOptions()` | `void` |

## L.EditToolbar

### Methods

Method | Returns | Description
--- | --- | ---
`intialize()` | `void` |
`getModeHandlers()` | `void` |
`getActions()` | `void` |
`addToolbar()` | `void` |
`removeToolbar()` | `void` |
`disable()` | `void` |

## L.Edit.PolyVerticesEdit

### Methods

Method | Returns | Description
--- | --- | ---
`intialize()` | `void` |
`addHooks()` | `void` |
`removeHooks()` | `void` |
`updateMarkers()` | `void` |

## L.Marker.Touch

This isn't full Touch support. This is just to get markers to also support dom touch events after creation

#TODO: find a better way of getting markers to support touch.

## Install

You have four methods of installing Leaflet.Draw, copy the leaflet.draw.js, css, and images from dist and embed directly into your application.

### npm

To install the plugin run `npm install leaflet-draw` via command line in your project. You must also require this in your project like so: `var leafletDraw = require('leaflet-draw');`

### bower

To install the plugin run `bower install leaflet-draw`.

### Builder

There is a custom builder at ../build/build.html to help make a custom package of Leaflet.Draw with the command line.

## CDN's

    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet.draw/0.4.2/leaflet.draw.css"/>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet.draw/0.4.2/leaflet.draw.js"></script>

## Options

You can configure the plugin by using the different options listed here. If you identify a typo or have a suggestion for this section of the documentation, please edit docs-misc.leafdoc in the build directory.

## Control.Draw

Option | Type | Default | Description
--- | --- | --- | ---
position | String | `'topleft'` | The initial position of the control (one of the map corners). See control positions.
draw | DrawOptions | `{}` | The options used to configure the draw toolbar.
edit | EditPolyOptions | `false` | The options used to configure the edit toolbar.

## DrawOptions

Option | Type | Default | Description
--- | --- | --- | ---
polyline | PolylineOptions | `{ }` | Polyline draw handler options. Set to `false` to disable handler.
polygon | PolygonOptions | `{ }` | Polygon draw handler options. Set to `false` to disable handler.
rectangle | RectangleOptions | `{ }` | Rectangle draw handler options. Set to `false` to disable handler.
circle | CircleOptions | `{ }` | Circle draw handler options. Set to `false` to disable handler.
marker | MarkerOptions | `{ }` | Marker draw handler options. Set to `false` to disable handler.

## PolylineOptions

Option | Type | Default | Description
--- | --- | --- | ---
allowIntersection | Bool | `true` | Determines if line segments can cross.
drawError | Object | See code | Configuration options for the error that displays if an intersection is detected.
guidelineDistance | Number | `20` | Distance in pixels between each guide dash.
shapeOptions | Leaflet Polyline options | See code | The options used when drawing the polyline/polygon on the map.
metric | Bool | `true` | Determines which measurement system (metric or imperial) is used.
zIndexOffset | Number | `2000` | This should be a high number to ensure that you can draw over all other layers on the map.
repeatMode | Bool | `false` | Determines if the draw tool remains enabled after drawing a shape.

## PolygonOptions

Option | Type | Default | Description
--- | --- | --- | ---
showArea | Bool | `false` | Show the area of the drawn polygon in m², ha or km². The area is only approximate and become less accurate the larger the polygon is.

## RectangleOptions

Option | Type | Default | Description
--- | --- | --- | ---
shapeOptions | Leaflet Path options | See code | The options used when drawing the rectangle on the map.
repeatMode | Bool | `false` | Determines if the draw tool remains enabled after drawing a shape.
showRadius | Bool | `true` | Show the area of the drawn circle in m², ha or km². The area is only approximate and become less accurate the larger the circle is.

## CircleOptions

Option | Type | Default | Description
--- | --- | --- | ---
shapeOptions | Leaflet Path options | See code | The options used when drawing the circle on the map.
repeatMode | Bool | `false` | Determines if the draw tool remains enabled after drawing a shape.

## MarkerOptions

Option | Type | Default | Description
--- | --- | --- | ---
icon | Leaflet Icon | `L.Icon.Default()` | The icon displayed when drawing a marker.
zIndexOffset | Number | `2000` | This should be a high number to ensure that you can draw over all other layers on the map.
repeatMode | Bool | `false` | Determines if the draw tool remains enabled after drawing a shape.

## EditPolyOptions

Option | Type | Default | Description
--- | --- | --- | ---
featureGroup | Leaflet FeatureGroup | `null` | This is the FeatureGroup that stores all editable shapes. THIS IS REQUIRED FOR THE EDIT TOOLBAR TO WORK
edit | EditHandlerOptions | `{ }` | Edit handler options. Set to `false` to disable handler.
remove | DeleteHandlerOptions | `{ }` | Delete handler options. Set to `false` to disable handler.
poly | EditPolyOptions | `{ }` | Set polygon editing options
allowIntersection | Bool | `true` | Determines if line segments can cross.

## EditHandlerOptions

Option | Type | Default | Description
--- | --- | --- | ---
selectedPathOptions | Leaflet Path options | See code | The path options for how the layers will look while in edit mode. If this is set to null the editable path options will not be set.

Note: To maintain the original layer color of the layer use `maintainColor: true` within `selectedPathOptions`. E.g. The edit options below will maintain the layer color and set the edit opacity to 0.3.

    {
        selectedPathOptions: {
            maintainColor: true,
            opacity: 0.3
        }
    }

## version

A constant that represents the Leaflet.Draw version in use.

        L.drawVersion; // contains "0.4.2" (or whatever version is currently in use)