Improve event type documentation.
MODIFY
src/event.js
src/event.js
* API. Each property contained here is a valid target for event handling
* via {@link geo.object#geoOn}. The event object provided to handlers is
* different for each event type. Each handler is generally called with the
- * `this` context being the class that caused the event.<br>
- * <br>
- * The following properties are common to all event objects:
+ * `this` context being the class that caused the event.
*
* @namespace
* @alias geo.event
- * @type {object}
- * @property {string} event The event type that was triggered.
- * @property {object} geo A universal event object for controlling propagation.
+ * @type {geo.event.base}
*
* @example
* map.geoOn(geo.event.layerAdd, function (event) {
*/
var geo_event = {};
+/**
+ * All events are sent an object that are an extension of this type.
+ *
+ * @typedef geo.event.base
+ * @type {object}
+ * @property {string} event The event type that was triggered.
+ * @property {object} geo A universal event object for controlling propagation.
+ */
+
/*
* Event types
*/
@@ -29,7 +34,7 @@ var geo_event = {};
* Triggered when a layer is added to the map.
*
* @event geo.event.layerAdd
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.map} target The current map.
* @property {geo.layer} layer The new layer that was added.
*/
@@ -39,7 +44,7 @@ geo_event.layerAdd = 'geo_layerAdd';
* Triggered when a layer is removed from the map.
*
* @event geo.event.layerRemove
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.map} target The current map.
* @property {geo.layer} layer The old layer that was removed.
*/
@@ -49,7 +54,7 @@ geo_event.layerRemove = 'geo_layerRemove';
* Triggered when the map's zoom level is changed.
*
* @event geo.event.zoom
- * @type {object}
+ * @type {geo.event.base}
* @property {number} zoomLevel New zoom level.
* @property {geo.screenPosition} screenPosition The screen position of the
* mouse pointer.
@@ -61,7 +66,7 @@ geo_event.zoom = 'geo_zoom';
* downward so that positive angles are clockwise rotations).
*
* @event geo.event.rotate
- * @type {object}
+ * @type {geo.event.base}
* @property {number} rotation The angle of the rotation in radians. This is
* the map's complete rotation, not a delta.
* @property {geo.screenPosition} screenPosition The screen position of the
@@ -74,7 +79,7 @@ geo_event.rotate = 'geo_rotate';
* transition.
*
* @event geo.event.pan
- * @type {object}
+ * @type {geo.event.base}
* @property {object} screenDelta The number of pixels of the pan.
* @property {number} screenDelta.x Horizontal pan distance in pixels.
* @property {number} screenDelta.y Vertical pan distance in pixels.
@@ -85,7 +90,7 @@ geo_event.pan = 'geo_pan';
* Triggered when the map's canvas is resized.
*
* @event geo.event.resize
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.map} target The map that was resized.
* @property {number} width The new width in pixels.
* @property {number} height The new height in pixels.
@@ -96,7 +101,7 @@ geo_event.resize = 'geo_resize';
* Triggered on every call to {@link geo.map#draw} before the map is rendered.
*
* @event geo.event.draw
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.map} target The current map.
*/
geo_event.draw = 'geo_draw';
@@ -105,7 +110,7 @@ geo_event.draw = 'geo_draw';
* Triggered on every call to {@link geo.map#draw} after the map is rendered.
*
* @event geo.event.drawEnd
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.map} target The current map.
*/
geo_event.drawEnd = 'geo_drawEnd';
@@ -115,6 +120,7 @@ geo_event.drawEnd = 'geo_drawEnd';
* might occur. The event object extends {@link geo.mouseState}.
*
* @event geo.event.mousemove
+ * @type {(geo.event.base|geo.mouseState)}
*/
geo_event.mousemove = 'geo_mousemove';
@@ -123,6 +129,7 @@ geo_event.mousemove = 'geo_mousemove';
* `mousedown` event. The event object extends {@link geo.mouseState}.
*
* @event geo.event.mouseclick
+ * @type {(geo.event.base|geo.mouseState)}
* @property {geo.mouseButtons} buttonsDown The buttons that were down at the
* start of the click action.
*/
@@ -133,6 +140,7 @@ geo_event.mouseclick = 'geo_mouseclick';
* The event object extends {@link geo.brushSelection}.
*
* @event geo.event.brush
+ * @type {(geo.event.base|geo.brushSelection)}
*/
geo_event.brush = 'geo_brush';
@@ -141,6 +149,7 @@ geo_event.brush = 'geo_brush';
* The event object extends {@link geo.brushSelection}.
*
* @event geo.event.brushend
+ * @type {(geo.event.base|geo.brushSelection)}
*/
geo_event.brushend = 'geo_brushend';
@@ -149,6 +158,7 @@ geo_event.brushend = 'geo_brushend';
* The event object extends {@link geo.brushSelection}.
*
* @event geo.event.brushstart
+ * @type {(geo.event.base|geo.brushSelection)}
*/
geo_event.brushstart = 'geo_brushstart';
@@ -157,6 +167,7 @@ geo_event.brushstart = 'geo_brushstart';
* The event object extends {@link geo.brushSelection}.
*
* @event geo.event.select
+ * @type {(geo.event.base|geo.brushSelection)}
*/
geo_event.select = 'geo_select';
@@ -165,6 +176,7 @@ geo_event.select = 'geo_select';
* The event object extends {@link geo.brushSelection}.
*
* @event geo.event.zoomselect
+ * @type {(geo.event.base|geo.brushSelection)}
*/
geo_event.zoomselect = 'geo_zoomselect';
@@ -173,6 +185,7 @@ geo_event.zoomselect = 'geo_zoomselect';
* The event object extends {@link geo.brushSelection}.
*
* @event geo.event.unzoomselect
+ * @type {(geo.event.base|geo.brushSelection)}
*/
geo_event.unzoomselect = 'geo_unzoomselect';
@@ -181,6 +194,7 @@ geo_event.unzoomselect = 'geo_unzoomselect';
* Triggered when an action is initiated with mouse down.
*
* @event geo.event.actiondown
+ * @type {geo.event.base}
* @property {geo.actionState} state The action state.
* @property {geo.mouseState} mouse The mouse state.
* @property {jQuery.Event} event The triggering jQuery event.
@@ -191,6 +205,7 @@ geo_event.actiondown = 'geo_actiondown';
* Triggered when an action is being processed during mouse movement.
*
* @event geo.event.actionmove
+ * @type {geo.event.base}
* @property {geo.actionState} state The action state.
* @property {geo.mouseState} mouse The mouse state.
* @property {jQuery.Event} event The triggering event.
@@ -201,6 +216,7 @@ geo_event.actionmove = 'geo_actionmove';
* Triggered when an action is ended with a mouse up.
*
* @event geo.event.actionup
+ * @type {geo.event.base}
* @property {geo.actionState} state The action state.
* @property {geo.mouseState} mouse The mouse state.
* @property {jQuery.Event} event The triggering event.
@@ -211,6 +227,7 @@ geo_event.actionup = 'geo_actionup';
* Triggered when an action results in a selection.
*
* @event geo.event.actionselection
+ * @type {geo.event.base}
* @property {geo.actionState} state The action state.
* @property {geo.mouseState} mouse The mouse state.
* @property {jQuery.Event} event The triggering event.
@@ -225,6 +242,7 @@ geo_event.actionselection = 'geo_actionselection';
* Triggered when an action is triggered with a mouse wheel event.
*
* @event geo.event.actionwheel
+ * @type {geo.event.base}
* @property {geo.actionState} state The action state.
* @property {geo.mouseState} mouse The mouse state.
* @property {jQuery.Event} event The triggering event.
@@ -235,6 +253,7 @@ geo_event.actionwheel = 'geo_actionwheel';
* Triggered when an action is triggered via the keyboard.
*
* @event geo.event.keyaction
+ * @type {geo.event.base}
* @property {object} move The movement that would happen if the action is
* passed through.
* @property {number} [move.zoomDelta] A change in the zoom level.
@@ -260,7 +279,7 @@ geo_event.keyaction = 'geo_keyaction';
* transition options can be modified in place.
*
* @event geo.event.transitionstart
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.geoPosition} center The target center.
* @property {number} zoom The target zoom level.
* @property {number} duration The duration of the transition in milliseconds.
@@ -272,7 +291,7 @@ geo_event.transitionstart = 'geo_transitionstart';
* Triggered after a map navigation animation ends.
*
* @event geo.event.transitionend
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.geoPosition} center The target center.
* @property {number} zoom The target zoom level.
* @property {number} duration The duration of the transition in milliseconds.
@@ -284,7 +303,7 @@ geo_event.transitionend = 'geo_transitionend';
* Triggered if a map navigation animation is canceled.
*
* @event geo.event.transitioncancel
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.geoPosition} center The target center.
* @property {number} zoom The target zoom level.
* @property {number} duration The duration of the transition in milliseconds.
@@ -296,7 +315,7 @@ geo_event.transitioncancel = 'geo_transitioncancel';
* Triggered when the parallel projection mode is changes.
*
* @event geo.event.parallelprojection
- * @type {object}
+ * @type {geo.event.base}
* @property {boolean} paralellProjection `true` if parallel projection is
* turned on.
*/
@@ -319,6 +338,7 @@ geo_event.feature = {
* moves.
*
* @event geo.event.feature.mousemove
+ * @type {geo.event.base}
* @property {object} data The feature data the mouse is over.
* @property {number} index The index of the feature data the mouse is over.
* @property {object} extra Extra information about the feature and mouse
@@ -335,6 +355,7 @@ geo_event.feature = {
* above it.
*
* @event geo.event.feature.mouseover
+ * @type {geo.event.base}
* @property {object} data The feature data the mouse is over.
* @property {number} index The index of the feature data the mouse is over.
* @property {object} extra Extra information about the feature and mouse
@@ -351,6 +372,7 @@ geo_event.feature = {
* or the order of the feature components that it is over.
*
* @event geo.event.feature.mouseover_order
+ * @type {geo.event.base}
* @property {geo.feature} feature The feature.
* @property {geo.mouseState} mouse The mouse state.
* @proeprty {geo.feature.searchResult} over A list of feature components
@@ -365,6 +387,7 @@ geo_event.feature = {
* no longer above it.
*
* @event geo.event.feature.mouseout
+ * @type {geo.event.base}
* @property {object} data The feature data the mouse is over.
* @property {number} index The index of the feature data the mouse is over.
* @property {object} extra Extra information about the feature and mouse
@@ -381,6 +404,7 @@ geo_event.feature = {
* feature.
*
* @event geo.event.feature.mouseon
+ * @type {geo.event.base}
* @property {object} data The feature data the mouse is on.
* @property {number} index The index of the feature data the mouse is on.
* @property {geo.mouseState} mouse The mouse state.
@@ -391,6 +415,7 @@ geo_event.feature = {
* component of a feature.
*
* @event geo.event.feature.mouseoff
+ * @type {geo.event.base}
* @property {object} data The feature data the mouse is off.
* @property {number} index The index of the feature data the mouse is off.
* @property {geo.mouseState} mouse The mouse state.
@@ -398,13 +423,26 @@ geo_event.feature = {
mouseoff: 'geo_feature_mouseoff',
/**
* The event is the feature version of {@link geo.event.mouseclick}.
+ *
* @event geo.event.feature.mouseclick
+ * @type {geo.event.base}
+ * @property {object} data The feature data the mouse is off.
+ * @property {number} index The index of the feature data the mouse is off.
+ * @property {object} extra Extra information about the feature and mouse
+ * location.
+ * @property {geo.mouseState} mouse The mouse state.
+ * @property {number} eventID a monotonically increasing event number. All
+ * features that the mouse clicks simultaneously will have the same
+ * `eventID`.
+ * @property {boolean} top True if this is the topmost data element.
*/
mouseclick: 'geo_feature_mouseclick',
/**
* The event contains the `feature`, the `mouse` record, and `over`, the
* record of data elements that are unrder the mouse.
+ *
* @event geo.event.feature.mouseclick_order
+ * @type {geo.event.base}
* @property {geo.feature} feature The feature that was clicked.
* @property {geo.mouseState} mouse The mouse state.
* @proeprty {geo.feature.searchResult} over A list of feature components
@@ -416,6 +454,7 @@ geo_event.feature = {
* that has just finished its selection.
*
* @event geo.event.feature.brushend
+ * @type {geo.event.base}
* @property {object} data The feature data the mouse is over.
* @property {number} index The index of the feature data the mouse is over.
* @property {geo.mouseState} mouse The mouse state.
@@ -431,6 +470,7 @@ geo_event.feature = {
* brush.
*
* @event geo.event.feature.brush
+ * @type {geo.event.base}
* @property {object} data The feature data the mouse is over.
* @property {number} index The index of the feature data the mouse is over.
* @property {geo.mouseState} mouse The mouse state.
@@ -453,7 +493,7 @@ geo_event.pixelmap = {
* rendered once.
*
* @event geo.event.pixelmap.prepared
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.pixelmapFeature} pixelmap The pixelmap object that was
* prepared.
*/
@@ -469,6 +509,7 @@ geo_event.screenshot = {
* Triggered when a screenshot has been completed.
*
* @event geo.event.screenshot.ready
+ * @type {geo.event.base}
* @property {HTMLCanvasElement} canvas The canvas used to take the
* screenshot.
* @property {string|HTMLCanvasElement} screenshot The screenshot as a
@@ -489,7 +530,7 @@ geo_event.camera = {};
* bounds). This is equivalent to the union of pan and zoom.
*
* @event geo.event.camera.view
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.camera} camera The camera instance.
*/
geo_event.camera.view = 'geo_camera_view';
@@ -498,6 +539,7 @@ geo_event.camera.view = 'geo_camera_view';
* Triggered after a projection change.
*
* @event geo.event.camera.projection
+ * @type {geo.event.base}
* @property {geo.camera} camera The camera instance.
* @property {string} type The projection type, either `'perspective'` or
* `'parallel'`.
@@ -508,6 +550,7 @@ geo_event.camera.projection = 'geo_camera_projection';
* Triggered after a viewport change.
*
* @event geo.event.camera.viewport
+ * @type {geo.event.base}
* @property {geo.camera} camera The camera instance.
* @property {geo.screenSize} viewport The new viewport size.
*/
@@ -523,7 +566,7 @@ geo_event.annotation = {};
* Triggered when an annotation has been added.
*
* @event geo.event.annotation.add
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.annotation} annotation The annotation that was added.
*/
geo_event.annotation.add = 'geo_annotation_add';
@@ -532,7 +575,7 @@ geo_event.annotation.add = 'geo_annotation_add';
* Triggered when an annotation is about to be added.
*
* @event geo.event.annotation.add_before
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.annotation} annotation The annotation that will be added.
*/
geo_event.annotation.add_before = 'geo_annotation_add_before';
@@ -542,7 +585,7 @@ geo_event.annotation.add_before = 'geo_annotation_add_before';
* triggered when updating existing annotations via the geojson function.
*
* @event geo.event.annotation.update
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.annotation} annotation The annotation that was altered.
*/
geo_event.annotation.update = 'geo_annotation_update';
@@ -551,7 +594,7 @@ geo_event.annotation.update = 'geo_annotation_update';
* Triggered when an annotation's coordinates have been updated.
*
* @event geo.event.annotation.coordinates
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.annotation} annotation The annotation that was altered.
*/
geo_event.annotation.coordinates = 'geo_annotation_coordinates';
@@ -560,7 +603,7 @@ geo_event.annotation.coordinates = 'geo_annotation_coordinates';
* Triggered when an annotation's edit handle is selected or released.
*
* @event geo.event.annotation.select_edit_handle
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.annotation} annotation The annotation that has an edit handle
* selected or unselected.
* @property {object} handle Information on the edit handle.
@@ -573,7 +616,7 @@ geo_event.annotation.select_edit_handle = 'geo_annotation_select_edit_handle';
* Triggered when an action is performed on an annotation's edit handle.
*
* @event geo.event.annotation.edit_action
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.annotation} annotation The annotation that has an edit handle
* selected or unselected.
* @property {object} handle Information on the edit handle.
@@ -587,7 +630,7 @@ geo_event.annotation.edit_action = 'geo_annotation_edit_action';
* Triggered when an annotation has been removed.
*
* @event geo.event.annotation.remove
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.annotation} annotation The annotation that was removed.
*/
geo_event.annotation.remove = 'geo_annotation_remove';
@@ -596,7 +639,7 @@ geo_event.annotation.remove = 'geo_annotation_remove';
* Triggered when an annotation's state changes.
*
* @event geo.event.annotation.state
- * @type {object}
+ * @type {geo.event.base}
* @property {geo.annotation} annotation The annotation that changed.
*/
geo_event.annotation.state = 'geo_annotation_state';
@@ -605,7 +648,7 @@ geo_event.annotation.state = 'geo_annotation_state';
* Triggered when the annotation mode is changed.
*
* @event geo.event.annotation.mode
- * @type {object}
+ * @type {geo.event.base}
* @property {string?} mode The new annotation mode. This is one of the values
* from {@link geo.annotation.state}.
* @property {string?} oldMode The annotation mode before this change. This is

Improve event type documentation.