$.event.special.drag

This is a jquery special event implementation of a drag event model. It is intended for use by developers who don't need one bloated script full of idiot-proof logic and a million different options. For people who plan a drag interaction model and decide how to set up pages and position elements, and don't need a script to figure that out...

Downloads - jQuery 1.2.x or 1.3.x required.

• jquery.event.drag-1.5.zip
• jquery.event.drag-1.5.js (Uncompressed)
• jquery.event.drag-1.5.min.js (Minified)
• Drag demos...

This plugin is designed to work seamlessly with $.special.event.drop, though it is not required.

To begin, let us look at the anatomy of a drag event model using standard DOM events...

1. "mousedown" - The user depresses a mouse button within the draggable element
2. "mousemove" - The user holds the mouse button and moves the mouse
3. "mouseup" - The user releases the mousebutton

Makes sense? Now consider the interesting moments of a drag interaction...

1. "dragstart" - Dragging begins, after the mouse has moved past some tolerance threshold
2. "drag" - The mouse is moving, element dragging
3. "dragend" - The dragging stops

This plugin simplifies all of this, by taking care of the DOM events when you bind a "drag" event handler, and triggering any other handlers at the appropriate time.

This plugin does NOT move elements! You have to do that yourself, but I think that is best in many cases (containment, snapping to a grid, axis restriction, and non-linear movement, to name a few). This plugin does update many helpful event properties for your use...

• event.dragTarget - The originating element of the drag event
• event.dragProxy - The proxy element or dragTarget
• event.cursorOffsetX - The horizontal difference between the click and element position
• event.cursorOffsetY - The vertical difference between the click and element position
• event.offsetX - The adjusted (by cursorOffset) dragged horizontal element position
• event.offsetY - The adjusted (by cursorOffset) dragged vertical element position

// bind a drag event, update position $( elems ).bind( 'drag', function( event ){ $( this ).css({ top:event.offsetY, left:event.offsetX }); });

Demo - Try dragging the box around...

To achieve more complex behaviors, consider handling these relatively simple events.

• dragstart - return false to prevent drag, return an element, jquery collection, or selector string to set the proxy element which will be accessible from event.dragProxy, and will be considered for drop target tolerance
• drag - return false to prevent further dragging and immediately trigger "dragend"
• dragend - a drag callback

// bind a dragstart event, return the proxy element $( elems ).bind( 'dragstart', function( event ){ return $( this ).clone().appendTo( this.parentNode ); }); // bind a drag event, update proxy position $( elems ).bind( 'drag', function( event ){ $( event.dragProxy ).css({ top:event.offsetY, left:event.offsetX }); }); // bind a dragend event, remove proxy $( elems ).bind( 'dragend', function( event ){ $( event.dragProxy ).fadeOut(); });

Demo - Try dragging the box around, observe the use of a proxy...

There is one parameter for customizing drag interaction, jQuery.event.special.drag.distance (default: 0), and it is used to define the length in pixels that must be moved before triggering "dragstart." This property is captured at the time the drag event is bound, and in jQuery 1.3, you will be able pass options using the already existing "bind" data argument.

// bind with data parameters (jQuery 1.3) $( elems ).bind( "drag", { distance:10 }, function(){ ... });

Lastly, there is an overloaded jquery method called "drag" which takes zero to three arguments.

// 0 args, trigger "drag" handler $( elems ).drag(); // 1 arg, binds "drag" handler $( elems ).drag( dragFn ); // 2 args, binds "dragstart" and "drag" handlers $( elems ).drag( dragstartFn, dragFn ); // 3 args, binds "dragstart" and "drag" and "dragend" handlers $( elems ).drag( dragstartFn, dragFn, dragendFn );

Please direct any feedback to http://groups.google.com/group/threedubmedia