UsefulJS.DnD

The DnD extension builds on UsefulJS.Event to provide a simple framework for dragging elements around the page using the mouse or touchscreen.

Static methods

register

Registers an element for drag and drop

Syntax

UsefulJS.DnD.register(elem[, boundingElem[, startCallback[, updateCallback[, ctx]]]])

Parameters

elem String|Element
The element (or ID of the element) for which you want drag behaviour.
boundingElem String|Element (optional)
The element (or ID of the element) that forms the bounding rectangle of the area in which elem is allowed to move; defaults to document.body
startCallback Function (optional)
Callback for when the drag operation begins; see the description below for details of the function parameters
updateCallback Function (optional)
Callback for when the dragged element is moved or the drag operation ends; see the description below for details of the function parameters
ctx Object (optional)
The calling context (i.e. "this") for the callbacks.

Throws TypeError: if elem is not an element or a string that resolves to an element.

Description

The start callback function takes has the following form:

startCallback(event, eventSource, registeredElement)

event will be a mousedown or touchstart event. eventSource may well not be the same element that was passed to register but registeredElement will be.

The callback should return the element that is to be dragged; this may not be the registered element. For example, in a chess game, the elements that are dragged around may be small images but the element registered for drag events is a much larger container element allowing pieces to be moved when using a touchscreen. The callback is also responsible for making the returned element suitable for dragging (for example, removing the element to be dragged from its current parent node, adding the element as a child node of the bounding element and positioning it absolutely). If you want to prevent the drag behaviour (for example, eventtSource is not an element that you want to allow to initiate drag operations) your callback function can return null.

You can distinguish touch events in your callback by the presence of a touches property in event. For example, when using a touch screen you may want to position the drag element differently so that it is not obscured by the user's finger.

If no startCallback function is supplied, the framework will use the registered element for dragging and will set style attributes on it (position: absolute; left, top: the clientX, clientY positions of the event).

The update callback function takes has the following form:

updateCallback(event, x, y, dragElement, complete)

If complete is true, event will be a mouseup or touchend event. Otherwise it will be a mousemove / touchmove event. dragElement is the element being dragged and x and y are the co-ordinates of its top left corners.

If an element is removed from the document tree when it has been registered for drag-and-drop (for example, one chess piece takes another), it should be deregistered first; this is both to free resources used and to allow drag-and-drop to work if you later register an element which re-uses the same element ID.

deregister

Deregisters an element previously registered for drag-and-drop.

Syntax

UsefulJS.DnD.deregister(elem)

Parameters

elem String|Element
The element (or ID of the element) for which you no longer want drag behaviour.

Throws TypeError: if elem is not an element or a string that resolves to an element.

Description

Removes event handlers that were added to elem by the UsefulJS.DnD.register call.

If you want to register an element for drag-and-drop using different parameters (for example, a different bounding element), you must deregister it first.

elementOffset

Gets the x- and y-offsets of one element from another

Syntax

UsefulJS.DnD.elementOffset(elem[, eRel])

Parameters

elem String|Element
The (ID of the) element that you're interested in
eRel String|Element (optional)
The (ID of the) element to be used as a reference; defaults to document.body.

Returns Array: the x and y co-ordinates of elem relative to eRel.

Throws TypeError: if elem is not an element or a string that resolves to an element.