From 728ba09060eb081d2f289b2ea7925993080afdaf Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Mon, 9 Jul 2007 20:02:52 +0000 Subject: [PATCH] more doc comments for the drag handler git-svn-id: http://svn.openlayers.org/trunk/openlayers@3659 dc9f47b5-9b13-0410-9fdd-eb0c1a62fdaf --- lib/OpenLayers/Handler/Drag.js | 63 ++++++++++++++++++++++++---------- 1 file changed, 45 insertions(+), 18 deletions(-) diff --git a/lib/OpenLayers/Handler/Drag.js b/lib/OpenLayers/Handler/Drag.js index d58e0c3ba8..714391ef86 100644 --- a/lib/OpenLayers/Handler/Drag.js +++ b/lib/OpenLayers/Handler/Drag.js @@ -4,9 +4,24 @@ /** * @requires OpenLayers/Handler.js - * @requires OpenLayers/Events.js * * Class: OpenLayers.Handler.Drag + * The drag handler is used to deal with sequences of browser events related + * to dragging. The handler is used by controls that want to know when + * a drag sequence begins, when a drag is happening, and when it has + * finished. + * + * Controls that use the drag handler typically construct it with callbacks + * for 'down', 'move', and 'done'. Callbacks for these keys are called + * when the drag begins, with each move, and when the drag is done. In + * addition, controls can have callbacks keyed to 'up' and 'out' if they + * care to differentiate between the types of events that correspond with + * the end of a drag sequence. + * + * Create a new drag handler with the constructor. + * + * Inherits from: + * - */ OpenLayers.Handler.Drag = OpenLayers.Class.create(); OpenLayers.Handler.Drag.prototype = @@ -15,7 +30,7 @@ OpenLayers.Handler.Drag.prototype = /** * Property: started * {Boolean} When a mousedown event is received, we want to record it, but - * not set 'dragging' until the mouse moves after starting. + * not set 'dragging' until the mouse moves after starting. */ started: false, @@ -42,20 +57,27 @@ OpenLayers.Handler.Drag.prototype = * Returns OpenLayers.Handler.Drag * * Parameters: - * control - {} + * control - {} The control that is making use of + * this handler. If a handler is being used without a control, the + * handlers setMap method must be overridden to deal properly with + * the map. * callbacks - {Object} An object containing a single function to be - * called when the drag operation is finished. - * The callback should expect to recieve a single - * argument, the pixel location of the event. - * Callbacks for 'move' and 'done' are supported. - * You can also speficy callbacks for 'down', 'up', - * and 'out' to respond to those events. + * called when the drag operation is finished. The callback should + * expect to recieve a single argument, the pixel location of the event. + * Callbacks for 'move' and 'done' are supported. You can also speficy + * callbacks for 'down', 'up', and 'out' to respond to those events. * options - {Object} */ initialize: function(control, callbacks, options) { OpenLayers.Handler.prototype.initialize.apply(this, arguments); }, + /** + * The methods below are part of the magic of event handling. Because + * they are named like browser events, they are registered as listeners + * for the events they represent. + */ + /** * Method: mousedown * Handle mousedown events @@ -63,7 +85,8 @@ OpenLayers.Handler.Drag.prototype = * Parameters: * evt - {Event} * - * Return: {Boolean} Should the event propagate + * Return: + * {Boolean} Let the event propagate. */ mousedown: function (evt) { if (this.checkModifiers(evt) && OpenLayers.Event.isLeftClick(evt)) { @@ -86,7 +109,8 @@ OpenLayers.Handler.Drag.prototype = * Parameters: * evt - {Event} * - * Return: {Boolean} Should the event propagate + * Return: + * {Boolean} Let the event propagate. */ mousemove: function (evt) { if (this.started) { @@ -107,7 +131,8 @@ OpenLayers.Handler.Drag.prototype = * Parameters: * evt - {Event} * - * Return: {Boolean} Should the event propagate + * Return: + * {Boolean} Let the event propagate. */ mouseup: function (evt) { if (this.started) { @@ -128,7 +153,8 @@ OpenLayers.Handler.Drag.prototype = * Parameters: * evt - {Event} * - * Return: {Boolean} Should the event propagate + * Return: + * {Boolean} Let the event propagate. */ mouseout: function (evt) { if (this.started && OpenLayers.Util.mouseLeft(evt, this.map.div)) { @@ -154,7 +180,8 @@ OpenLayers.Handler.Drag.prototype = * Parameters: * evt - {Event} * - * Return: {Boolean} Should the event propagate + * Return: + * {Boolean} Let the event propagate. */ click: function (evt) { // throw away the first left click event that happens after a mouse up @@ -170,8 +197,8 @@ OpenLayers.Handler.Drag.prototype = * Method: activate * Activate the handler. * - * Return: {Boolean} Was activation successful. - * Returns false if already active. + * Return: + * {Boolean} The handler was successfully activated. */ activate: function() { if(OpenLayers.Handler.prototype.activate.apply(this, arguments)) { @@ -186,8 +213,8 @@ OpenLayers.Handler.Drag.prototype = * Method: deactivate * Deactivate the handler. * - * Return: {Boolean} Was deactivation successful. - * Returns false if already active. + * Return: + * {Boolean} The handler was successfully deactivated. */ deactivate: function() { if(OpenLayers.Handler.prototype.deactivate.apply(this, arguments)) {