Skip to content

Commit 1413372

Browse files
mcwhittemoremcwhittemore
committed
Merge pull request #258 from mapbox/fresh-start
0.6.0-rc1
2 parents 2302641 + 6435a20 commit 1413372

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

89 files changed

+26067
-2331
lines changed

‎API.md

+137-113
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# API Reference
22

3-
In order to use GL Draw you must instantiate the draw class like so:
3+
To use Draw
44

55
```js
66
var Draw = mapboxgl.Draw({ options });
@@ -17,77 +17,50 @@ map.on('load', function() {
1717
});
1818
```
1919

20-
### Options
20+
## Options
2121

2222
option | values | function
2323
--- | --- | ---
2424
drawing | boolean | The ability to draw and delete features - default: `true`
25-
interactive | boolean | Keep all features permanently in selected mode - default: `false`
2625
keybindings | boolean | Keyboard shortcuts for drawing - default: `true`
2726
displayControlsDefault | boolean | Sets default value for the control keys in the control option - default `true`
28-
controls | Object | Lets you hide or show individual controls. See `displayControlsDefault` for default. Available options are: marker, line, shape, square and trash.
29-
styles | Object | Add a style with any of the following properties: <li>`gl-draw-polygon`</li><li>`gl-draw-polygon-stroke`</li><li> `gl-draw-line`</li><li> `gl-draw-point`</li><li> `gl-draw-selected-line`</li><li> `gl-draw-selected-polygon`</li><li> `gl-draw-selected-polygon-stroke`</li><li> `gl-draw-selected-point`</li><li> `gl-draw-selected-point-mid`</li>The property should be an object with either the `layout` and/or `paint` properties as specified in the [Mapbox GL Style Reference](https://www.mapbox.com/mapbox-gl-style-spec/). It will overwrite the corresponding default styles found in [`src/theme/`](https://github.com/mapbox/mapbox-gl-draw/tree/master/src/theme).
30-
31-
Custom Style Example:
32-
33-
```js
34-
var Draw = mapboxgl.Draw({
35-
styles: {
36-
'gl-draw-polygon': {
37-
'paint': {
38-
'fill-color': '#00ffff',
39-
'fill-outline-color': '#00ffff',
40-
'fill-opacity': 0.25
41-
}
42-
},
43-
'gl-draw-polygon-stroke': {
44-
'paint': {
45-
'line-color': '#0000ff',
46-
'line-width': 4
47-
}
48-
}
49-
}
50-
});
51-
```
52-
53-
54-
`mapboxgl.Draw()` returns an instance of the `Draw` class which has the following public API methods for getting and setting data:
27+
controls | Object | Lets you hide or show individual controls. See `displayControlsDefault` for default. Available options are: point, line, polygon and trash.
28+
style | Object | An array of style objects. By default draw provides a style for you. To override this see [Styling Draw](#styling-draw) further down.
5529

5630
## API Methods
5731

58-
####`.add(Object: GeoJSONFeature, [Object]: options) -> String`
32+
`mapboxgl.Draw()` returns an instance of `Draw` which has the following API for working with your data:
5933

60-
This method takes any valid GeoJSON and adds it to Draw. The object will be turned into a GeoJSON feature and will be assigned a unique `drawId` that can be used to identify it. This method return the new feature's `drawId`. If an id is provided with the feature that ID will be used.
34+
###`.add(Object: GeoJSON) -> String || [String]`
6135

62-
The second argument is an optional options object to add information to the geometry when creating the new element. Currently the only used option is `permanent`, which, if set to true, will cause the element to ignore click events, `Draw.select(:id:)` and `Draw.selectAll()`.
36+
This method takes either a Feature or a FeatureCollection and adds it to Draw. It returns an id for interacting with the added feature. When a FeatureCollection is provided an array of ids is returned. If there is no ID on the feature, a random ID will be genearted.
6337

64-
Draw does not enforce unique IDs to be passed to `.add`, but it does enforce unique ids inside of it. This means that if you provide an id for a feature that is not unqiue, Draw will override the exhisting feature with your new feature. You can think of this like PUT in http verbs.
38+
Currently the only supoorted GeoJSON feature types are `Point`, `LineString` and `Polygon`.
6539

66-
If a FeatureCollection is provided to `.add` Draw will break it up into many features as if you looped through the features in the collection and added them one at a time. This is good for bulk adding, though it is no faster than looping yourself.
40+
Adding a feature with the same id as another feature in Draw forces an update.
6741

6842
Example:
6943

7044
```js
7145
var feature = { type: 'Point', coordinates: [0, 0] };
7246
var featureId = Draw.add(feature);
73-
console.log(Draw.get(featureId));
74-
//=> { type: 'Feature', geometry: { type: 'Point', coordinates: [0, 0] }
47+
console.log(featureId);
48+
//=> 'random-string'
7549
```
7650

7751
Example with ID:
7852

7953
```js
8054
var feature = { type: 'Point', coordinates: [0, 0], id: 'unique-id' };
8155
var featureId = Draw.add(feature);
82-
console.log(featureId) //=> unique-id
83-
console.log(Draw.get('unique-id'));
84-
//=> { type: 'Feature', geometry: { type: 'Point', coordinates: [0, 0], id: 'unique-id' }
56+
console.log(featureId)
57+
//=> unique-id
8558
```
8659

8760
---
88-
####`.get(String: drawId) -> Object`
61+
###`.get(String: feature.id) -> Object`
8962

90-
This method takes the `drawId` of a feature and returns its GeoJSON object.
63+
This method takes an ID returns a GeoJSON feature.
9164

9265
Example:
9366

@@ -98,10 +71,9 @@ console.log(Draw.get(id));
9871
```
9972

10073
---
101-
####`.getAll() -> Object`
102-
103-
This method returns all features added to Draw in a single GeoJSON FeatureCollection. The each feature's unique id will be found on the `id` attribute of the feature.
74+
###`.getAll() -> Object`
10475

76+
This method returns all features added to Draw in a single GeoJSON FeatureCollection.
10577

10678
Example:
10779

@@ -114,20 +86,23 @@ console.log(Draw.getAll());
11486
// type: 'FeatureCollection',
11587
// features: [
11688
// {
89+
// id: 'random-0'
11790
// type: 'Feature',
11891
// geometry: {
11992
// type: 'Point',
12093
// coordinates: [0, 0]
12194
// }
12295
// },
12396
// {
97+
// id: 'random-1'
12498
// type: 'Feature',
12599
// geometry: {
126100
// type: 'Point',
127101
// coordinates: [1, 1]
128102
// }
129103
// },
130-
// {
104+
// {
105+
// id: 'random-2'
131106
// type: 'Feature',
132107
// geometry: {
133108
// type: 'Point',
@@ -139,121 +114,170 @@ console.log(Draw.getAll());
139114
```
140115
---
141116

142-
####`.getSelected() -> Object`
117+
###`.delete(String: id) -> Draw`
143118

144-
Get all selected features.
119+
This method takes an id removes the coorisponding feature from Draw.
145120

146-
---
121+
In `direct_select` mode, deleting the active feature will stop the mode and revert to the `simple_select` mode.
147122

148-
####`.select(String: drawId) -> Draw`
123+
Example:
149124

150-
This method takes the `drawId` of a feature and selects it. It returns `this` to allow for method chaining.
125+
```js
126+
var feature = { type: 'Point', coordinates: [0, 0] };
127+
var id = draw.add(feature)
128+
Draw
129+
.delete(id)
130+
.getAll();
131+
// => { type: 'FeatureCollection', features: [] }
132+
```
151133

152134
---
153135

154-
####`.selectAll() -> Draw`
136+
###`.deleteAll() -> Draw`
155137

156-
This method selects all features. It returns `this` to allow for method chaining.
138+
This method removes all geometries in Draw.
139+
140+
Example:
141+
142+
```js
143+
Draw.add({ type: 'Point', coordinates: [0, 0] });
144+
Draw
145+
.deleteAll()
146+
.getAll();
147+
// => { type: 'FeatureCollection', features: [] }
148+
```
157149

158150
---
159151

160-
####`.deselect(String: drawId) -> Draw`
152+
### `.trash() -> Draw`
161153

162-
This method takes the `drawId` of a feature and deselects it if selected. It returns `this` to allow for method chaining.
154+
This envokes the current modes trash event. For the `simple_select` mode this deletes all active features. For the `direct_select` mode this deletes the active vertices. For the drawing modes, these cancel the current process.
155+
156+
This is different from `delete` or `deleteAlll` in that it follows rules described by the current mode.
163157

164158
---
165159

166-
####`.deselectAll() -> Draw`
160+
### `.changeMode(String: mode, ?Any: options) -> Draw`
167161

168-
This method deselects all features. It returns `this` to allow for method chaining.
162+
`changeMode` triggers the mode switching process inside Draw. `mode` must be one of the below strings. Each mode takes its own arguments. They are descibed in detail below.
169163

170-
---
164+
#### Mode: `simple_select`
171165

172-
####`.destroy(String: drawId) -> Draw`
166+
Lets you select, delete and drag features.
173167

174-
This method takes the `drawId` of feature and removes it from draw. It returns `this` to allow for method chaining.
168+
For `simple_select` options is an array of ids. It is optional. If provided, these features will be active at the start of the mode. In this mode, features can have their active state changed by the user. To control what is active, react to changes as described in the events section below.
175169

176-
Example:
170+
#### Mode: `direct_select`
177171

178-
```js
179-
var feature = { type: 'Point', coordinates: [0, 0] };
180-
var id = draw.add(feature)
181-
Draw
182-
.destroy(id)
183-
.getAll();
184-
// => { type: 'FeatureCollection', features: [] }
185-
```
172+
Lets you select, delete and drag vertices.
186173

187-
---
174+
For `direct_select`options is a single featureId. It is required. This feature will be active for the duration of the mode.
188175

189-
####`.update(String: drawId, Object: GeoJSONFeature) -> Draw`
176+
#### Drawing modes:
190177

191-
This method takes the `drawId` of an existing feature and a GeoJSON object and replaces that feature in draw with the new feature. It returns `this`.
178+
The three drawing modes work identically. They do not take an options argument.
192179

193-
Example:
180+
- `draw_line_string`: Draws a LineString feature.
181+
- `draw_polygon`: Draws a Polygon feature.
182+
- `draw_point`: Draws a Point feature.
194183

195-
```js
196-
var id = Draw.add({ type: 'Point', coordinates: [0, 0] });
197-
var newFeature = Draw
198-
.update(id, { type: 'Point', coordinates: [1, 1] })
199-
.get(id);
200-
console.log(newFeature);
201-
//=> { type: 'Feature', geometry: { type: 'Point', coordinates: [1, 1] } }
202-
```
184+
## Events
203185

204-
---
186+
Draw fires off a number of events. All of these events are name spaced `draw.` and are emitted via map object.
205187

206-
####`.clear() -> Draw`
188+
### draw.modechange
207189

208-
This method removes all geometries in Draw.
190+
This event is fired just after the current mode is stopped and just before the next mode is started. A render will not happen until after all event handlers have been triggered. This means you can force a mode redirect by calling `changeMode` inside of a `draw.modechange` handler.
209191

210-
Example:
192+
This is not fired when the first mode is started.
193+
194+
Here is an example payload.
211195

212196
```js
213-
Draw.add({ type: 'Point', coordinates: [0, 0] });
214-
Draw
215-
.clear()
216-
.getAll();
217-
// => { type: 'FeatureCollection', features: [] }
197+
{
198+
mode: `direct_select`
199+
opts: '123123123'
200+
}
218201
```
219202

220-
---
203+
### draw.deleted
221204

222-
####`.startDrawing(Enum: { Draw.types.POINT | Draw.types.LINE | Draw.types.POLYGON | Draw.types.SQUARE })`
205+
This is fired every time a feature is deleted. The payload is a list GeoJSON features just before they were deleted.
223206

224-
This method initiates drawing the specified type. The types are defined in constants in draw under `Draw.types.*`. The argument should be one of
207+
### draw.changed
225208

226-
- `Draw.types.POINT`
227-
- `Draw.types.LINE`
228-
- `Draw.types.POLYGON`
229-
- `Draw.types.SQUARE`
209+
This is fired when feature coordinates are changed. It is fired just after the changes have been sent to be rendered. The payload is the GeoJSON of all changed features. Deleted features will not show up here.
230210

231-
Example:
211+
### draw.mode.default.selected.start
232212

233-
```js
234-
Draw.startDrawing(Draw.types.LINE);
235-
```
213+
This is fired every time a feature is selected in the default mode. The payload is an array of feature ids being selected. This is **NOT** fired when the mode starts as this information is in the `draw.modechange` event.
236214

237-
## Events
215+
### draw.mode.default.selected.end
216+
217+
This is fired every time a feature is unselected in the default mode. The payload is an array of feature ids being unselected. This is **NOT** fired when the mode stops, as this can be assumed via the `draw.modechange` event.
218+
219+
## Styling Draw
238220

239-
Draw fires off a number of events on draw and select actions. All of these events are name spaced `draw` inside of the mapboxgl event emitter.
221+
Draw is styled by the [Mapbox GL Style Spec](https://www.mapbox.com/mapbox-gl-style-spec/) with a preset list of properties.
240222

241-
#### draw.set
223+
The `GL Style Spec` requires each layer to have a source. **DO NOT PROVIDE THIS** for styling draw.
242224

243-
This is fired every time a feature is committed via escape or the double click. The payload is an object with the `mapbox-gl-draw` feature id and the GeoJSON representation of the feature.
225+
Draw moves features between sources for performance gains, because of this it is recommeneded that you **DO NOT** provide a source for a style despite the fact the `GL Style Spec` requires a source. **Draw will provide the source for you automatically**.
244226

245-
#### draw.delete
227+
If you need to style gl-draw for debugging sources the source names are `mapbox-gl-draw-hot` and `mapbox-gl-draw-cold`.
246228

247-
This is fired every time a feature is deleted inside of `mapbox-gl-draw`. The payload is an object with the `mapbox-gl-draw` feature id of the feature that was deleted and the GeoJSON representation of the feature just before it was deleted.
229+
property | values | function
230+
--- | --- | ---
231+
meta | feature, midpoint, vertex, too-small | `midpoint` and `vertex` are used on points added to the map to communicate polygon and line handles. `feature` is used for all features added by the user. `too-small` is used to indicate a point that represents the center of a collection of features that are too small at the current zoom level to be seen.
232+
active | true, false | A feature is active when it is 'selected' in the current mode. `true` and `false` are strings.
233+
mode | simple_select, direct_select, draw_point, draw_line_string, draw_polygon | Indicates which mode Draw is currently in.
234+
hover | true, false | `true` and `false` are strings. `hover` is true when the mouse is over the feature.
248235

249-
#### draw.select.start
236+
Draw also provides a few more properties, but they should not be used for styling. For details on them, see `Using Draw with map.queryRenderFeatures`.
250237

251-
Fired every time a feature is selected. The payload is an object with the `mapbox-gl-draw` feature id and the GeoJSON representation of the feature.
238+
### Example Custom Style
252239

253-
#### draw.select.end
240+
With this style all Point features are blue and have a black halo when active. No other features are rendered, even if they are present.
254241

255-
Fired every time a feature is deselected. The payload is an object with the `mapbox-gl-draw` feature id.
242+
```js
243+
mapbox.Draw({
244+
style: [
245+
{
246+
'id': 'highlight-active-points',
247+
'type': 'circle',
248+
'filter': ['all',
249+
['==', '$type', 'Point'],
250+
['==', 'meta', 'feature'],
251+
['==', 'active', 'true']],
252+
'paint': {
253+
'circle-radius': 7,
254+
'circle-color': '#000000'
255+
},
256+
'interactive': true
257+
},
258+
{
259+
'id': 'points-are-blue',
260+
'type': 'circle',
261+
'filter': ['all',
262+
['==', '$type', 'Point'],
263+
['==', 'meta', 'feature'],
264+
['==', 'active', 'true']],
265+
'paint': {
266+
'circle-radius': 5,
267+
'circle-color': '#000088'
268+
},
269+
'interactive': true
270+
}
271+
]
272+
});
273+
```
256274

257-
## Private functions
275+
## Using Draw with `map.queryRenderFeatures`
258276

259-
Draw uses underscore prefixed variables to indicate that the following function is private. These functions are apt to change or be removed. If there is functionality in these functions that should be part of the public api, please open PR explaining the use case.
277+
property | values | function
278+
--- | --- | ---
279+
id | string | only available when `meta` is `feature`
280+
parent | string | only avaible when `meta` is not `feature`
281+
coord_path | string | a `.` seporated path to one [lon, lat] entity in the parents coordinates
282+
lon | number | the longitude value of a handle. Only available when `meta` is `midpoint`.
283+
lat | number | the latitude value of a handle. Only available when `meta` is `midpoint`.

0 commit comments

Comments
 (0)