Classes

Files

Class YAHOO.util.DragDrop

Object
   |
   +--YAHOO.util.DragDrop
Direct Known Subclasses:
YAHOO.util.DDTarget, YAHOO.util.DD
class YAHOO.util.DragDrop
Quick Links:  Field Summary | Constructor Summary | Method Summary | Method Details

Field Summary [top]

boolean available
The availabe property is false until the linked dom element is accessible. 
object config
Configuration attributes passed into the constructor 
string[] groups
The group defines a logical collection of DragDrop objects that are related. 
String id
The id of the element associated with this object. 
string[] invalidHandleClasses
An indexted array of css class names for elements that will be ignored if clicked. 
string[] invalidHandleIds
An associative array of ids for elements that will be ignored if clicked 
string[] invalidHandleTypes
An associative array of HTML tags that will be ignored if clicked. 
boolean isTarget
By default, all insances can be a drop target. 
boolean maintainOffset
Maintain offsets when we resetconstraints. 
int[] padding
The padding configured for this drag and drop object for calculating the drop zone intersection with this object. 
boolean primaryButtonOnly
By default the drag and drop instance will only respond to the primary button click (left button for a right-handed mouse). 
int[] xTicks
Array of pixel locations the element will snap to if we specified a horizontal graduation/interval. 
int[] yTicks
Array of pixel locations the element will snap to if we specified a vertical graduation/interval. 

Constructor Summary [top]

YAHOO.util.DragDrop
Defines the interface and base operation of items that that can be dragged or can be drop targets. 

Method Summary [top]

void addInvalidHandleClass (<string> cssClass)
Lets you specify a css class of elements that will not initiate a drag 
void addInvalidHandleId (<string> id)
Lets you to specify an element id for a child of a drag handle that should not initiate a drag 
void addInvalidHandleType (<string> tagName)
Allows you to specify a tag name that should not start a drag operation when clicked. 
void addToGroup (sGroup)
Add this instance to a group of related drag/drop objects. 
void applyConfig ()
Applies the configuration parameters that were passed into the constructor. 
void clearConstraints ()
Clears any constraints applied to this instance. 
void clearTicks ()
Clears any tick interval defined for this instance 
void endDrag (<Event> e)
Fired when we are done dragging the object 
HTMLElement getDragEl ()
Returns a reference to the actual element to drag. 
HTMLElement getEl ()
Returns a reference to the linked element 
void init (id, <String> sGroup, <object> config)
Sets up the DragDrop object. 
void initTarget (id, <String> sGroup, <object> config)
Initializes Targeting functionality only... 
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.) 
boolean isValidHandleChild (<ygNode> node)
Checks the tag exclusion list to see if this click should be ignored 
void lock ()
Lock this instance 
void onAvailable ()
Override the onAvailable method to do what is needed after the initial position was determined. 
void onDrag (<Event> e)
Abstract method called during the onMouseMove event while dragging an object. 
void onDragDrop (<Event> e, id)
Abstract method called when this item is dropped on another DragDrop obj 
void onDragEnter (<Event> e, id)
Abstract method called when this element fist begins hovering over another DragDrop obj 
void onDragOut (<Event> e, id)
Abstract method called when we are no longer hovering over an element 
void onDragOver (<Event> e, id)
Abstract method called when this element is hovering over another DragDrop obj 
void onMouseDown (<Event> e)
Event handler that fires when a drag/drop obj gets a mousedown 
void onMouseUp (<Event> e)
Event handler that fires when a drag/drop obj gets a mouseup 
void removeFromGroup (<string> sGroup)
Remove's this instance from the supplied interaction group 
void removeInvalidHandleClass (cssClass)
Unsets an invalid css class 
void removeInvalidHandleId (id)
Unsets an invalid handle id 
void removeInvalidHandleType (<string> tagName)
Unsets an excluded tag name set by addInvalidHandleType 
void resetConstraints ()
resetConstraints must be called if you manually reposition a dd element. 
void setDragElId (id)
Allows you to specify that an element other than the linked element will be moved with the cursor during a drag 
void setHandleElId (id)
Allows you to specify a child of the linked element that should be used to initiate the drag operation. 
void setInitPosition (diffX, diffY)
Stores the initial placement of the dd element 
void setOuterHandleElId (id)
Allows you to set an element outside of the linked element as a drag handle 
void setPadding (<int> iTop, <int> iRight, <int> iBot, <int> iLeft)
Configures the padding for the target zone in px. 
void setXConstraint (<int> iLeft, <int> iRight, <int> iTickSize)
By default, the element can be dragged any place on the screen. 
void setYConstraint (<int> iUp, <int> iDown, <int> iTickSize)
By default, the element can be dragged any place on the screen. 
void startDrag (x, y)
Abstract method called after a drag/drop object is clicked and the drag or mousedown time thresholds have beeen met. 
Object toString ()
toString method 
void unlock ()
Unlock this instace 
void unreg ()
Remove all drag and drop hooks for this element 

Field Detail [top]

available

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

config

object   config
Configuration attributes passed into the constructor

groups

string[]   groups
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.

id

String   id
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[]   invalidHandleClasses
An indexted array of css class names for elements that will be ignored if clicked.

invalidHandleIds

string[]   invalidHandleIds
An associative array of ids for elements that will be ignored if clicked

invalidHandleTypes

string[]   invalidHandleTypes
An associative array of HTML tags that will be ignored if clicked.

isTarget

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

maintainOffset

boolean   maintainOffset
Maintain offsets when we resetconstraints. Used to maintain the slider thumb value, and this needs to be fixed.

padding

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

primaryButtonOnly

boolean   primaryButtonOnly
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

xTicks

int[]   xTicks
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[]   yTicks
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.

Constructor Detail [top]

YAHOO.util.DragDrop

YAHOO.util.DragDrop ()
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 YAHOO.util.DD. setDragElId() lets you define a separate element that would be moved, as in 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);
  }
Parameters:
id - of the element that is linked to this instance
sGroup - the group of related DragDrop objects
config - an object containing configurable attributes Valid properties for DragDrop: padding, isTarget, maintainOffset, primaryButtonOnly

Method Detail [top]

addInvalidHandleClass

void addInvalidHandleClass (<string> cssClass)
Lets you specify a css class of elements that will not initiate a drag
Parameters:
cssClass - the class of the elements you wish to ignore

addInvalidHandleId

void addInvalidHandleId (<string> id)
Lets you to specify an element id for a child of a drag handle that should not initiate a drag
Parameters:
id - the element id of the element you wish to ignore

addInvalidHandleType

void addInvalidHandleType (<string> 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 - 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.

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

endDrag

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

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:
the html element

getEl

HTMLElement getEl ()
Returns a reference to the linked element
Returns:
the html element

init

void init (id, <String> sGroup, <object> config)
Sets up the DragDrop object. Must be called in the constructor of any YAHOO.util.DragDrop subclass
Parameters:
id - the id of the linked element
sGroup - the group of related items
config - configuration attributes

initTarget

void initTarget (id, <String> sGroup, <object> config)
Initializes Targeting functionality only... the object does not get a mousedown handler.
Parameters:
id - the id of the linked element
sGroup - the group of related items
config - 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:
true if this obj or all drag/drop is locked, else false

isValidHandleChild

boolean isValidHandleChild (<ygNode> node)
Checks the tag exclusion list to see if this click should be ignored
Parameters:
node -
Returns:
true if this is a valid tag type, false if not

lock

void lock ()
Lock this instance

onAvailable

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

onDrag

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

onDragDrop

void onDragDrop (<Event> e, id)
Abstract method called when this item is dropped on another DragDrop obj
Parameters:
e -
String - || YAHOO.util.DragDrop[]} id 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 (<Event> e, id)
Abstract method called when this element fist begins hovering over another DragDrop obj
Parameters:
e -
String - || YAHOO.util.DragDrop[]} id 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 (<Event> e, id)
Abstract method called when we are no longer hovering over an element
Parameters:
e -
String - || YAHOO.util.DragDrop[]} id 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 (<Event> e, id)
Abstract method called when this element is hovering over another DragDrop obj
Parameters:
e -
String - || YAHOO.util.DragDrop[]} id In POINT mode, the element id this is hovering over. In INTERSECT mode, an array of dd items being hovered over.

onMouseDown

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

onMouseUp

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

removeFromGroup

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

removeInvalidHandleClass

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

removeInvalidHandleId

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

removeInvalidHandleType

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

resetConstraints

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

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 - 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 - the id of the element that will be used to initiate the drag

setInitPosition

void setInitPosition (diffX, diffY)
Stores the initial placement of the dd element

setOuterHandleElId

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

setPadding

void setPadding (<int> iTop, <int> iRight, <int> iBot, <int> 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 - Top pad
iRight - Right pad
iBot - Bot pad
iLeft - Left pad

setXConstraint

void setXConstraint (<int> iLeft, <int> iRight, <int> 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 - the number of pixels the element can move to the left
iRight - the number of pixels the element can move to the right
iTickSize - optional parameter for specifying that the element should move iTickSize pixels at a time.

setYConstraint

void setYConstraint (<int> iUp, <int> iDown, <int> 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 - the number of pixels the element can move up
iDown - the number of pixels the element can move down
iTickSize - optional parameter for specifying that the element should move iTickSize pixels at a time.

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 - click location
Y - click location

toString

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

unlock

void unlock ()
Unlock this instace

unreg

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