API: dragdrop YAHOO.util.DragDrop (YUI Library)

# Yahoo! UI Library

### Drag and Drop 2.8.1

Yahoo! UI Library > dragdrop > YAHOO.util.DragDrop
Search:
Filters Show Private Show Protected Show Deprecated

## Class YAHOO.util.DragDrop

Known Subclasses:
  YAHOO.widget.Slider YAHOO.util.DDTarget YAHOO.util.DD

Defines the interface and base operation of items that that can be dragged or can be drop targets. It was designed to be extended, overriding the event handlers for startDrag, onDrag, onDragOver, onDragOut. Up to three html elements can be associated with a DragDrop instance:

- linked element: the element that is passed into the constructor. This is the element which defines the boundaries for interaction with other DragDrop objects.
- handle element(s): The drag operation only occurs if the element that was clicked matches a handle element. By default this is the linked element, but there are times that you will want only a portion of the linked element to initiate the drag operation, and the setHandleElId() method provides a way to define this.
- drag element: this represents an the element that would be moved along with the cursor during a drag operation. By default, this is the linked element itself as in {@link YAHOO.util.DD}. setDragElId() lets you define a separate element that would be moved, as in {@link YAHOO.util.DDProxy}

This class should not be instantiated until the onload event to ensure that the associated elements are available. The following would define a DragDrop obj that would interact with any other DragDrop obj in the "group1" group:

    dd = new YAHOO.util.DragDrop("div1", "group1");

Since none of the event handlers have been implemented, nothing would actually happen if you were to run the code above. Normally you would override this class or one of the default implementations, but you can also override the methods you want on an instance of the class...

    dd.onDragDrop = function(e, id) {
      alert("dd was dropped on " + id);
    }

### Constructor

YAHOO.util.DragDrop `( id , sGroup , config )`

Parameters:
  `id <String>` of the element that is linked to this instance
  `sGroup <String>` the group of related DragDrop objects
  `config <object>` an object containing configurable attributes Valid properties for DragDrop: padding, isTarget, maintainOffset, primaryButtonOnly,

### Properties

#### __ygDragDrop - `private object`

Internal typeof flag

#### _domRef - `private object`

Cached reference to the linked element

#### available - `boolean`

The availabe property is false until the linked dom element is accessible.

#### config - `object`

Configuration attributes passed into the constructor

#### constrainX - `private boolean`

Set to true when horizontal contraints are applied

#### constrainY - `private boolean`

Set to true when vertical contraints are applied

#### cursorIsOver - `boolean`

Property that is assigned to a drag and drop object when testing to see if it is being targeted by another dd object. This property can be used in intersect mode to help determine the focus of the mouse interaction. DDM.getBestMatch uses this property first to determine the closest match in INTERSECT mode when multiple targets are part of the same interaction.

#### deltaX - `private int`

The difference between the click position and the source element's location

#### deltaY - `private int`

The difference between the click position and the source element's location

#### dragElId - `private String`

The id of the element that will be dragged. By default this is same as the linked element , but could be changed to another element. Ex: YAHOO.util.DDProxy

#### dragOnly - `Boolean`

If this flag is true, do not fire drop events. The element is a drag only element (for movement not dropping)

#### events - `object`

An Object Literal containing the events that we will be using: mouseDown, b4MouseDown, mouseUp, b4StartDrag, startDrag, b4EndDrag, endDrag, mouseUp, drag, b4Drag, invalidDrop, b4DragOut, dragOut, dragEnter, b4DragOver, dragOver, b4DragDrop, dragDrop By setting any of these to false, then event will not be fired.

#### groups - `{string: string}`

The group defines a logical collection of DragDrop objects that are related. Instances only get events when interacting with other DragDrop object in the same group. This lets us define multiple groups using a single DragDrop subclass if we want.

#### handleElId - `private String`

the id of the element that initiates the drag operation. By default this is the linked element, but could be changed to be a child of this element. This lets us do things like only starting the drag when the header element within the linked html element is clicked.

#### hasOuterHandles - `boolean`

By default, drags can only be initiated if the mousedown occurs in the region the linked element is. This is done in part to work around a bug in some browsers that mis-report the mousedown if the previous mouseup happened outside of the window. This property is set to true if outer handles are defined.
Default Value: false

#### id - `String`

The id of the element associated with this object. This is what we refer to as the "linked element" because the size and position of this element is used to determine when the drag and drop objects have interacted.

#### invalidHandleClasses - `string[]`

An indexted array of css class names for elements that will be ignored if clicked.

#### invalidHandleIds - `{string: string}`

An associative array of ids for elements that will be ignored if clicked

#### invalidHandleTypes - `{string: string}`

An associative array of HTML tags that will be ignored if clicked.

#### isTarget - `boolean`

By default, all instances can be a drop target. This can be disabled by setting isTarget to false.

#### locked - `private boolean`

Individual drag/drop instances can be locked. This will prevent onmousedown start drag.

#### maintainOffset - `boolean`

Maintain offsets when we resetconstraints. Set to true when you want the position of the element relative to its parent to stay the same when the page changes

#### maxX - `private int`

The right constraint

#### maxY - `private int`

The down constraint

#### minX - `private int`

The left constraint

#### minY - `private int`

The up constraint

#### overlap - `YAHOO.util.Region`

Property that is assigned to a drag and drop object when testing to see if it is being targeted by another dd object. This is a region that represents the area the draggable element overlaps this target. DDM.getBestMatch uses this property to compare the size of the overlap to that of other targets in order to determine the closest match in INTERSECT mode when multiple targets are part of the same interaction.

#### padding - `int[]`

The padding configured for this drag and drop object for calculating the drop zone intersection with this object.

#### primaryButtonOnly - `boolean`

By default the drag and drop instance will only respond to the primary button click (left button for a right-handed mouse). Set to true to allow drag and drop to start with any mouse click that is propogated by the browser

#### startPageX - `private int`

The linked element's absolute X position at the time the drag was started

#### startPageY - `private int`

The linked element's absolute X position at the time the drag was started

#### useShim - `Boolean`

If this flag is true, a shim will be placed over the screen/viewable area to track mouse events. Should help with dragging elements over iframes and other controls.

#### xTicks - `int[]`

Array of pixel locations the element will snap to if we specified a horizontal graduation/interval. This array is generated automatically when you define a tick interval.

#### yTicks - `int[]`

Array of pixel locations the element will snap to if we specified a vertical graduation/interval. This array is generated automatically when you define a tick interval.

### Methods

#### addInvalidHandleClass

`void addInvalidHandleClass ( cssClass )`
Lets you specify a css class of elements that will not initiate a drag

Parameters:
  `cssClass <string>` the class of the elements you wish to ignore

#### addInvalidHandleId

`void addInvalidHandleId ( id )`
Lets you to specify an element id for a child of a drag handle that should not initiate a drag

Parameters:
  `id <string>` the element id of the element you wish to ignore

#### addInvalidHandleType

`void addInvalidHandleType ( tagName )`
Allows you to specify a tag name that should not start a drag operation when clicked. This is designed to facilitate embedding links within a drag handle that do something other than start the drag.

Parameters:
  `tagName <string>` the type of element to exclude

#### addToGroup

`void addToGroup ( sGroup )`
Add this instance to a group of related drag/drop objects. All instances belong to at least one group, and can belong to as many groups as needed.

Parameters:
  `sGroup <string>` the name of the group

#### applyConfig

`void applyConfig ( )`
Applies the configuration parameters that were passed into the constructor. This is supposed to happen at each level through the inheritance chain. So a DDProxy implentation will execute apply config on DDProxy, DD, and DragDrop in order to get all of the parameters that are available in each object.

#### b4Drag

`private void b4Drag ( )`
Code that executes immediately before the onDrag event

#### b4DragDrop

`private void b4DragDrop ( )`
Code that executes immediately before the onDragDrop event

#### b4DragOut

`private void b4DragOut ( )`
Code that executes immediately before the onDragOut event

#### b4DragOver

`private void b4DragOver ( )`
Code that executes immediately before the onDragOver event

#### b4EndDrag

`private void b4EndDrag ( )`
Code that executes immediately before the endDrag event

#### b4MouseDown

`private void b4MouseDown ( e )`
Code executed immediately before the onMouseDown event

Parameters:
  `e <Event>` the mousedown event

#### b4StartDrag

`private void b4StartDrag ( )`
Code that executes immediately before the startDrag event

#### clearConstraints

`void clearConstraints ( )`
Clears any constraints applied to this instance. Also clears ticks since they can't exist independent of a constraint at this time.

#### clearTicks

`void clearTicks ( )`
Clears any tick interval defined for this instance

#### clickValidator

`void clickValidator ( e )`
Method validates that the clicked element was indeed the handle or a valid child of the handle

Parameters:
  `e <Event>`

#### endDrag

`void endDrag ( e )`
Fired when we are done dragging the object

Parameters:
  `e <Event>` the mouseup event

#### getDragEl

`HTMLElement getDragEl ( )`
Returns a reference to the actual element to drag. By default this is the same as the html element, but it can be assigned to another element. An example of this can be found in YAHOO.util.DDProxy

Returns: `HTMLElement`
  the html element

#### getEl

`HTMLElement getEl ( )`
Returns a reference to the linked element

Returns: `HTMLElement`
  the html element

#### getTargetCoord

`private getTargetCoord ( iPageX , iPageY )`
Finds the location the element should be placed if we want to move it to where the mouse location less the click offset would place us.

Parameters:
  `iPageX <int>` the X coordinate of the click
  `iPageY <int>` the Y coordinate of the click

Returns: ``
  an object that contains the coordinates (Object.x and Object.y)

#### getTick

`private int getTick ( val , tickArray )`
Normally the drag element is moved pixel by pixel, but we can specify that it move a number of pixels at a time. This method resolves the location when we have it set up like this.

Parameters:
  `val <int>` where we want to place the object
  `tickArray <int[]>` sorted array of valid points

Returns: `int`
  the closest tick

#### handleMouseDown

`private void handleMouseDown ( e , oDD )`
Fired when this object is clicked

Parameters:
  `e <Event>`
  `oDD <YAHOO.util.DragDrop>` the clicked dd object (this dd obj)

#### handleOnAvailable

`private void handleOnAvailable ( )`
Executed when the linked element is available

#### init

`void init ( id , sGroup , config )`
Sets up the DragDrop object. Must be called in the constructor of any YAHOO.util.DragDrop subclass

Parameters:
  `id <object>` the id of the linked element
  `sGroup <String>` the group of related items
  `config <object>` configuration attributes

#### initTarget

`void initTarget ( id , sGroup , config )`
Initializes Targeting functionality only... the object does not get a mousedown handler.

Parameters:
  `id <object>` the id of the linked element
  `sGroup <String>` the group of related items
  `config <object>` configuration attributes

#### isLocked

`boolean isLocked ( )`
Returns true if this instance is locked, or the drag drop mgr is locked (meaning that all drag/drop is disabled on the page.)

Returns: `boolean`
  true if this obj or all drag/drop is locked, else false

#### isValidHandleChild

`boolean isValidHandleChild ( node )`
Checks the tag exclusion list to see if this click should be ignored

Parameters:
  `node <HTMLElement>` the HTMLElement to evaluate

Returns: `boolean`
  true if this is a valid tag type, false if not

#### lock

`void lock ( )`
Lock this instance

#### on

`void on ( )`
Shortcut for EventProvider.subscribe, see YAHOO.util.EventProvider.subscribe

#### onAvailable

`void onAvailable ( )`
Override the onAvailable method to do what is needed after the initial position was determined.

#### onDrag

`void onDrag ( e )`
Abstract method called during the onMouseMove event while dragging an object.

Parameters:
  `e <Event>` the mousemove event

#### onDragDrop

`void onDragDrop ( e , id )`
Abstract method called when this item is dropped on another DragDrop obj

Parameters:
  `e <Event>` the mouseup event
  `id <String|DragDrop[]>` In POINT mode, the element id this was dropped on. In INTERSECT mode, an array of dd items this was dropped on.

#### onDragEnter

`void onDragEnter ( e , id )`
Abstract method called when this element fist begins hovering over another DragDrop obj

Parameters:
  `e <Event>` the mousemove event
  `id <String|DragDrop[]>` In POINT mode, the element id this is hovering over. In INTERSECT mode, an array of one or more dragdrop items being hovered over.

#### onDragOut

`void onDragOut ( e , id )`
Abstract method called when we are no longer hovering over an element

Parameters:
  `e <Event>` the mousemove event
  `id <String|DragDrop[]>` In POINT mode, the element id this was hovering over. In INTERSECT mode, an array of dd items that the mouse is no longer over.

#### onDragOver

`void onDragOver ( e , id )`
Abstract method called when this element is hovering over another DragDrop obj

Parameters:
  `e <Event>` the mousemove event
  `id <String|DragDrop[]>` In POINT mode, the element id this is hovering over. In INTERSECT mode, an array of dd items being hovered over.

#### onInvalidDrop

`void onInvalidDrop ( e )`
Abstract method called when this item is dropped on an area with no drop target

Parameters:
  `e <Event>` the mouseup event

#### onMouseDown

`void onMouseDown ( e )`
Event handler that fires when a drag/drop obj gets a mousedown

Parameters:
  `e <Event>` the mousedown event

#### onMouseUp

`void onMouseUp ( e )`
Event handler that fires when a drag/drop obj gets a mouseup

Parameters:
  `e <Event>` the mouseup event

#### removeFromGroup

`void removeFromGroup ( sGroup )`
Remove's this instance from the supplied interaction group

Parameters:
  `sGroup <string>` The group to drop

#### removeInvalidHandleClass

`void removeInvalidHandleClass ( cssClass )`
Unsets an invalid css class

Parameters:
  `cssClass <string>` the class of the element(s) you wish to re-enable

#### removeInvalidHandleId

`void removeInvalidHandleId ( id )`
Unsets an invalid handle id

Parameters:
  `id <string>` the id of the element to re-enable

#### removeInvalidHandleType

`void removeInvalidHandleType ( tagName )`
Unsets an excluded tag name set by addInvalidHandleType

Parameters:
  `tagName <string>` the type of element to unexclude

#### resetConstraints

`void resetConstraints ( )`
resetConstraints must be called if you manually reposition a dd element.

#### setDragElId

`void setDragElId ( id )`
Allows you to specify that an element other than the linked element will be moved with the cursor during a drag

Parameters:
  `id <string>` the id of the element that will be used to initiate the drag

#### setHandleElId

`void setHandleElId ( id )`
Allows you to specify a child of the linked element that should be used to initiate the drag operation. An example of this would be if you have a content div with text and links. Clicking anywhere in the content area would normally start the drag operation. Use this method to specify that an element inside of the content div is the element that starts the drag operation.

Parameters:
  `id <string>` the id of the element that will be used to initiate the drag.

#### setInitialPosition

`private void setInitialPosition ( diffX , diffY )`
Stores the initial placement of the linked element.

Parameters:
  `diffX <int>` the X offset, default 0
  `diffY <int>` the Y offset, default 0

#### setOuterHandleElId

`void setOuterHandleElId ( id )`
Allows you to set an element outside of the linked element as a drag handle

Parameters:
  `id <object>` the id of the element that will be used to initiate the drag

#### setPadding

`void setPadding ( iTop , iRight , iBot , iLeft )`
Configures the padding for the target zone in px. Effectively expands (or reduces) the virtual object size for targeting calculations. Supports css-style shorthand; if only one parameter is passed, all sides will have that padding, and if only two are passed, the top and bottom will have the first param, the left and right the second.

Parameters:
  `iTop <int>` Top pad
  `iRight <int>` Right pad
  `iBot <int>` Bot pad
  `iLeft <int>` Left pad

#### setStartPosition

`private void setStartPosition ( pos )`
Sets the start position of the element. This is set when the obj is initialized, the reset when a drag is started.

Parameters:
  `pos <object>` current position (from previous lookup)

#### setXConstraint

`void setXConstraint ( iLeft , iRight , iTickSize )`
By default, the element can be dragged any place on the screen. Use this method to limit the horizontal travel of the element. Pass in 0,0 for the parameters if you want to lock the drag to the y axis.

Parameters:
  `iLeft <int>` the number of pixels the element can move to the left
  `iRight <int>` the number of pixels the element can move to the right
  `iTickSize <int>` optional parameter for specifying that the element should move iTickSize pixels at a time.

#### setXTicks

`private void setXTicks ( )`
Create the array of horizontal tick marks if an interval was specified in setXConstraint().

#### setYConstraint

`void setYConstraint ( iUp , iDown , iTickSize )`
By default, the element can be dragged any place on the screen. Set this to limit the vertical travel of the element. Pass in 0,0 for the parameters if you want to lock the drag to the x axis.

Parameters:
  `iUp <int>` the number of pixels the element can move up
  `iDown <int>` the number of pixels the element can move down
  `iTickSize <int>` optional parameter for specifying that the element should move iTickSize pixels at a time.

#### setYTicks

`private void setYTicks ( )`
Create the array of vertical tick marks if an interval was specified in setYConstraint().

#### startDrag

`void startDrag ( X , Y )`
Abstract method called after a drag/drop object is clicked and the drag or mousedown time thresholds have beeen met.

Parameters:
  `X <int>` click location
  `Y <int>` click location

#### toString

`string toString ( )`
toString method

Returns: `string`
  string representation of the dd obj

#### unlock

`void unlock ( )`
Unlock this instace

#### unreg

`void unreg ( )`
Remove all drag and drop hooks for this element

### Events

#### b4DragDropEvent

`b4DragDropEvent ( )`
Fires before the dragDropEvent

#### b4DragEvent

`b4DragEvent ( )`
Fires before the dragEvent.

#### b4DragOutEvent

`b4DragOutEvent ( )`
Fires before the dragOutEvent

#### b4DragOverEvent

`b4DragOverEvent ( )`
Fires before the dragOverEvent.

#### b4EndDragEvent

`b4EndDragEvent ( )`
Fires before the endDragEvent. Returning false will cancel.

#### b4MouseDownEvent

`b4MouseDownEvent ( )`
Provides access to the mousedown event, before the mouseDownEvent gets fired. Returning false will cancel the drag.

#### b4StartDragEvent

`b4StartDragEvent ( )`
Fires before the startDragEvent, returning false will cancel the startDrag Event.

#### dragDropEvent

`dragDropEvent ( )`
Fires when the dragged objects is dropped on another.

#### dragEnterEvent

`dragEnterEvent ( )`
Occurs when the dragged object first interacts with another targettable drag and drop object.

#### dragEvent

`dragEvent ( )`
Occurs every mousemove event while dragging.

#### dragOutEvent

`dragOutEvent ( )`
Fires when a dragged object is no longer over an object that had the onDragEnter fire.

#### dragOverEvent

`dragOverEvent ( )`
Fires every mousemove event while over a drag and drop object.

#### endDragEvent

`endDragEvent ( )`
Fires on the mouseup event after a drag has been initiated (startDrag fired).

#### invalidDropEvent

`invalidDropEvent ( )`
Fires when the dragged objects is dropped in a location that contains no drop targets.

#### mouseDownEvent

`mouseDownEvent ( )`
Provides access to the mousedown event. The mousedown does not always result in a drag operation.

#### mouseUpEvent

`mouseUpEvent ( )`
Fired from inside DragDropMgr when the drag operation is finished.

#### startDragEvent

`startDragEvent ( )`
Occurs after a mouse down and the drag threshold has been met. The drag threshold default is either 3 pixels of mouse movement or 1 full second of holding the mousedown.

Copyright © 2010 Yahoo! Inc. All rights reserved.