Drag-listener NPM

drag-listener

Listen to horizontal drag events on a dom element. drag-listener will not actually move the element around for you, it will just notify you of the user's attempt to drag the element.

install

npm install drag-listener

environmental requirements

drag-listener has some fairly strict environmental requirements in that it must be used in conjunction with browserify (hence the npm distribution). It also expects $ in the global scope to reference jQuery at runtime.

usage

listen(element, [handle,] offsetMin, offsetMax, [opts])

Start listening for drag events on an element. Returns an EventEmitter that emits the events in the events section below.

element the element that will have its position measured to return a value for the drag event. For more details, on how this is measured, see the drag event below.
handle (optional) - the handle of the draggable element, this is the thing that user clicks on to start dragging. Defaults to element.
offsetMin the minimum bound of the draggable element, relative to its parent. Can also be passed as a function that returns a number (the function is called at the start of each drag to determine the minimum bound for that drag)
offsetMax the maximum bound of the draggable element, relative to its parent. Can also be passed as a function that returns a number (the function is called at the start of each drag to determine the maximum bound for that drag)
opts (optional) a set of options, specified below

options

includeWidth (default = false) if set to true, include the width of the parent when calculating its current position.
stopPropagation (default = true) if set to true, don't propagate the initial mousedown event that initiates a drag
shouldDrag (default = function(){return true}). a function that is called when a drag is initiated, determining if the drag should be ignored. Shall return true or false.
movementThreshold (default = 1). The minimum distance to move before a drag is triggered.
timeThreshold (default = 100). The minimum time before a drag is triggered (in ms).
requireBothThresholds (default = false). If set to true, both time and position thresholds must be satisfied before a drag is triggered.

events

dragStart - emitted when the user initiates a drag (when the handle receives a mousedown and a mousemove event). Passes one argument, a number between 0.0 and 1.0 that indicates where the element is located at the start of the drag.
drag - emitted when the user drags the element (fired for every mousemove event received after the handle has received a mousedown event, but before it has received a mouseup event). Passes one argument, a number between 0.0 and 1.0 that indicates where the user has dragged the element between the offsetMin and offsetMax bounds.
dragFinish - emitted when the user finishes a drag (when the handle receives a mouseup event). Passes one argument, a number between 0.0 and 1.0 that indicates where the element is located at the end of the drag.
click - emitted when a mousedown and a mouseup event is received in the space of 500ms, and no mousemove events are received.