Merge pull request #1898 from ahocevar/events

Document events

src/ol/collection.js

@@ -16,7 +16,17 @@ goog.require('ol.Object');
  * @enum {string}
  */
 ol.CollectionEventType = {
+  /**
+   * Triggered when an item is added to the collection.
+   * @event ol.CollectionEvent#add
+   * @todo stability experimental
+   */
   ADD: 'add',
+  /**
+   * Triggered when an item is removed from the collection.
+   * @event ol.CollectionEvent#remove
+   * @todo stability experimental
+   */
   REMOVE: 'remove'
 };
 
@@ -35,7 +45,9 @@ ol.CollectionEvent = function(type, opt_element, opt_target) {
   goog.base(this, type, opt_target);
 
   /**
+   * The element that is added to or removed from the collection.
    * @type {*}
+   * @todo stability experimental
    */
   this.element = opt_element;
 
@@ -56,6 +68,7 @@ ol.CollectionProperty = {
  * A mutable MVC Array.
  * @constructor
  * @extends {ol.Object}
+ * @fires {@link ol.CollectionEvent} ol.CollectionEvent
  * @param {Array=} opt_array Array.
  * @todo stability experimental
  * @todo observable length {number} readonly the length of the array

src/ol/interaction/draganddropinteraction.js

@@ -19,6 +19,8 @@ goog.require('ol.proj');
 /**
  * @constructor
  * @extends {ol.interaction.Interaction}
+ * @fires {@link ol.interaction.DragAndDropEvent}
+ *     ol.interaction.DragAndDropEvent
  * @param {olx.interaction.DragAndDropOptions=} opt_options Options.
  */
 ol.interaction.DragAndDrop = function(opt_options) {
@@ -175,6 +177,11 @@ ol.interaction.DragAndDrop.prototype.tryReadFeatures_ = function(format, text) {
  * @enum {string}
  */
 ol.interaction.DragAndDropEventType = {
+  /**
+   * Triggered when features are added
+   * @event ol.interaction.DragAndDropEvent#addfeatures
+   * @todo stability experimental
+   */
   ADD_FEATURES: 'addfeatures'
 };
 
@@ -196,11 +203,13 @@ ol.interaction.DragAndDropEvent =
 
   /**
    * @type {Array.<ol.Feature>|undefined}
+   * @todo stability experimental
    */
   this.features = opt_features;
 
   /**
    * @type {ol.proj.Projection|undefined}
+   * @todo stability experimental
    */
   this.projection = opt_projection;
 

src/ol/interaction/dragboxinteraction.js

@@ -31,7 +31,17 @@ ol.DRAG_BOX_HYSTERESIS_PIXELS_SQUARED =
  * @enum {string}
  */
 ol.DragBoxEventType = {
+  /**
+   * Triggered upon drag box start.
+   * @event ol.DragBoxEvent#boxstart
+   * @todo stability experimental
+   */
   BOXSTART: 'boxstart',
+  /**
+   * Triggered upon drag box end.
+   * @event ol.DragBoxEvent#boxstart
+   * @todo stability experimental
+   */
   BOXEND: 'boxend'
 };
 
@@ -70,6 +80,7 @@ goog.inherits(ol.DragBoxEvent, goog.events.Event);
  *
  * @constructor
  * @extends {ol.interaction.Pointer}
+ * @fires {@link ol.DragBoxEvent} ol.DragBoxEvent
  * @param {olx.interaction.DragBoxOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/interaction/drawinteraction.js

@@ -29,7 +29,17 @@ goog.require('ol.style.Style');
  * @enum {string}
  */
 ol.DrawEventType = {
+  /**
+   * Triggered upon feature draw start
+   * @event ol.DrawEvent#drawstart
+   * @todo stability experimental
+   */
   DRAWSTART: 'drawstart',
+  /**
+   * Triggered upon feature draw end
+   * @event ol.DrawEvent#drawend
+   * @todo stability experimental
+   */
   DRAWEND: 'drawend'
 };
 
@@ -47,7 +57,9 @@ ol.DrawEvent = function(type, feature) {
   goog.base(this, type);
 
   /**
+   * The feature being drawn.
    * @type {ol.Feature}
+   * @todo stability experimental
    */
   this.feature = feature;
 
@@ -60,6 +72,7 @@ goog.inherits(ol.DrawEvent, goog.events.Event);
  * Interaction that allows drawing geometries
  * @constructor
  * @extends {ol.interaction.Pointer}
+ * @fires {@link ol.DrawEvent} ol.DrawEvent
  * @param {olx.interaction.DrawOptions} options Options.
  * @todo stability experimental
  */

src/ol/layer/heatmaplayer.js

@@ -24,6 +24,7 @@ ol.layer.HeatmapLayerProperty = {
 /**
  * @constructor
  * @extends {ol.layer.Vector}
+ * @fires {@link ol.render.Event} ol.render.Event
  * @param {olx.layer.HeatmapOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/layer/imagelayer.js

@@ -7,6 +7,7 @@ goog.require('ol.layer.Layer');
 /**
  * @constructor
  * @extends {ol.layer.Layer}
+ * @fires {@link ol.render.Event} ol.render.Event
  * @param {olx.layer.LayerOptions} options Layer options.
  * @todo stability experimental
  */

src/ol/layer/layer.js

@@ -12,6 +12,7 @@ goog.require('ol.source.Source');
 /**
  * @constructor
  * @extends {ol.layer.Base}
+ * @fires {@link ol.render.Event} ol.render.Event
  * @param {olx.layer.LayerOptions} options Layer options.
  * @todo stability experimental
  * @todo observable brightness {number} the brightness of the layer

src/ol/layer/tilelayer.js

@@ -16,6 +16,7 @@ ol.layer.TileProperty = {
 /**
  * @constructor
  * @extends {ol.layer.Layer}
+ * @fires {@link ol.render.Event} ol.render.Event
  * @param {olx.layer.TileOptions} options Tile layer options.
  * @todo stability experimental
  * @todo observable preload {number} the level to preload tiles up to

src/ol/layer/vectorlayer.js

@@ -10,6 +10,7 @@ goog.require('ol.layer.Layer');
 /**
  * @constructor
  * @extends {ol.layer.Layer}
+ * @fires {@link ol.render.Event} ol.render.Event
  * @param {olx.layer.VectorOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/map.js

@@ -156,6 +156,9 @@ ol.MapProperty = {
  * @constructor
  * @extends {ol.Object}
  * @param {olx.MapOptions} options Map options.
+ * @fires {@link ol.MapBrowserEvent} ol.MapBrowserEvent
+ * @fires {@link ol.MapEvent} ol.MapEvent
+ * @fires {@link ol.render.Event} ol.render.Event
  * @todo stability experimental
  * @todo observable layergroup {ol.layer.LayerGroup} a layer group containing
  *       the layers in this map.
@@ -766,7 +769,8 @@ ol.Map.prototype.getViewport = function() {
 /**
  * @return {Element} The map's overlay container. Elements added to this
  * container will let mousedown and touchstart events through to the map, so
- * clicks and gestures on an overlay will trigger MapBrowserEvent events.
+ * clicks and gestures on an overlay will trigger {@link ol.MapBrowserEvent}
+ * events.
  */
 ol.Map.prototype.getOverlayContainer = function() {
   return this.overlayContainer_;
@@ -776,7 +780,8 @@ ol.Map.prototype.getOverlayContainer = function() {
 /**
  * @return {Element} The map's overlay container. Elements added to this
  * container won't let mousedown and touchstart events through to the map, so
- * clicks and gestures on an overlay don't trigger any MapBrowserEvent.
+ * clicks and gestures on an overlay don't trigger any
+ * {@link ol.MapBrowserEvent}.
  */
 ol.Map.prototype.getOverlayContainerStopEvent = function() {
   return this.overlayContainerStopEvent_;

src/ol/mapbrowserevent.js

@@ -41,16 +41,19 @@ ol.MapBrowserEvent = function(type, map, browserEvent, opt_frameState) {
   /**
    * @const
    * @type {Event}
+   * @todo stability experimental
    */
   this.originalEvent = browserEvent.getBrowserEvent();
 
   /**
    * @type {ol.Coordinate}
+   * @todo stability experimental
    */
   this.coordinate = map.getEventCoordinate(this.originalEvent);
 
   /**
    * @type {ol.Pixel}
+   * @todo stability experimental
    */
   this.pixel = map.getEventPixel(this.originalEvent);
 
@@ -460,11 +463,32 @@ ol.MapBrowserEventHandler.prototype.disposeInternal = function() {
  */
 ol.MapBrowserEvent.EventType = {
   // derived event types
+  /**
+   * A true single click with no dragging and no double click. Note that this
+   * event is delayed by 250 ms to ensure that it is not a double click.
+   * @event ol.MapBrowserEvent#singleclick
+   * @todo stability experimental
+   */
   SINGLECLICK: 'singleclick',
+  /**
+   * A true double click, with no dragging.
+   * @event ol.MapBrowserEvent#dblclick
+   * @todo stability experimental
+   */
   DBLCLICK: goog.events.EventType.DBLCLICK,
+  /**
+   * Triggered when a pointer is dragged.
+   * @event ol.MapBrowserEvent#pointerdrag
+   * @todo stability experimental
+   */
   POINTERDRAG: 'pointerdrag',
 
   // original pointer event types
+  /**
+   * Triggered when a pointer is moved.
+   * @event ol.MapBrowserEvent#pointermove
+   * @todo stability experimental
+   */
   POINTERMOVE: 'pointermove',
   POINTERDOWN: 'pointerdown',
   POINTERUP: 'pointerup',

src/ol/mapevent.js

@@ -8,7 +8,17 @@ goog.require('goog.events.Event');
  * @enum {string}
  */
 ol.MapEventType = {
+  /**
+   * Triggered after a map frame is rendered.
+   * @event ol.MapEvent#postrender
+   * @todo stability experimental
+   */
   POSTRENDER: 'postrender',
+  /**
+   * Triggered after the map is moved.
+   * @event ol.MapEvent#moveend
+   * @todo stability experimental
+   */
   MOVEEND: 'moveend'
 };
 

src/ol/object.js

@@ -20,7 +20,17 @@ goog.require('ol.Observable');
  * @enum {string}
  */
 ol.ObjectEventType = {
+  /**
+   * Triggered before a property is changed.
+   * @event ol.ObjectEvent#beforepropertychange
+   * @todo stability experimental
+   */
   BEFOREPROPERTYCHANGE: 'beforepropertychange',
+  /**
+   * Triggered when a property is changed.
+   * @event ol.ObjectEvent#propertychange
+   * @todo stability experimental
+   */
   PROPERTYCHANGE: 'propertychange'
 };
 
@@ -99,6 +109,7 @@ ol.ObjectAccessor.prototype.transform = function(from, to) {
  * @constructor
  * @extends {ol.Observable}
  * @param {Object.<string, *>=} opt_values Values.
+ * @fires {@link ol.ObjectEvent} ol.ObjectEvent
  * @todo stability experimental
  */
 ol.Object = function(opt_values) {

src/ol/observable.js

@@ -8,7 +8,8 @@ goog.require('goog.events.EventType');
 
 /**
  * An event target providing convenient methods for listener registration
- * and unregistration.
+ * and unregistration. A generic `change` event is always available through
+ * {@link ol.Observable#dispatchChangeEvent}.
  * @constructor
  * @extends {goog.events.EventTarget}
  * @suppress {checkStructDictInheritance}
@@ -30,6 +31,9 @@ goog.inherits(ol.Observable, goog.events.EventTarget);
 
 
 /**
+ * Dispatches a `change` event. Register a listener for this event to get
+ * notified of changes.
+ * @fires change
  * @todo stability experimental
  */
 ol.Observable.prototype.dispatchChangeEvent = function() {

src/ol/render/renderevent.js

@@ -9,8 +9,20 @@ goog.require('ol.render.IVectorContext');
  * @enum {string}
  */
 ol.render.EventType = {
+  /**
+   * @event ol.render.Event#postcompose
+   * @todo stability experimental
+   */
   POSTCOMPOSE: 'postcompose',
+  /**
+   * @event ol.render.Event#precompose
+   * @todo stability experimental
+   */
   PRECOMPOSE: 'precompose',
+  /**
+   * @event ol.render.Event#render
+   * @todo stability experimental
+   */
   RENDER: 'render'
 };
 
@@ -35,21 +47,29 @@ ol.render.Event = function(
 
   /**
    * @type {ol.render.IVectorContext|undefined}
+   * @todo stability experimental
    */
   this.vectorContext = opt_vectorContext;
 
   /**
    * @type {oli.FrameState|undefined}
+   * @todo stability experimental
    */
   this.frameState = opt_frameState;
 
   /**
+   * Canvas context. Only available when a Canvas renderer is used,
+   * null otherwise.
    * @type {CanvasRenderingContext2D|null|undefined}
+   * @todo stability experimental
    */
   this.context = opt_context;
 
   /**
+   * WebGL context. Only available when a WebGL renderer is used, null
+   * otherwise.
    * @type {ol.webgl.Context|null|undefined}
+   * @todo stability experimental
    */
   this.glContext = opt_glContext;
 

src/ol/source/geojsonsource.js

@@ -8,6 +8,7 @@ goog.require('ol.source.VectorFile');
 /**
  * @constructor
  * @extends {ol.source.VectorFile}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.GeoJSONOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/source/gpxsource.js

@@ -8,6 +8,7 @@ goog.require('ol.source.VectorFile');
 /**
  * @constructor
  * @extends {ol.source.VectorFile}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.GPXOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/source/igcsource.js

@@ -8,6 +8,7 @@ goog.require('ol.source.VectorFile');
 /**
  * @constructor
  * @extends {ol.source.VectorFile}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.IGCOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/source/kmlsource.js

@@ -8,6 +8,7 @@ goog.require('ol.source.VectorFile');
 /**
  * @constructor
  * @extends {ol.source.VectorFile}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.KMLOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/source/osmxmlsource.js

@@ -8,6 +8,7 @@ goog.require('ol.source.VectorFile');
 /**
  * @constructor
  * @extends {ol.source.VectorFile}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.OSMXMLOptions=} opt_options Options.
  */
 ol.source.OSMXML = function(opt_options) {

src/ol/source/topojsonsource.js

@@ -8,6 +8,7 @@ goog.require('ol.source.VectorFile');
 /**
  * @constructor
  * @extends {ol.source.VectorFile}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.TopoJSONOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/source/vectorfilesource.js

@@ -22,6 +22,7 @@ goog.require('ol.xml');
 /**
  * @constructor
  * @extends {ol.source.Vector}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.VectorFileOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/source/vectorsource.js

@@ -21,7 +21,17 @@ goog.require('ol.structs.RBush');
  * @enum {string}
  */
 ol.source.VectorEventType = {
+  /**
+   * Triggered when a feature is added to the source.
+   * @event ol.source.VectorEvent#addfeature
+   * @todo stability experimental
+   */
   ADDFEATURE: 'addfeature',
+  /**
+   * Triggered when a feature is removed from the source.
+   * @event ol.source.VectorEvent#removefeature
+   * @todo stability experimental
+   */
   REMOVEFEATURE: 'removefeature'
 };
 
@@ -30,6 +40,7 @@ ol.source.VectorEventType = {
 /**
  * @constructor
  * @extends {ol.source.Source}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.VectorOptions=} opt_options Vector source options.
  * @todo stability experimental
  */
@@ -372,7 +383,9 @@ ol.source.VectorEvent = function(type, opt_feature) {
   goog.base(this, type);
 
   /**
+   * The feature being added or removed.
    * @type {ol.Feature|undefined}
+   * @todo stability experimental
    */
   this.feature = opt_feature;