Drag and drop in HTML

To drag data into and out of an HTML-based application (or into and out of the HTML displayed in an HTMLLoader), you can use HTML drag and drop events. The HTML drag-and-drop API allows you to drag to and from DOM elements in the HTML content.

Note: You can also use the AIR NativeDragEvent and NativeDragManager APIs by listening for events on the HTMLLoader object containing the HTML content. However, the HTML API is better integrated with the HTML DOM and gives you control of the default behavior.

Default drag-and-drop behavior

The HTML environment provides default behavior for drag-and-drop gestures involving text, images, and URLs. Using the default behavior, you can always drag these types of data out of an element. However, you can only drag text into an element and only to elements in an editable region of a page. When you drag text between or within editable regions of a page, the default behavior performs a move action. When you drag text to an editable region from a non-editable region or from outside the application, then the default behavior performs a copy action.

You can override the default behavior by handling the drag-and-drop events yourself. To cancel the default behavior, you must call the preventDefault() methods of the objects dispatched for the drag-and-drop events. You can then insert data into the drop target and remove data from the drag source as necessary to perform the chosen action.

By default, the user can select and drag any text, and drag images and links. You can use the WebKit CSS property, -webkit-user-select to control how any HTML element can be selected. For example, if you set -webkit-user-select to none, then the element contents are not selectable and so cannot be dragged. You can also use the -webkit-user-drag CSS property to control whether an element as a whole can be dragged. However, the contents of the element are treated separately. The user could still drag a selected portion of the text. For more information, see CSS in AIR.

Drag-and-drop events in HTML

The events dispatched by the initiator element from which a drag originates, are:

Event	Description
dragstart	Dispatched when the user starts the drag gesture. The handler for this event can prevent the drag, if necessary, by calling the preventDefault() method of the event object. To control whether the dragged data can be copied, linked, or moved, set the effectAllowed property. Selected text, images, and links are put onto the clipboard by the default behavior, but you can set different data for the drag gesture using the dataTransfer property of the event object.
drag	Dispatched continuously during the drag gesture.
dragend	Dispatched when the user releases the mouse button to end the drag gesture.

The events dispatched by a drag target are:

Event	Description
dragover	Dispatched continuously while the drag gesture remains within the element boundaries. The handler for this event should set the dataTransfer.dropEffect property to indicate whether the drop will result in a copy, move, or link action if the user releases the mouse.
dragenter	Dispatched when the drag gesture enters the boundaries of the element. If you change any properties of a dataTransfer object in a dragenter event handler, those changes are quickly overridden by the next dragover event. On the other hand, there is a short delay between a dragenter and the first dragover event that can cause the cursor to flash if different properties are set. In many cases, you can use the same event handler for both events.
dragleave	Dispatched when the drag gesture leaves the element boundaries.
drop	Dispatched when the user drops the data onto the element. The data being dragged can only be accessed within the handler for this event.

The event object dispatched in response to these events is similar to a mouse event. You can use mouse event properties such as ( clientX, clientY) and ( screenX, screenY), to determine the mouse position.

The most important property of a drag event object is dataTransfer, which contains the data being dragged. The dataTransfer object itself has the following properties and methods:

Property or Method	Description
effectAllowed	The effect allowed by the source of the drag. Typically, the handler for the dragstart event sets this value. See Drag effects in HTML.
dropEffect	The effect chosen by the target or the user. If you set the dropEffect in a dragover or dragenter event handler, then AIR updates the mouse cursor to indicate the effect that occurs if the user releases the mouse. If the dropEffect set does not match one of the allowed effects, no drop is allowed and the unavailable cursor is displayed. If you have not set a dropEffect in response to the latest dragover or dragenter event, then the user can choose from the allowed effects with the standard operating system modifier keys. The final effect is reported by the dropEffect property of the object dispatched for dragend. If the user abandons the drop by releasing the mouse outside an eligible target, then dropEffect is set to none.
types	An array containing the MIME type strings for each data format present in the dataTransfer object.
getData(mimeType)	Gets the data in the format specified by the mimeType parameter. The getData() method can only be called in response to the drop event.
setData(mimeType)	Adds data to the dataTransfer in the format specified by the mimeType parameter. You can add data in multiple formats by calling setData() for each MIME type. Any data placed in the dataTransfer object by the default drag behavior is cleared. The setData() method can only be called in response to the dragstart event.
clearData(mimeType)	Clears any data in the format specified by the mimeType parameter.
setDragImage(image, offsetX, offsetY)	Sets a custom drag image. The setDragImage() method can only be called in response to the dragstart event and only when an entire HTML element is dragged by setting its -webkit-user-drag CSS style to element. The image parameter can be a JavaScript Element or Image object.

MIME types for the HTML drag-and-drop

The MIME types to use with the dataTransfer object of an HTML drag-and-drop event include:

Data format	MIME type
Text	"text/plain"
HTML	"text/html"
URL	"text/uri-list"
Bitmap	"image/x-vnd.adobe.air.bitmap"
File list	"application/x-vnd.adobe.air.file-list"

You can also use other MIME strings, including application-defined strings. However, other applications may not be able to recognize or use the transferred data. It is your responsibility to add data to the dataTransfer object in the expected format.

Important: Only code running in the application sandbox can access dropped files. Attempting to read or set any property of a File object within a non-application sandbox generates a security error. See Handling file drops in non-application HTML sandboxes for more information.

Drag effects in HTML

The initiator of the drag gesture can limit the allowed drag effects by setting the dataTransfer.effectAllowed property in the handler for the dragstart event. The following string values can be used:

String value	Description
"none"	No drag operations are allowed.
"copy"	The data will be copied to the destination, leaving the original in place.
"link"	The data will be shared with the drop destination using a link back to the original.
"move"	The data will be copied to the destination and removed from the original location.
"copyLink"	The data can be copied or linked.
"copyMove"	The data can be copied or moved.
"linkMove"	The data can be linked or moved.
"all"	The data can be copied, moved, or linked. All is the default effect when you prevent the default behavior.

The target of the drag gesture can set the dataTransfer.dropEffect property to indicate the action that is taken if the user completes the drop. If the drop effect is one of the allowed actions, then the system displays the appropriate copy, move, or link cursor. If not, then the system displays the unavailable cursor. If no drop effect is set by the target, the user can choose from the allowed actions with the modifier keys.

Set the dropEffect value in the handlers for both the dragover and dragenter events:

function doDragStart(event) {
    event.dataTransfer.setData("text/plain","Text to drag");
    event.dataTransfer.effectAllowed = "copyMove";
}

function doDragOver(event) {
    event.dataTransfer.dropEffect = "copy";
}

function doDragEnter(event) {
    event.dataTransfer.dropEffect = "copy";
}

Note: Although you should always set the dropEffect property in the handler for dragenter, be aware that the next dragover event resets the property to its default value. Set dropEffect in response to both events.