# Leaflet.Editable API reference

## Map

Leaflet.Editable add options and events to the `L.Map` object. See `Editable` events for the list of events fired on the Map.

### Usage example

    var map = L.map('map', {
     editable: true,
     editOptions: {
       …
    }
    });

### Options

#### Map Options

Option | Type | Default | Description
--- | --- | --- | ---
`editToolsClass` | `class` | `L.Editable` | Class to be used as vertex, for path editing.
`editable` | `boolean` | `false` | Whether to create a L.Editable instance at map init.
`editOptions` | `hash` | `{}` | Options to pass to L.Editable when instanciating.

## EditableMixin

`EditableMixin` is included to `L.Polyline`, `L.Polygon`, `L.Rectangle`, `L.Circle` and `L.Marker`. It adds some methods to them. When editing is enabled, the editor is accessible on the instance with the `editor` property.

### Methods

Method | Returns | Description
--- | --- | ---
`enableEdit(<L.Map> map?)` | `this.editor` | Enable editing, by creating an editor if not existing, and then calling `enable` on it.
`editEnabled()` | `boolean` | Return true if current instance has an editor attached, and this editor is enabled.
`disableEdit()` | `` | Disable editing, also remove the editor property reference.
`toggleEdit()` | `` | Enable or disable editing, according to current status.

## Editable

Main edition handler. By default, it is attached to the map as `map.editTools` property. Leaflet.Editable is made to be fully extendable. You have three ways to customize the behaviour: using options, listening to events, or extending.

### Options

Option | Type | Default | Description
--- | --- | --- | ---
`zIndex` | `int` | `1000` | The default zIndex of the editing tools.
`polygonClass` | `class` | `L.Polygon` | Class to be used when creating a new Polygon.
`polylineClass` | `class` | `L.Polyline` | Class to be used when creating a new Polyline.
`markerClass` | `class` | `L.Marker` | Class to be used when creating a new Marker.
`rectangleClass` | `class` | `L.Rectangle` | Class to be used when creating a new Rectangle.
`circleClass` | `class` | `L.Circle` | Class to be used when creating a new Circle.
`drawingCSSClass` | `string` | `'leaflet-editable-drawing'` | CSS class to be added to the map container while drawing.
`drawingCursor` | `const` | `'crosshair'` | Cursor mode set to the map while drawing.
`editLayer` | `Layer` | `new L.LayerGroup()` | Layer used to store edit tools (vertex, line guide…).
`featuresLayer` | `Layer` | `new L.LayerGroup()` | Default layer used to store drawn features (Marker, Polyline…).
`polylineEditorClass` | `class` | `PolylineEditor` | Class to be used as Polyline editor.
`polygonEditorClass` | `class` | `PolygonEditor` | Class to be used as Polygon editor.
`markerEditorClass` | `class` | `MarkerEditor` | Class to be used as Marker editor.
`rectangleEditorClass` | `class` | `RectangleEditor` | Class to be used as Rectangle editor.
`circleEditorClass` | `class` | `CircleEditor` | Class to be used as Circle editor.
`lineGuideOptions` | `hash` | `{}` | Options to be passed to the line guides.
`skipMiddleMarkers` | `boolean` | `false` | Set this to true if you don't want middle markers.
`vertexMarkerClass` | `class` | `VertexMarker` | Class to be used as vertex, for path editing.
`middleMarkerClass` | `class` | `VertexMarker` | Class to be used as middle vertex, pulled by the user to create a new point in the middle of a path.

### Events

Event | Data | Description
--- | --- | ---
`editable:created` | `LayerEvent` | Fired when a new feature (Marker, Polyline…) is created.
`editable:enable` | `Event` | Fired when an existing feature is ready to be edited.
`editable:disable` | `Event` | Fired when an existing feature is not ready anymore to be edited.
`editable:editing` | `Event` | Fired as soon as any change is made to the feature geometry.
`editable:dragstart` | `Event` | Fired before a path feature is dragged.
`editable:drag` | `Event` | Fired when a path feature is being dragged.
`editable:dragend` | `Event` | Fired after a path feature has been dragged.

#### Drawing events

Event | Data | Description
--- | --- | ---
`editable:drawing:start` | `Event` | Fired when a feature is to be drawn.
`editable:drawing:end` | `Event` | Fired when a feature is not drawn anymore.
`editable:drawing:cancel` | `Event` | Fired when user cancel drawing while a feature is being drawn.
`editable:drawing:commit` | `Event` | Fired when user finish drawing a feature.
`editable:drawing:mousedown` | `Event` | Fired when user `mousedown` while drawing.
`editable:drawing:mouseup` | `Event` | Fired when user `mouseup` while drawing.
`editable:drawing:click` | `CancelableEvent` | Fired when user `click` while drawing, before any internal action is being processed.
`editable:drawing:move` | `Event` | Fired when `move` mouse while drawing, while dragging a marker, and while dragging a vertex.
`editable:drawing:clicked` | `Event` | Fired when user `click` while drawing, after all internal actions.

#### Vertex events

Event | Data | Description
--- | --- | ---
`editable:vertex:new` | `VertexEvent` | Fired when a new vertex is created.
`editable:vertex:click` | `CancelableVertexEvent` | Fired when a `click` is issued on a vertex, before any internal action is being processed.
`editable:vertex:clicked` | `VertexEvent` | Fired when a `click` is issued on a vertex, after all internal actions.
`editable:vertex:rawclick` | `CancelableVertexEvent` | Fired when a `click` is issued on a vertex without any special key and without being in drawing mode.
`editable:vertex:deleted` | `VertexEvent` | Fired after a vertex has been deleted by user.
`editable:vertex:ctrlclick` | `VertexEvent` | Fired when a `click` with `ctrlKey` is issued on a vertex.
`editable:vertex:shiftclick` | `VertexEvent` | Fired when a `click` with `shiftKey` is issued on a vertex.
`editable:vertex:metakeyclick` | `VertexEvent` | Fired when a `click` with `metaKey` is issued on a vertex.
`editable:vertex:altclick` | `VertexEvent` | Fired when a `click` with `altKey` is issued on a vertex.
`editable:vertex:contextmenu` | `VertexEvent` | Fired when a `contextmenu` is issued on a vertex.
`editable:vertex:mousedown` | `VertexEvent` | Fired when user `mousedown` a vertex.
`editable:vertex:drag` | `VertexEvent` | Fired when a vertex is dragged by user.
`editable:vertex:dragstart` | `VertexEvent` | Fired before a vertex is dragged by user.
`editable:vertex:dragend` | `VertexEvent` | Fired after a vertex is dragged by user.

#### MiddleMarker events

Event | Data | Description
--- | --- | ---
`editable:middlemarker:mousedown` | `VertexEvent` | Fired when user `mousedown` a middle marker.

#### Shape events

Event | Data | Description
--- | --- | ---
`editable:shape:new` | `ShapeEvent` | Fired when a new shape is created in a multi (Polygon or Polyline).
`editable:shape:delete` | `CancelableShapeEvent` | Fired before a new shape is deleted in a multi (Polygon or Polyline).
`editable:shape:deleted` | `ShapeEvent` | Fired after a new shape is deleted in a multi (Polygon or Polyline).

### Methods

#### Public methods

You will generally access them by the `map.editTools` instance: `map.editTools.startPolyline();`

Method | Returns | Description
--- | --- | ---
`drawing()` | `boolean` | Return true if any drawing action is ongoing.
`stopDrawing()` | `` | When you need to stop any ongoing drawing, without needing to know which editor is active.
`commitDrawing()` | `` | When you need to commit any ongoing drawing, without needing to know which editor is active.
`startPolyline(<L.LatLng> latlng, <hash> options)` | `L.Polyline` | Start drawing a Polyline. If `latlng` is given, a first point will be added. In any case, continuing on user click. If `options` is given, it will be passed to the Polyline class constructor.
`startPolygon(<L.LatLng> latlng, <hash> options)` | `L.Polygon` | Start drawing a Polygon. If `latlng` is given, a first point will be added. In any case, continuing on user click. If `options` is given, it will be passed to the Polygon class constructor.
`startMarker(<L.LatLng> latlng, <hash> options)` | `L.Marker` | Start adding a Marker. If `latlng` is given, the Marker will be shown first at this point. In any case, it will follow the user mouse, and will have a final `latlng` on next click (or touch). If `options` is given, it will be passed to the Marker class constructor.
`startRectangle(<L.LatLng> latlng, <hash> options)` | `L.Rectangle` | Start drawing a Rectangle. If `latlng` is given, the Rectangle anchor will be added. In any case, continuing on user drag. If `options` is given, it will be passed to the Rectangle class constructor.
`startCircle(<L.LatLng> latlng, <hash> options)` | `L.Circle` | Start drawing a Circle. If `latlng` is given, the Circle anchor will be added. In any case, continuing on user drag. If `options` is given, it will be passed to the Circle class constructor.

## BaseEditor

When editing a feature (Marker, Polyline…), an editor is attached to it. This editor basically knows how to handle the edition.

### Methods

Method | Returns | Description
--- | --- | ---
`enable()` | `this` | Set up the drawing tools for the feature to be editable.
`disable()` | `this` | Remove the drawing tools for the feature.
`drawing()` | `boolean` | Return true if any drawing action is ongoing with this editor.

## MarkerEditor

Editor for Marker.

### Methods

▶ Methods inherited from BaseEditor

Method | Returns | Description
--- | --- | ---
`enable()` | `this` | Set up the drawing tools for the feature to be editable.
`disable()` | `this` | Remove the drawing tools for the feature.
`drawing()` | `boolean` | Return true if any drawing action is ongoing with this editor.

## PathEditor

Base class for all path editors.

### Methods

Method | Returns | Description
--- | --- | ---
`reset()` | `` | Rebuild edit elements (Vertex, MiddleMarker, etc.).
`push()` | `` | Programmatically add a point while drawing.
`pop()` | `L.LatLng or null` | Programmatically remove last point (if any) while drawing.
`newShape(<L.LatLng> latlng?)` | `` | Add a new shape (Polyline, Polygon) in a multi, and setup up drawing tools to draw it; if optional `latlng` is given, start a path at this point.
`deleteShapeAt(<L.LatLng> latlng)` | `Array` | Remove a path shape at the given `latlng`.
`appendShape(<Array> shape)` | `` | Append a new shape to the Polygon or Polyline.
`prependShape(<Array> shape)` | `` | Prepend a new shape to the Polygon or Polyline.
`insertShape(<Array> shape, <int> index)` | `` | Insert a new shape to the Polygon or Polyline at given index (default is to append).

▶ Methods inherited from BaseEditor

Method | Returns | Description
--- | --- | ---
`enable()` | `this` | Set up the drawing tools for the feature to be editable.
`disable()` | `this` | Remove the drawing tools for the feature.
`drawing()` | `boolean` | Return true if any drawing action is ongoing with this editor.

## PolylineEditor

### Methods

Method | Returns | Description
--- | --- | ---
`continueBackward(<Array> latlngs?)` | `` | Set up drawing tools to continue the line backward.
`continueForward(<Array> latlngs?)` | `` | Set up drawing tools to continue the line forward.
`splitShape(<Array> latlngs?, <int> index)` | `` | Split the given `latlngs` shape at index `index` and integrate new shape in instance `latlngs`.

▶ Methods inherited from PathEditor

Method | Returns | Description
--- | --- | ---
`reset()` | `` | Rebuild edit elements (Vertex, MiddleMarker, etc.).
`push()` | `` | Programmatically add a point while drawing.
`pop()` | `L.LatLng or null` | Programmatically remove last point (if any) while drawing.
`newShape(<L.LatLng> latlng?)` | `` | Add a new shape (Polyline, Polygon) in a multi, and setup up drawing tools to draw it; if optional `latlng` is given, start a path at this point.
`deleteShapeAt(<L.LatLng> latlng)` | `Array` | Remove a path shape at the given `latlng`.
`appendShape(<Array> shape)` | `` | Append a new shape to the Polygon or Polyline.
`prependShape(<Array> shape)` | `` | Prepend a new shape to the Polygon or Polyline.
`insertShape(<Array> shape, <int> index)` | `` | Insert a new shape to the Polygon or Polyline at given index (default is to append).

▶ Methods inherited from BaseEditor

Method | Returns | Description
--- | --- | ---
`enable()` | `this` | Set up the drawing tools for the feature to be editable.
`disable()` | `this` | Remove the drawing tools for the feature.
`drawing()` | `boolean` | Return true if any drawing action is ongoing with this editor.

## PolygonEditor

### Methods

Method | Returns | Description
--- | --- | ---
`newHole(<L.LatLng> latlng?, <int> index)` | `` | Set up drawing tools for creating a new hole on the Polygon. If the `latlng` param is given, a first point is created.

▶ Methods inherited from PathEditor

Method | Returns | Description
--- | --- | ---
`reset()` | `` | Rebuild edit elements (Vertex, MiddleMarker, etc.).
`push()` | `` | Programmatically add a point while drawing.
`pop()` | `L.LatLng or null` | Programmatically remove last point (if any) while drawing.
`newShape(<L.LatLng> latlng?)` | `` | Add a new shape (Polyline, Polygon) in a multi, and setup up drawing tools to draw it; if optional `latlng` is given, start a path at this point.
`deleteShapeAt(<L.LatLng> latlng)` | `Array` | Remove a path shape at the given `latlng`.
`appendShape(<Array> shape)` | `` | Append a new shape to the Polygon or Polyline.
`prependShape(<Array> shape)` | `` | Prepend a new shape to the Polygon or Polyline.
`insertShape(<Array> shape, <int> index)` | `` | Insert a new shape to the Polygon or Polyline at given index (default is to append).

▶ Methods inherited from BaseEditor

Method | Returns | Description
--- | --- | ---
`enable()` | `this` | Set up the drawing tools for the feature to be editable.
`disable()` | `this` | Remove the drawing tools for the feature.
`drawing()` | `boolean` | Return true if any drawing action is ongoing with this editor.

## RectangleEditor

### Methods

▶ Methods inherited from PathEditor

Method | Returns | Description
--- | --- | ---
`reset()` | `` | Rebuild edit elements (Vertex, MiddleMarker, etc.).
`push()` | `` | Programmatically add a point while drawing.
`pop()` | `L.LatLng or null` | Programmatically remove last point (if any) while drawing.
`newShape(<L.LatLng> latlng?)` | `` | Add a new shape (Polyline, Polygon) in a multi, and setup up drawing tools to draw it; if optional `latlng` is given, start a path at this point.
`deleteShapeAt(<L.LatLng> latlng)` | `Array` | Remove a path shape at the given `latlng`.
`appendShape(<Array> shape)` | `` | Append a new shape to the Polygon or Polyline.
`prependShape(<Array> shape)` | `` | Prepend a new shape to the Polygon or Polyline.
`insertShape(<Array> shape, <int> index)` | `` | Insert a new shape to the Polygon or Polyline at given index (default is to append).

▶ Methods inherited from BaseEditor

Method | Returns | Description
--- | --- | ---
`enable()` | `this` | Set up the drawing tools for the feature to be editable.
`disable()` | `this` | Remove the drawing tools for the feature.
`drawing()` | `boolean` | Return true if any drawing action is ongoing with this editor.

## CircleEditor

### Methods

▶ Methods inherited from PathEditor

Method | Returns | Description
--- | --- | ---
`reset()` | `` | Rebuild edit elements (Vertex, MiddleMarker, etc.).
`push()` | `` | Programmatically add a point while drawing.
`pop()` | `L.LatLng or null` | Programmatically remove last point (if any) while drawing.
`newShape(<L.LatLng> latlng?)` | `` | Add a new shape (Polyline, Polygon) in a multi, and setup up drawing tools to draw it; if optional `latlng` is given, start a path at this point.
`deleteShapeAt(<L.LatLng> latlng)` | `Array` | Remove a path shape at the given `latlng`.
`appendShape(<Array> shape)` | `` | Append a new shape to the Polygon or Polyline.
`prependShape(<Array> shape)` | `` | Prepend a new shape to the Polygon or Polyline.
`insertShape(<Array> shape, <int> index)` | `` | Insert a new shape to the Polygon or Polyline at given index (default is to append).

▶ Methods inherited from BaseEditor

Method | Returns | Description
--- | --- | ---
`enable()` | `this` | Set up the drawing tools for the feature to be editable.
`disable()` | `this` | Remove the drawing tools for the feature.
`drawing()` | `boolean` | Return true if any drawing action is ongoing with this editor.

## VertexMarker

Handler for dragging path vertices.

### Methods

#### Public methods

The marker used to handle path vertex. You will usually interact with a `VertexMarker` instance when listening for events like `editable:vertex:ctrlclick`.

Method | Returns | Description
--- | --- | ---
`delete()` | `` | Delete a vertex and the related LatLng.
`getIndex()` | `int` | Get the index of the current vertex among others of the same LatLngs group.
`getLastIndex()` | `int` | Get last vertex index of the LatLngs group of the current vertex.
`getPrevious()` | `VertexMarker` | Get the previous VertexMarker in the same LatLngs group.
`getNext()` | `VertexMarker` | Get the next VertexMarker in the same LatLngs group.
`split()` | `` | Split the vertex LatLngs group at its index, if possible.
`continue()` | `` | Continue the vertex LatLngs from this vertex. Only active for first and last vertices of a Polyline.

## Event objects

##

### CancelableEvent

Method | Returns | Description
--- | --- | ---
`cancel()` | `` | Cancel any subsequent action.

##

### VertexEvent

Property | Type | Description
--- | --- | ---
`vertex` | `VertexMarker` | The vertex that fires the event.

##

### ShapeEvent

Property | Type | Description
--- | --- | ---
`shape` | `Array` | The shape (LatLngs array) subject of the action.

##

### CancelableVertexEvent

▶ Methods inherited from CancelableEvent

Method | Returns | Description
--- | --- | ---
`cancel()` | `` | Cancel any subsequent action.

### CancelableVertexEvent

▶ Properties inherited from VertexEvent

Property | Type | Description
--- | --- | ---
`vertex` | `VertexMarker` | The vertex that fires the event.

##

### CancelableShapeEvent

▶ Methods inherited from CancelableEvent

Method | Returns | Description
--- | --- | ---
`cancel()` | `` | Cancel any subsequent action.

### CancelableShapeEvent

▶ Properties inherited from ShapeEvent

Property | Type | Description
--- | --- | ---
`shape` | `Array` | The shape (LatLngs array) subject of the action.

##

### LayerEvent

Property | Type | Description
--- | --- | ---
`layer` | `object` | The Layer (Marker, Polyline…) subject of the action.