Document or remove any event that can be fired by "Map"

[lucaswoj]

There are many events that we fire but don't consider part of our public API. Many users are using these events despite them being undocumented. We should consider prefixing these events with an _, like a private method, to discourage their use.

[lucaswoj]

The biggest offender is style.load. I see a lot of uses of the undocumented style.load where load should have been used. I suspect many people started using style.load as a workaround for #2042.

[jfirebaugh]

I'd be fine with publicly documenting style.load and pretty much all the *.* events.

[tmcw]

Agree with @jfirebaugh, if an event isn't public, we shouldn't emit it.

[lucaswoj]

👍 Makes sense. I adjusted the issue title to reflect this approach.

[lyzidiamond]

Here is a list of all of the events that are undocumented and where they live in the code. Some of them may be undocumented intentionally and the link I put here may not be the canonical link. Tell me which should be documented and which should be removed!

• 'error':

  mapbox-gl-js/js/style/image_sprite.js

  Line 28 in b703263

  this.fire('error', {error: err});

• 'touchstart':

  mapbox-gl-js/js/ui/interaction.js

  Lines 42 to 45 in fc4568d

  	el.addEventListener('touchstart', this._onTouchStart, false);
  	el.addEventListener('touchend', this._onTouchEnd, false);
  	el.addEventListener('touchmove', this._onTouchMove, false);
  	el.addEventListener('touchcancel', this._onTouchCancel, false);

  documented
• 'touchmove':

  mapbox-gl-js/js/ui/interaction.js

  Lines 42 to 45 in fc4568d

  	el.addEventListener('touchstart', this._onTouchStart, false);
  	el.addEventListener('touchend', this._onTouchEnd, false);
  	el.addEventListener('touchmove', this._onTouchMove, false);
  	el.addEventListener('touchcancel', this._onTouchCancel, false);

  documented
• 'touchend':

  mapbox-gl-js/js/ui/interaction.js

  Lines 42 to 45 in fc4568d

  	el.addEventListener('touchstart', this._onTouchStart, false);
  	el.addEventListener('touchend', this._onTouchEnd, false);
  	el.addEventListener('touchmove', this._onTouchMove, false);
  	el.addEventListener('touchcancel', this._onTouchCancel, false);

  documented
• 'touchcancel':

  mapbox-gl-js/js/ui/interaction.js

  Lines 42 to 45 in fc4568d

  	el.addEventListener('touchstart', this._onTouchStart, false);
  	el.addEventListener('touchend', this._onTouchEnd, false);
  	el.addEventListener('touchmove', this._onTouchMove, false);
  	el.addEventListener('touchcancel', this._onTouchCancel, false);

  documented
• 'tile.error':

  mapbox-gl-js/js/source/vector_tile_source.js

  Line 87 in 81f7959

  this.fire('tile.error', {tile: tile, error: err});

• 'tile.load':

  mapbox-gl-js/js/source/vector_tile_source.js

  Line 98 in 81f7959

  this.fire('tile.load', {tile: tile});

• 'tile.stats':

  mapbox-gl-js/js/source/vector_tile_source.js

  Line 99 in 81f7959

  this.fire('tile.stats', data.bucketStats);

• 'tile.add':

  mapbox-gl-js/js/source/vector_tile_source.js

  Line 108 in 81f7959

  this.fire('tile.add', {tile: tile});

• 'tile.remove':

  mapbox-gl-js/js/source/vector_tile_source.js

  Line 112 in 81f7959

  this.fire('tile.remove', {tile: tile});

• 'change':

  mapbox-gl-js/js/source/geojson_source.js

  Line 98 in d6c34c8

  this.fire('change');

• 'pitch':

  mapbox-gl-js/js/ui/camera.js

  Line 369 in 9846a4f

  this.fire('pitch', eventData);

• 'render':

  mapbox-gl-js/js/ui/map.js

  Line 861 in 2028b48

  this.fire('render');

[bhousel]

Wow thanks @lyzidiamond! I can help with this..

I just added the touch* events within the past few days, and they are documented, that code just hasn't made it into a release yet.

[lyzidiamond]

@bhousel ah yes, i saw the doc comments in the code and was confused as to why they weren't showing in the docs! Comment above updated.

[lyzidiamond]

@bhousel also I'm happy to add the doc, just need to know which ones to document!

[lyzidiamond]

A bunch more here, including the source.*, layer.* and tile.* events. I'm not sure where to find the style.* events.

mapbox-gl-js/js/ui/map.js

Lines 508 to 527 in 2028b48

	this.style
	.on('load', this._onStyleLoad)
	.on('error', this._forwardStyleEvent)
	.on('change', this._onStyleChange)
	.on('source.add', this._onSourceAdd)
	.on('source.remove', this._onSourceRemove)
	.on('source.load', this._onSourceUpdate)
	.on('source.error', this._forwardSourceEvent)
	.on('source.change', this._onSourceUpdate)
	.on('layer.add', this._forwardLayerEvent)
	.on('layer.remove', this._forwardLayerEvent)
	.on('layer.error', this._forwardLayerEvent)
	.on('tile.add', this._forwardTileEvent)
	.on('tile.remove', this._forwardTileEvent)
	.on('tile.load', this._update)
	.on('tile.error', this._forwardTileEvent)
	.on('tile.stats', this._forwardTileEvent);
	this.on('rotate', this.style._redoPlacement);
	this.on('pitch', this.style._redoPlacement);

[lucaswoj]

I'm not sure where to find the style.* events.

The style. prefix is added here.

Style events are fired throughout the js/style/style.js file. For example, style.load is fired as load here.

[andreasplesch]

As somebody who did some ol3, I was actually looking for map generated events and was wondering if there were any because they are not in listed in the API documentation. In particular, I was looking for an event which is fired whenever a render is completed. map#render seems to fit. It would be great if these events could be documented, even if very briefly. Otherwise adopters will just try to find them in the code. Even a list of available events without documentation (such as above) is very helpful.
(Is there a canonical way to sync across two map canvases ?)

[lyzidiamond]

@lucaswoj @bhousel @jfirebaugh any idea which of the events i listed should have doc and which should be removed? Happy to hit this once I know which is which.

[lucaswoj]

Of the events listed, I think we should document render and error. I don't have any strong opinions about the rest.

[jfirebaugh]

I think these should all be documented except for tile.stats, which is an internal performance diagnostic thing.

[lucaswoj]

I think we should clean up our events architecture by doing the following things:

Already Done

• document touchstart
• document touchmove
• document touchend
• document touchcancel

Step 1

• document pitch
• document render

Step 2

• document error
• merge tile.error with error
• merge style.error with error
• merge source.error with error
• merge tile.error with error
• merge layer.error with error

Step 3

• add pitchstart and pitchend events
• ensure rotatestart and rotateend events are fired in all cases

Step 4

• implement and document data and dataend (ref Add data, datastart and dataend events #1715 (comment))
• remove tile.load in favor of data
• remove tile.stats in favor of data
• remove tile.add in favor of data
• remove tile.remove in favor of data
• remove source.change in favor of data

[lucaswoj]

Split up remaining subtasks into

• Ensure rotatestart and rotateend events are fired in all cases #2448
• Make Evented print a warning message if an "error" event is lost #2447
• Combine all error events #2446
• Add data, datastart and dataend events #1715

[lucaswoj]

Revisiting this at a high level. Now that #3244 has landed we have better visibility into our events:

Events fired in GL JS

• boxzoomcancel
• boxzoomend
• boxzoomstart
• click
• close
• contextmenu
• dblclick
• drag
• dragend
• dragstart
• error
• geolocate
• layer.add
• layer.remove
• load
• mousedown
• mousemove
• mouseout
• mouseup
• move
• moveend
• movestart
• pitch
• remove
• render
• resize
• rotate
• rotateend
• rotatestart
• source.add
• source.change
• source.load
• source.remove
• style.change
• style.load
• tile.add
• tile.load
• tile.remove
• touchcancel
• touchend
• touchmove
• touchstart
• webglcontextlost
• webglcontextrestored
• zoom
• zoomend
• zoomstart

Events Documented in GL JS

• boxzoomcancel
• boxzoomend
• boxzoomstart
• click
• close
• contextmenu
• dblclick
• drag
• dragend
• dragstart
• error
• geolocate
• load
• mousedown
• mousemove
• mouseout
• mouseup
• move
• moveend
• movestart
• pitch
• render
• rotate
• rotateend
• rotatestart
• touchcancel
• touchend
• touchmove
• touchstart
• webglcontextlost
• webglcontextrestored
• zoom
• zoomend
• zoomstart

Events Fired but not Documented

• remove
• resize

Events to be Merged into the data Event

• layer.add
• layer.remove
• source.add
• source.change
• source.load
• source.remove
• style.change
• style.load
• tile.add
• tile.load
• tile.remove