Yahoo! UI Library

Drag and Drop  2.7.0

Yahoo! UI Library > dragdrop > YAHOO.util.DragDrop
Search:
 
Filters

Class YAHOO.util.DragDrop

Known Subclasses:
YAHOO.widget.Slider DD DDTarget
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
Returns: void

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
Returns: void

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
Returns: void

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
Returns: void

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.
Returns: void

b4Drag

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

b4DragDrop

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

b4DragOut

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

b4DragOver

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

b4EndDrag

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

b4MouseDown

private void b4MouseDown ( e )
Code executed immediately before the onMouseDown event
Parameters:
e <Event> the mousedown event
Returns: void

b4StartDrag

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

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.
Returns: void

clearTicks

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

clickValidator

void clickValidator ( e )
Method validates that the clicked element was indeed the handle or a valid child of the handle
Parameters:
e <Event>
Returns: void

endDrag

void endDrag ( e )
Fired when we are done dragging the object
Parameters:
e <Event> the mouseup event
Returns: void

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

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)
Returns: void

handleOnAvailable

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

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
Returns: void

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
Returns: void

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
Returns: void

on

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

onAvailable

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

onDrag

void onDrag ( e )
Abstract method called during the onMouseMove event while dragging an object.
Parameters:
e <Event> the mousemove event
Returns: void

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.
Returns: void

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.
Returns: void

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.
Returns: void

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.
Returns: void

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
Returns: void

onMouseDown

void onMouseDown ( e )
Event handler that fires when a drag/drop obj gets a mousedown
Parameters:
e <Event> the mousedown event
Returns: void

onMouseUp

void onMouseUp ( e )
Event handler that fires when a drag/drop obj gets a mouseup
Parameters:
e <Event> the mouseup event
Returns: void

removeFromGroup

void removeFromGroup ( sGroup )
Remove's this instance from the supplied interaction group
Parameters:
sGroup <string> The group to drop
Returns: void

removeInvalidHandleClass

void removeInvalidHandleClass ( cssClass )
Unsets an invalid css class
Parameters:
cssClass <string> the class of the element(s) you wish to re-enable
Returns: void

removeInvalidHandleId

void removeInvalidHandleId ( id )
Unsets an invalid handle id
Parameters:
id <string> the id of the element to re-enable
Returns: void

removeInvalidHandleType

void removeInvalidHandleType ( tagName )
Unsets an excluded tag name set by addInvalidHandleType
Parameters:
tagName <string> the type of element to unexclude
Returns: void

resetConstraints

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

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
Returns: void

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.
Returns: void

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
Returns: void

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
Returns: void

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
Returns: void

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)
Returns: void

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.
Returns: void

setXTicks

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

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.
Returns: void

setYTicks

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

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
Returns: void

toString

string toString ( )
toString method
Returns: string
string representation of the dd obj

unlock

void unlock ( )
Unlock this instace
Returns: void

unreg

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

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 © 2009 Yahoo! Inc. All rights reserved.