Merge pull request #1024 from pagameba/doc-interactions

Documentation for Interactions

src/objectliterals.jsdoc

@@ -52,7 +52,9 @@
  * @typedef {Object} ol.MapOptions
  * @property {ol.Collection|Array.<ol.control.Control>|undefined} controls
  *     Controls initially added to the map.
- * @property {ol.Collection|undefined} interactions Interactions.
+ * @property {ol.Collection|undefined} interactions A collection of
+ *     {@link ol.interaction|ol.interaction.Interaction} instances that allow the user to interact with
+ *     the map.
  * @property {Array.<ol.layer.Base>|ol.Collection|undefined} layers Layers.
  * @property {ol.Collection|Array.<ol.Overlay>|undefined} overlays
  *     Overlays initially added to the map.
@@ -237,28 +239,36 @@
 /**
  * @typedef {Object} ol.interaction.DoubleClickZoomOptions
  * @property {number|undefined} delta The zoom delta applied on each double
- *    click.
+ *     click, default is 1.
  */
 
 /**
  * @typedef {Object} ol.interaction.DragPanOptions
- * @property {ol.Kinetic|undefined} kinetic Kinetic.
+ * @property {ol.Kinetic|undefined} kinetic Kinetic inertia to apply to the pan.
- * @property {ol.interaction.ConditionType|undefined} condition Condition.
+ * @property {ol.interaction.ConditionType|undefined} condition A conditional
+ *     modifier (i.e. Shift key) that determines if the interaction is active
+ *     or not, default is no modifiers.
  */
 
 /**
  * @typedef {Object} ol.interaction.DragRotateOptions
- * @property {ol.interaction.ConditionType|undefined} condition Condition.
+ * @property {ol.interaction.ConditionType|undefined} condition A conditional
+ *     modifier (i.e. Shift key) that determines if the interaction is active
+ *     or not, default is both shift and alt keys.
  */
 
 /**
  * @typedef {Object} ol.interaction.DragRotateAndZoomOptions
- * @property {ol.interaction.ConditionType|undefined} condition Condition.
+ * @property {ol.interaction.ConditionType|undefined} condition A conditional
+ *     modifier (i.e. Shift key) that determines if the interaction is active
+ *     or not, default is shify key.
  */
 
 /**
  * @typedef {Object} ol.interaction.DragZoomOptions
- * @property {ol.interaction.ConditionType|undefined} condition Condition.
+ * @property {ol.interaction.ConditionType|undefined} condition A conditional
+ *     modifier (i.e. Shift key) that determines if the interaction is active
+ *     or not, default is shift key.
  */
 
 /**
@@ -284,26 +294,34 @@
 
 /**
  * @typedef {Object} ol.interaction.KeyboardPanOptions
- * @property {ol.interaction.ConditionType|undefined} condition Condition.
+ * @property {ol.interaction.ConditionType|undefined} condition A conditional
- * @property {number|undefined} pixelDelta Pixel delta
+ *     modifier (i.e. Shift key) that determines if the interaction is active
+ *     or not, default is no modifiers.
+ * @property {number|undefined} pixelDelta Pixel The amount to pan on each key
+ *     press
  */
 
 /**
  * @typedef {Object} ol.interaction.KeyboardZoomOptions
- * @property {ol.interaction.ConditionType|undefined} condition Condition.
+ * @property {ol.interaction.ConditionType|undefined} condition A conditional
- * @property {number|undefined} delta Delta.
+ *     modifier (i.e. Shift key) that determines if the interaction is active
+ *     or not, default is no modifiers.
+ * @property {number|undefined} delta The amount to zoom on each key press.
  */
 
 /**
  * @typedef {Object} ol.interaction.SelectOptions
- * @property {ol.interaction.ConditionType|undefined} condition Condition.
+ * @property {ol.interaction.ConditionType|undefined} condition A conditional
+ *     modifier (i.e. Shift key) that determines if the interaction is active
+ *     or not, default is on mouse click only.
  * @property {undefined|function(ol.layer.Layer):boolean} layerFilter Filter
  *     function to restrict selection to a subset of layers.
  */
 
 /**
  * @typedef {Object} ol.interaction.TouchPanOptions
- * @property {ol.Kinetic|undefined} kinetic Kinetic.
+ * @property {ol.Kinetic|undefined} kinetic Kinetic inertia to apply to the
+ *     pan.
  */
 
 /**

src/ol/interaction/condition.js

@@ -39,6 +39,7 @@ ol.interaction.condition.altShiftKeysOnly = function(mapBrowserEvent) {
 
 
 /**
+ * Always true.
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
  * @return {boolean} True.
  */
@@ -47,7 +48,7 @@ ol.interaction.condition.always = goog.functions.TRUE;
 
 /**
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
- * @return {boolean} True only the event is a click event.
+ * @return {boolean} True if the event is a click event.
  */
 ol.interaction.condition.clickOnly = function(mapBrowserEvent) {
   var browserEvent = mapBrowserEvent.browserEvent;
@@ -57,7 +58,7 @@ ol.interaction.condition.clickOnly = function(mapBrowserEvent) {
 
 /**
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
- * @return {boolean} True if only the no modifier keys are pressed.
+ * @return {boolean} True only if there no modifier keys are pressed.
  */
 ol.interaction.condition.noModifierKeys = function(mapBrowserEvent) {
   var browserEvent = mapBrowserEvent.browserEvent;
@@ -96,7 +97,7 @@ ol.interaction.condition.shiftKeyOnly = function(mapBrowserEvent) {
 
 /**
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
- * @return {boolean} True if the target element is not editable.
+ * @return {boolean} True only if the target element is not editable.
  */
 ol.interaction.condition.targetNotEditable = function(mapBrowserEvent) {
   var browserEvent = mapBrowserEvent.browserEvent;

src/ol/interaction/condition.jsdoc

@@ -0,0 +1,3 @@
+/**
+ * @namespace ol.interaction.condition
+ */

src/ol/interaction/doubleclickzoom.exports

@@ -0,0 +1 @@
+@exportClass ol.interaction.DoubleClickZoom ol.interaction.DoubleClickZoomOptions

src/ol/interaction/doubleclickzoominteraction.js

@@ -16,6 +16,8 @@ ol.interaction.DOUBLECLICKZOOM_ANIMATION_DURATION = 250;
 
 
 /**
+ * Allows the user to zoom by double-clicking on the map.
+ *
  * @constructor
  * @extends {ol.interaction.Interaction}
  * @param {ol.interaction.DoubleClickZoomOptions=} opt_options Options.

src/ol/interaction/draginteraction.js

@@ -12,6 +12,7 @@ goog.require('ol.interaction.Interaction');
 
 
 /**
+ * Base class for interactions that drag the map.
  * @constructor
  * @extends {ol.interaction.Interaction}
  */

src/ol/interaction/dragpan.exports

@@ -0,0 +1 @@
+@exportClass ol.interaction.DragPan ol.interaction.DragPanOptions

src/ol/interaction/dragpaninteraction.js

@@ -14,6 +14,7 @@ goog.require('ol.interaction.condition');
 
 
 /**
+ * Allows the user to pan the map by clickng and dragging.
  * @constructor
  * @extends {ol.interaction.Drag}
  * @param {ol.interaction.DragPanOptions=} opt_options Options.

src/ol/interaction/dragrotate.exports

@@ -0,0 +1 @@
+@exportClass ol.interaction.DragRotate ol.interaction.DragRotateOptions

src/ol/interaction/dragrotateandzoominteraction.js

@@ -18,6 +18,11 @@ ol.interaction.DRAGROTATEANDZOOM_ANIMATION_DURATION = 400;
 
 
 /**
+ * Allows the user to zoom and rotate the map by clicking and dragging
+ * on the map.  By default, this interaction is limited to when the shift
+ * key is held down.
+ *
+ * This interaction is not included in the default interactions.
  * @constructor
  * @extends {ol.interaction.Drag}
  * @param {ol.interaction.DragRotateAndZoomOptions=} opt_options Options.

src/ol/interaction/dragrotateinteraction.js

@@ -15,6 +15,9 @@ ol.interaction.DRAGROTATE_ANIMATION_DURATION = 250;
 
 
 /**
+ * Allows the user to rotate the map by clicking and dragging on the map,
+ * normally combined with an {@link ol.interaction.condition} that limits
+ * it to when the alt and shift keys are held down.
  * @constructor
  * @extends {ol.interaction.Drag}
  * @param {ol.interaction.DragRotateOptions=} opt_options Options.

src/ol/interaction/dragzoom.exports

@@ -0,0 +1 @@
+@exportClass ol.interaction.DragZoom ol.interaction.DragZoomOptions

src/ol/interaction/dragzoominteraction.js

@@ -29,6 +29,9 @@ ol.SHIFT_DRAG_ZOOM_HYSTERESIS_PIXELS_SQUARED =
 
 
 /**
+ * Allows the user to zoom the map by clicking and dragging on the map,
+ * normally combined with an {@link ol.interaction.condition} that limits
+ * it to when the shift key is held down.
  * @constructor
  * @extends {ol.interaction.Drag}
  * @param {ol.interaction.DragZoomOptions=} opt_options Options.

src/ol/interaction/interaction.jsdoc

@@ -0,0 +1,3 @@
+/**
+ * @namespace ol.interaction
+ */

src/ol/interaction/interactiondefaults.js

@@ -15,8 +15,17 @@ goog.require('ol.interaction.TouchZoom');
 
 
 /**
+ * This method is a convenience method to create a set of interactions
+ * to be used with an {@link ol.Map}.  Specific interactions can be excluded by
+ * setting the appropriate option to false in the constructor options,
+ * but the order of the interactions is fixed.  If you want to specify a
+ * different order for interactions, you will need to create your own
+ * {@link ol.interaction} instances and insert them into an
+ * {@link ol.Collection} in the order you want before creating your ol.Map
+ * instance.
  * @param {ol.interaction.DefaultsOptions=} opt_options Defaults options.
- * @return {ol.Collection} Interactions.
+ * @return {ol.Collection} A collection of interactions to be used with
+ * the ol.Map constructor's interactions option.
  */
 ol.interaction.defaults = function(opt_options) {
 

src/ol/interaction/keyboardpan.exports

@@ -0,0 +1 @@
+@exportClass ol.interaction.KeyboardPan ol.interaction.KeyboardPanOptions

src/ol/interaction/keyboardpaninteraction.js

@@ -21,6 +21,7 @@ ol.interaction.KEYBOARD_PAN_DURATION = 100;
 
 
 /**
+ * Allows the user to pan the map using keyboard arrows.
  * @constructor
  * @extends {ol.interaction.Interaction}
  * @param {ol.interaction.KeyboardPanOptions=} opt_options Options.

src/ol/interaction/keyboardzoom.exports

@@ -0,0 +1 @@
+@exportClass ol.interaction.KeyboardZoom ol.interaction.KeyboardZoomOptions

src/ol/interaction/keyboardzoominteraction.js

@@ -17,6 +17,7 @@ ol.interaction.KEYBOARD_ZOOM_DURATION = 100;
 
 
 /**
+ * Allows the user to zoom the map using keyboard + and -.
  * @constructor
  * @param {ol.interaction.KeyboardZoomOptions=} opt_options Options.
  * @extends {ol.interaction.Interaction}

src/ol/interaction/mousewheelzoom.exports

@@ -0,0 +1 @@
+@exportSymbol ol.interaction.MouseWheelZoom

src/ol/interaction/mousewheelzoominteraction.js

@@ -30,6 +30,7 @@ ol.interaction.MOUSEWHEELZOOM_TIMEOUT_DURATION = 80;
 
 
 /**
+ * Allows the user to zoom the map by scrolling the mouse wheel.
  * @constructor
  * @extends {ol.interaction.Interaction}
  */

src/ol/interaction/selectinteraction.js

@@ -13,6 +13,7 @@ goog.require('ol.source.Vector');
 
 
 /**
+ * Allows the user to select features on the map.
  * @constructor
  * @extends {ol.interaction.Interaction}
  * @param {ol.interaction.SelectOptions=} opt_options Options.

src/ol/interaction/touchinteraction.js

@@ -13,6 +13,7 @@ goog.require('ol.interaction.Interaction');
 
 
 /**
+ * Base class for touch interactions.
  * @constructor
  * @extends {ol.interaction.Interaction}
  */

src/ol/interaction/touchpan.exports

@@ -0,0 +1 @@
+@exportClass ol.interaction.TouchPan ol.interaction.TouchPanOptions

src/ol/interaction/touchpaninteraction.js

@@ -11,6 +11,8 @@ goog.require('ol.interaction.Touch');
 
 
 /**
+ * Allows the user to pan the map by touching and dragging
+ * on a touch screen.
  * @constructor
  * @extends {ol.interaction.Touch}
  * @param {ol.interaction.TouchPanOptions=} opt_options Options.

src/ol/interaction/touchrotate.exports

@@ -0,0 +1 @@
+@exportClass ol.interaction.TouchRotate ol.interaction.TouchRotateOptions

src/ol/interaction/touchrotateinteraction.js

@@ -17,6 +17,8 @@ ol.interaction.TOUCHROTATE_ANIMATION_DURATION = 250;
 
 
 /**
+ * Allows the user to rotate the map by twisting with two fingers
+ * on a touch screen.
  * @constructor
  * @extends {ol.interaction.Touch}
  * @param {ol.interaction.TouchRotateOptions=} opt_options Options.

src/ol/interaction/touchzoom.exports

@@ -0,0 +1 @@
+@exportSymbol ol.interaction.TouchZoom

src/ol/interaction/touchzoominteraction.js

@@ -17,6 +17,8 @@ ol.interaction.TOUCHZOOM_ANIMATION_DURATION = 400;
 
 
 /**
+ * Allows the user to zoom the map by pinching with two fingers
+ * on a touch screen.
  * @constructor
  * @extends {ol.interaction.Touch}
  */

src/ol/kinetic.exports

@@ -0,0 +1 @@
+@exportSymbol ol.Kinetic

src/ol/map.js

@@ -511,7 +511,11 @@ ol.Map.prototype.getFeatures = function(options) {
 
 
 /**
- * Gets the collection on interactions associated with this map.
+ * Gets the collection of
+ * {@link ol.interaction|ol.interaction.Interaction} instances
+ * associated with this map.  Modifying this collection
+ * changes the interactions associated with the map.
+ *
  * Interactions are used for e.g. pan, zoom and rotate.
  * @return {ol.Collection} Interactions.
  */