model
In Mapmost Draw, modes is used to combine a set of user interactions into a single behavior. Internally, Draw has the draw_polygon mode, which controls a series of interactions for drawing polygons. Draw also has a simple_select mode, which controls interaction when zero, one or more features are selected, including switching to direct_select mode when the user’s interaction suggests they wish to make detailed edits to individual features.
To help developers gain greater control over their Mapmost Draw-based applications, Draw provides an interface for writing and wiring custom schemas.
Custom drawing mode
We will create a custom mode called LotsOfPointsMode. When activated, this mode will create a new point each time the user clicks on the map and transition to the default mode when the user presses the esc key.
Case
var LotsOfPointsMode = {};
// This function is called when the mode starts.
// The `opts` parameter comes from `draw.changeMode('lotsofpoints', {count:7})`.
// The return value should be an object and will be passed to all other lifecycle functions.
LotsOfPointsMode.onSetup = function(opts) {
var state = {};
state.count = opts.count || 0;
return state;
};
// When the user clicks on the map, Draw will call `onClick`
LotsOfPointsMode.onClick = function(state, e) {
// `this.newFeature` accepts geojson and generates a DrawFeature
var point = this.newFeature({
type: 'Feature',
properties: {
count: state.count
},
geometry: {
type: 'Point',
coordinates: [e.lngLat.lng, e.lngLat.lat]
}
});
this.addFeature(point); // Place the point on the map
};
// When the user clicks a button on the map, it will be sent here
LotsOfPointsMode.onKeyUp = function(state, e) {
if (e.keyCode === 27) return this.changeMode('simple_select');
};
// This is the only function required for a pattern
// It determines which features currently in Draw’s data store will be rendered to the map.
// All traits passed to `display` will be rendered, so you can pass multiple traits inside the display.
// Look for `styling-draw` suggestions for display functions in `API.md`.
LotsOfPointsMode.toDisplayFeatures = function(state, geojson, display) {
display(geojson);
};
//Add a new drawing mode to the MapmostDraw object
var draw = new MapmostDraw({
defaultMode: 'lots_of_points',
// Add LotsOfPointsMode to the set of built-in modes
modes: Object.assign({
lots_of_points: LotsOfPointsMode,
}, MapmostDraw.modes),
});
See [Lifecycle Functions](/mapmost_docs/webgl_en/latest/docs/plugins/Mapmost-WebGL-Draw/MODES#Lifecycle Functions) below for details on how map interactions are handled. For more information on how to interact with Draw’s internal state, see [Settings and Getting](/mapmost_docs/webgl_en/latest/docs/plugins/Mapmost-WebGL-Draw/MODES#Settings and Getting) below.
Drawing modes that can be used directly
Feel free to add your own patterns to this list via PR
- Static Mode: Turn off interactive functions
- Cut/Split Line Mode: Cut/split line feature function
- Freehand Mode: Add freehand drawing function in polygon drawing mode
- Rotate Mode: Add rotating GL Draw feature function
- Radius Mode: Draw a polygonal circle based on the center vertex and radius line
- Rectangle Mode
- Circle Mode
- Assisted Rectangle Mode
- Rotate/Scale Rectangle Mode
- Rectangle Restrict Area Mode: Draw a rectangle with a restricted area
- Geodesic Modes: Draw geodesic, polygon and circle
- Cut/Split Line Mode: Use line features, point features or polygon features to cut/split linestrings/Multilinestrings
- Cut Polygon Mode: Use polygon features to cut polygons/Multipolygons
- Split Polygon Mode: Use line features to split polygons/Multipolygons
- Scale/Rotate Mode: Scale and rotate polygon and line features
- Waypoint Mode: Allows the user to drag only vertices, preventing dragging of features
- Bezier Curve Mode: Draw and edit Bezier curves
Life cycle function
MODE.onClick
Fires when the mouse is clicked.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
| e | Object | RequiredThe capture event that triggers this life cycle event. |
MODE.onCombineFeature
Fired when draw.combineFeatures() is called.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
MODE.onDrag
Fired when a drag event is detected on the map.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
| e | Object | RequiredThe capture event that triggers this life cycle event. |
MODE.onKeyDown
Fired when a key press event is detected.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
| e | Object | RequiredThe capture event that triggers this life cycle event. |
MODE.onKeyUp
Fired when a key release event is detected.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
| e | Object | RequiredThe capture event that triggers this life cycle event. |
MODE.onMouseDown
Fires when the mouse button is pressed.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
| e | Object | RequiredThe capture event that triggers this life cycle event. |
MODE.onMouseMove
Fires when the mouse is moved.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
| e | Object | RequiredThe capture event that triggers this life cycle event. |
MODE.onMouseOut
Fired when the mouse leaves the map container.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
| e | Object | RequiredThe capture event that triggers this life cycle event. |
MODE.onMouseUp
Fires when the mouse button is released.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
| e | Object | RequiredThe capture event that triggers this life cycle event. |
MODE.onSetup
Fires during mode transition.
Parameters
| Name | Type | Description |
|---|---|---|
| opts | Object | RequiredObject passed through "draw.changeMode(mode, opts)". |
Returns an Object which will be passed to all other lifecycle functions.
MODE.onStop
Triggered when exiting mode, used to clean up leftovers, such as invalid features, etc.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
MODE.onTap
Fired when the map is quickly clicked.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
| e | Object | RequiredThe capture event that triggers this life cycle event. |
MODE.onTouchEnd
Fired when the finger is removed from the map.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
| e | Object | RequiredThe capture event that triggers this life cycle event. |
MODE.onTouchMove
Fires when dragging with a finger on a mobile device.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
| e | Object | RequiredThe capture event that triggers this life cycle event. |
MODE.onTouchStart
Fired when a touch event starts.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
| e | Object | RequiredThe capture event that triggers this life cycle event. |
MODE.onTrash
Fired when draw.trash() is called.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
MODE.onUncombineFeature
Fired when draw.uncombineFeatures() is called.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
MODE.toDisplayFeatures
At render time, fired on a per-feature basis, converts the original features into a set of features displayed on the map.
For details about the GeoJSON properties used by Draw in rendering, see Drawing Styles in the API documentation for a complete style reference.
Parameters
| Name | Type | Description |
|---|---|---|
| state | Object | RequiredA mutable state object created by onSetup. |
| geojson | Object | RequiredGeoJSON object. This needs to be passed to the "display" function for rendering. |
| display | Function | RequiredAll GeoJSON objects passed to this function will be rendered to the map. |
Setting and getting
clearSelectedCoordinates
Clear all selected coordinates.
clearSelectedFeatures
Clear all selected features.
this.activateUIButton
If a name is provided, it makes the button active, otherwise it makes all buttons inactive.
Parameters
| Name | Type | Description |
|---|---|---|
| name | String | RequiredThe name of the button to be activated. Setting "undefined" will make the button inactive. |
this.addFeature
Add a DrawFeature. See this.newFeature to convert GeoJSON to DrawFeature .
Parameters
| Name | Type | Description |
|---|---|---|
| feature | DrawFeature | RequiredFeatures to be added. |
this.changeMode
Trigger mode change.
Parameters
| name | type | default value | description |
|---|---|---|---|
| mode | String | RequiredThe mode to be set. | |
| opts | Object | {} | optionalThe options object passed to the new mode. |
| eventOpts | Object | {} | optionalUsed to control the type of events emitted. |
this.delete
Removes a feature from the selection.
Parameters
| Name | Type | Description |
|---|---|---|
| id | String | RequiredThe id of the element. |
this.deleteFeature
Remove an element.
Parameters
| name | type | default value | description |
|---|---|---|---|
| id | String | RequiredThe id of the element. | |
| opts | Object | {} | optionalElement attributes. |
this.doRender
Forces the drawing tool to re-render the feature corresponding to the specified ID.
Parameters
| Name | Type | Description |
|---|---|---|
| id | String | RequiredThe id of the element. |
this.featuresAt
Gets the location or features within the bounding box of the event object.
Parameters
| name | type | default value | description |
|---|---|---|---|
| event | Function | RequiredEvent object. | |
| bbox | Array | RequiredBoundary range. | |
| bufferType | String | click | optionalclick or tap event. |
this.getFeature
Get DrawFeature by ID and return DrawFeature .
Parameters
| Name | Type | Description |
|---|---|---|
| id | String | RequiredThe id of the element. |
this.getSelected
Get all selected features as DrawFeature, return Array[DrawFeature]
this.getSelectedIds
Get the IDs of all currently selected features and return Array[String]
this.isInstanceOf
Checks whether an object is a DrawFeature instance, returning a Boolean value.
Parameters
| Name | Type | Description |
|---|---|---|
| type | String | RequiredYou can choose "Point", "LineString", "Polygon", "MultiFeature" types. |
| feature | Object | RequiredFeatures to be checked. |
this.isSelected
Checks whether a feature is selected, returning a Boolean value.
Parameters
| Name | Type | Description |
|---|---|---|
| id | String | RequiredThe id of the element. |
this.newFeature
Creates a new DrawFeature from GeoJSON, returning DrawFeature .
Parameters
| Name | Type | Description |
|---|---|---|
| geojson | GeoJSONFeature | RequiredGeoJSON feature. |
this.select
Adds features to the selected state inside the drawing tool.
Parameters
| Name | Type | Description |
|---|---|---|
| id | String | RequiredThe id of the element. |
this.setActionableState
Indicates whether your mode can currently perform different operations. See draw.actionalbe for a list of possible actions. All undefined operations default to false.
Parameters
| name | type | default value | description |
|---|---|---|---|
| actions | Object | {} | RequiredOperation object. |
this.setSelected
Sets the internal selection state of the drawing tool.
Parameters
| Name | Type | Description |
|---|---|---|
| features | RequiredFeatures. | |
| null-null | Array | RequiredSelected DrawFeature. |
this.setSelectedCoordinates
Sets the drawing tool’s internal selection coordinate state.
Parameters
| Name | Type | Description |
|---|---|---|
| coords | Array | RequiredShaped like {coord_path: "string", feature_id: "string"} |
this.updateUIClasses
Updates the state of the drawing map class.
Parameters
| Name | Type | Description |
|---|---|---|
| opts | Object | RequiredThe status object to be updated. |