# Yahoo! UI Library

### dd 3.0.0b1

Yahoo! UI Library > dd > DD.Drag
Search:
Filters Show Private Show Protected Show Deprecated

## Class DD.Drag - extends Base

Known Subclasses:
  Plugin.Drag

This class provides the ability to drag a Node.

### Constructor

DD.Drag `( )`

### Properties

#### _clickTimeout - `private {Boolean}`

Holder for the setTimeout call

#### _dragThreshMet - `private {Boolean}`

Private flag to see if the drag threshhold was met

#### _endTime - `private Date`

The getTime of the mouseup event. Not used, just here in case someone wants/needs to use it.

#### _ev_md - `private {Event.Facade}`

A private reference to the mousedown DOM event

#### _fromTimeout - `private {Boolean}`

Flag to determine if the drag operation came from a timeout

#### _groups - `private {Array}`

Storage Array for the groups this drag belongs to.

#### _handles - `private {Object}`

A private hash of the valid drag handles

#### _ieSelectBack - `private object`

We will hold a copy of the current "onselectstart" method on this property, and reset it after we are done using it.

#### _invalids - `private {Object}`

A private hash of the invalid selector strings

#### _invalidsDefault - `private {Object}`

A private hash of the default invalid selector strings: {'textarea': true, 'input': true, 'a': true, 'button': true}

#### _startTime - `private Date`

The getTime of the mousedown event. Not used, just here in case someone wants/needs to use it.

#### actXY - `{Array}`

The xy that the node will be set to. Changing this will alter the position as it's dragged.

#### deltaXY - `{Array}`

The offset of the mouse position to the element's position

#### lastXY - `{Array}`

The position of the element as it's moving (for offset calculations)

#### mouseXY - `{Array}`

The XY coords of the mousemove

#### nodeXY - `{Array}`

The initial element position

#### realXY - `{Array}`

The real xy position of the node.

#### region - `Object`

A region object associated with this drag, used for checking regions while dragging.

#### startXY - `{Array}`

The initial mouse position

#### target - `{Object}`

This will be a reference to the Drop instance associated with this drag if the target: true config attribute is set..

#### Properties inherited from Attribute:

``

#### Properties inherited from Base:

`name`

### Methods

#### _align

`private void _align ( xy )`
Calculates the offsets and set's the XY that the element will move to.

Parameters:
  `xy <Array>` The xy coords to align with.

Returns: `void`

#### _alignNode

`private void _alignNode ( eXY )`
This method performs the alignment before the element move.

Parameters:
  `eXY <Array>` The XY to move the element to, usually comes from the mousemove DOM event.

Returns: `void`

#### _createEvents

`private void _createEvents ( )`
This method creates all the events for this Event Target and publishes them so we get Event Bubbling.

Returns: `void`

#### _defAlignFn

`private void _defAlignFn ( e )`
Calculates the offsets and set's the XY that the element will move to.

Parameters:
  `e <Event.Facade>` The drag:align event.

Returns: `void`

#### _defDragFn

`private void _defDragFn ( ev )`
Default function for drag:drag. Fired from _moveNode.

Parameters:
  `ev <Event.Facade>` The drag:drag event

Returns: `void`

#### _defMouseDownFn

`private void _defMouseDownFn ( )`
Handler for the mousedown DOM event

Returns: `void`

#### _fixDragStart

`private void _fixDragStart ( )`
The function we use as the ondragstart handler when we start a drag in Internet Explorer. This keeps IE from blowing up on images as drag handles.

Returns: `void`

#### _fixIEMouseDown

`private void _fixIEMouseDown ( )`
This method copies the onselectstart listner on the document to the _ieSelectFix property

Returns: `void`

#### _fixIEMouseUp

`private void _fixIEMouseUp ( )`
This method copies the _ieSelectFix property back to the onselectstart listner on the document.

Returns: `void`

#### _handleMouseDownEvent

`private void _handleMouseDownEvent ( )`
Handler for the mousedown DOM event

Returns: `void`

#### _handleMouseUp

`private void _handleMouseUp ( )`
Handler for the mouseup DOM event

Returns: `void`

#### _handleTarget

`private Boolean/Object _handleTarget ( )`
Attribute handler for the target config attribute.

Returns: `Boolean/Object`

#### _ieSelectFix

`private void _ieSelectFix ( )`
The function we use as the onselectstart handler when we start a drag in Internet Explorer

Returns: `void`

#### _move

`private void _move ( ev )`
Fired from DragDropMgr (DDM) on mousemove.

Parameters:
  `ev <Event.Facade>` The mousemove DOM event

Returns: `void`

#### _moveNode

`private void _moveNode ( )`
This method performs the actual element move.

Returns: `void`

#### _prep

`private void _prep ( )`
Attach event listners and add classname

Returns: `void`

#### _prevEndFn

`private void _prevEndFn ( )`
Handler for preventing the drag:end event. It will reset the node back to it's start position

Returns: `void`

#### _setStartPosition

`private void _setStartPosition ( xy )`
Sets the current position of the Element and calculates the offset

Parameters:
  `xy <Array>` The XY coords to set the position to.

Returns: `void`

#### _timeoutCheck

`private void _timeoutCheck ( )`
The method passed to setTimeout to determine if the clickTimeThreshold was met.

Returns: `void`

#### _unprep

`private void _unprep ( )`
Detach event listeners and remove classname

Returns: `void`

#### addHandle

`Self addHandle ( str )`
Add a handle to a drag element. Drag only initiates when a mousedown happens on this element.

Parameters:
  `str <String>` The selector to test for a valid handle. Must be a child of the element.

Returns: `Self`

Chainable: This method is chainable.

#### addInvalid

`Self addInvalid ( str )`
Add a selector string to test the handle against. If the test passes the drag operation will not continue.

Parameters:
  `str <String>` The selector to test against to determine if this is an invalid drag handle.

Returns: `Self`

Chainable: This method is chainable.

#### addToGroup

`Self addToGroup ( g )`
Add this Drag instance to a group, this should be used for on-the-fly group additions.

Parameters:
  `g <String>` The group to add this Drag Instance to.

Returns: `Self`

Chainable: This method is chainable.

#### destructor

`private void destructor ( )`
Lifecycle destructor, unreg the drag from the DDM and remove listeners

Returns: `void`

#### end

`Self end ( )`
Ends the drag operation

Returns: `Self`

Chainable: This method is chainable.

#### initializer

`private void initializer ( )`
Internal init handler

Returns: `void`

#### removeFromGroup

`Self removeFromGroup ( g )`
Remove this Drag instance from a group, this should be used for on-the-fly group removals.

Parameters:
  `g <String>` The group to remove this Drag Instance from.

Returns: `Self`

Chainable: This method is chainable.

#### removeHandle

`Self removeHandle ( str )`
Remove a Selector added by addHandle

Parameters:
  `str <String>` The selector for the handle to be removed.

Returns: `Self`

Chainable: This method is chainable.

#### removeInvalid

`Self removeInvalid ( str )`
Remove an invalid handle added by addInvalid

Parameters:
  `str <String>` The invalid handle to remove from the internal list.

Returns: `Self`

Chainable: This method is chainable.

#### start

`Self start ( )`
Starts the drag operation

Returns: `Self`

Chainable: This method is chainable.

#### stopDrag

`Self stopDrag ( )`
Method will forcefully stop a drag operation. For example calling this from inside an ESC keypress handler will stop this drag.

Returns: `Self`

Chainable: This method is chainable.

#### validClick

`Boolean validClick ( )`
Method first checks to see if we have handles, if so it validates the click against the handle. Then if it finds a valid handle, it checks it against the invalid handles list. Returns true if a good handle was used, false otherwise.

Returns: `Boolean`

#### Methods inherited from EventTarget:

`_getType, _parseType, addTarget, after, before, bubble, detach, detachAll, fire, getEvent, on, publish, removeTarget, subscribe, unsubscribe, unsubscribeAll`

#### Methods inherited from Attribute:

`_addAttrs, _addLazyAttr, _defAttrChangeFn, _fireAttrChange, _getAttrInitVal, _isLazyAttr, _set, _setAttr, _setAttrVal, _splitAttrVals, addAttr, addAttrs, attrAdded, get, getAttrs, modifyAttr, removeAttr, reset, set, setAttrs`

#### Methods inherited from Plugin.Host:

`_destroyPlugins, _initPlugins, _plug, _unplug, hasPlugin, plug, unplug`

#### Methods inherited from Base:

`_aggregateAttrs, _defDestroyFn, _defInitFn, _destroyHierarchy, _filterAttrCfs, _getAttrCfgs, _getClasses, _initHierarchy, _initHierarchyData, destroy, init, toString`

### Events

#### activeHandleChange

`activeHandleChange ( event )`
Fires when the value for the configuration attribute 'activeHandle' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### bubblesChange

`bubblesChange ( event )`
Fires when the value for the configuration attribute 'bubbles' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### clickPixelThreshChange

`clickPixelThreshChange ( event )`
Fires when the value for the configuration attribute 'clickPixelThresh' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### clickTimeThreshChange

`clickTimeThreshChange ( event )`
Fires when the value for the configuration attribute 'clickTimeThresh' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### dataChange

`dataChange ( event )`
Fires when the value for the configuration attribute 'data' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### drag:addHandle

`drag:addHandle ( )`
Fires after a handle is added.
Bubbles: This event bubbles to DDM.

#### drag:addInvalid

`drag:addInvalid ( )`
Fires after an invalid selector is added.
Bubbles: This event bubbles to DDM.

#### drag:afterMouseDown

`drag:afterMouseDown ( ev )`
Fires after the mousedown event has been cleared.

Parameters:
  `ev <Event.Facade>` The mousedown event.

Bubbles: This event bubbles to DDM.

#### drag:align

`drag:align ( )`
Fires when this node is aligned.
Bubbles: This event bubbles to DDM.
Preventable: This event is preventable by method e.preventDefault(). The default function executed by this event is _defAlignFn.

#### drag:drag

`drag:drag ( )`
Fires every mousemove during a drag operation.
Bubbles: This event bubbles to DDM.

#### drag:drophit

`drag:drophit ( )`
Fires when this node is dropped on a valid Drop Target. (Fired from dd-ddm-drop)
Bubbles: This event bubbles to DDM.

#### drag:dropmiss

`drag:dropmiss ( )`
Fires when this node is dropped on an invalid Drop Target. (Fired from dd-ddm-drop)
Bubbles: This event bubbles to DDM.

#### drag:end

`drag:end ( )`
Fires at the end of a drag operation.
Bubbles: This event bubbles to DDM.

#### drag:enter

`drag:enter ( )`
Fires when this node enters a Drop Target. (Fired from dd-drop)
Bubbles: This event bubbles to DDM.

#### drag:exit

`drag:exit ( )`
Fires when this node exits a Drop Target. (Fired from dd-drop)
Bubbles: This event bubbles to DDM.

#### drag:mouseDown

`drag:mouseDown ( ev )`
Handles the mousedown DOM event, checks to see if you have a valid handle then starts the drag timers.

Parameters:
  `ev <Event.Facade>` The mousedown event.

Bubbles: This event bubbles to DDM.
Preventable: This event is preventable by method e.preventDefault(). The default function executed by this event is _defMouseDownFn.

#### drag:over

`drag:over ( )`
Fires when this node is over a Drop Target. (Fired from dd-drop)
Bubbles: This event bubbles to DDM.

#### drag:removeHandle

`drag:removeHandle ( )`
Fires after a handle is removed.
Bubbles: This event bubbles to DDM.

#### drag:removeInvalid

`drag:removeInvalid ( )`
Fires after an invalid selector is removed.
Bubbles: This event bubbles to DDM.

#### drag:start

`drag:start ( )`
Fires at the start of a drag operation.
Bubbles: This event bubbles to DDM.

#### draggingChange

`draggingChange ( event )`
Fires when the value for the configuration attribute 'dragging' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### dragModeChange

`dragModeChange ( event )`
Fires when the value for the configuration attribute 'dragMode' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### dragNodeChange

`dragNodeChange ( event )`
Fires when the value for the configuration attribute 'dragNode' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### groupsChange

`groupsChange ( event )`
Fires when the value for the configuration attribute 'groups' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### handlesChange

`handlesChange ( event )`
Fires when the value for the configuration attribute 'handles' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### lockChange

`lockChange ( event )`
Fires when the value for the configuration attribute 'lock' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### moveChange

`moveChange ( event )`
Fires when the value for the configuration attribute 'move' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### nodeChange

`nodeChange ( event )`
Fires when the value for the configuration attribute 'node' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### offsetNodeChange

`offsetNodeChange ( event )`
Fires when the value for the configuration attribute 'offsetNode' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### primaryButtonOnlyChange

`primaryButtonOnlyChange ( event )`
Fires when the value for the configuration attribute 'primaryButtonOnly' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### targetChange

`targetChange ( event )`
Fires when the value for the configuration attribute 'target' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### useShimChange

`useShimChange ( event )`
Fires when the value for the configuration attribute 'useShim' is changed. You can listen for the event using the on method if you wish to be notified before the attribute's value has changed, or using the after method if you wish to be notified after the attribute's value has changed.

Parameters:
  `event <Event.Facade>` An Event Facade object with the following attribute specific properties added:
  prevVal
    The value of the attribute, prior to it being set
  newVal
    The value the attribute is to be set to
  attrName
    The name of the attribute being set
  subAttrName
    If setting a property within the attribute's value, the name of the sub-attribute property being set

#### Events inherited from Base:

`destroy, destroyedChange, init, initializedChange,`

### Configuration Attributes

#### activeHandle `- Node`

This config option is set by Drag to inform you of which handle fired the drag event (in the case that there are several handles): default false.

#### bubbles `- Object`

Controls the default bubble parent for this Drag instance. Default: Y.DD.DDM. Set to false to disable bubbling.

#### clickPixelThresh `- Number`

The number of pixels to move to start a drag operation, default is 3.

#### clickTimeThresh `- Number`

The number of milliseconds a mousedown has to pass to start a drag operation, default is 1000.

#### data `- Mixed`

A payload holder to store arbitrary data about this drag object, can be used to store any value.

#### dragging `- Boolean`

This attribute is not meant to be used by the implementor, it is meant to be used as an Event tracker so you can listen for it to change.

#### dragMode `- String`

This attribute only works if the dd-drop module is active. It will set the dragMode (point, intersect, strict) of this Drag instance.

#### dragNode `- Node`

Y.Node instanace to use as the draggable element, defaults to node

#### groups `- Array`

Array of groups to add this drag into.

#### handles `- Array`

Array of valid handles to add. Adding something here will set all handles, even if previously added with addHandle

#### lock `- Boolean`

Set to lock this drag element so that it can't be dragged: default false.

#### move `- Boolean`

If this is false, the drag element will not move with the cursor: default true. Can be used to "resize" the element.

#### node `- Node`

Y.Node instanace to use as the element to initiate a drag operation

#### offsetNode `- Boolean`

Offset the drag element by the difference in cursor position: default true

#### primaryButtonOnly `- Boolean`

By default a drag operation will only begin if the mousedown occurred with the primary mouse button. Setting this to false will allow for all mousedown events to trigger a drag.

#### target `- Boolean`

This attribute only works if the dd-drop module has been loaded. It will make this node a drop target as well as draggable.

#### useShim `- Boolean`

Use the protective shim on all drag operations: default true. Only works with dd-ddm, not dd-ddm-base.

#### Configuration attributes inherited from Base:

`destroyed, initialized,`

Copyright © 2009 Yahoo! Inc. All rights reserved.