Tutorials > " . "XUL Tutorial"; $pagetitle="8.5 - Drag and Drop"; $customsidebar = "xultu-sidebar.php"; include "header.php"; ?>

Drag and Drop

This section describes how to implement objects that can be dragged around and dropped onto other objects.

The Drag and Drop Interface

Many user interfaces allow one to drag particular objects around within the interface. For example, dragging files to other directories, or dragging an icon to another window to open the document it refers to. Mozilla and XUL provide a number of events that can handle when the user attempts to drag objects around.

A user can start dragging by holding down the mouse button and moving the mouse. The drag stops when the user releases the mouse. Event handlers are called when the user starts and ends dragging, and at various points in-between.

Mozilla implements dragging by using a drag session. When a user requests to drag something that can be dragged, a drag session should be started. The drag session handles updating the mouse cursor and where the object should be dropped. If something cannot be dragged, it should not start a drag session. Because the user generally has only one mouse, only one drag session is in use at a time.

Note that drag sessions can be created from within Mozilla itself or from other applications. Mozilla will translate the data being dragged as needed.

The list below describes the event handlers that can be called, which may be placed on any element. You only need to put values for the handlers where you need to do something when the event occurs.

There are two ways that drag and drop events can be handled. This first invloves using the drag and drop XPCOM interfaces directly. The second is to use a JavaScript wrapper object that handles some of this for you. This wrapper is contained in the widget-toolkit (or global) package.

XPCOM Drag and Drop

Two interfaces are used to support drag and drop. The first is a drag service, nsIDragService and the second is the drag session, nsIDragSession.

The nsIDragService is responsible for creating drag sessions when a drag starts, and removing the drag session when the drag is complete. The function 'invokeDragSession' should be called to start a drag inside an ondraggesture event handler. Once this function is called, a drag has started.

The function invokeDragSession takes four parameters, as described below:

invokeDragSession(element,transferableArray,region,actions);

The interface nsIDragService also provides the function 'getCurrentSession' which can be called from within the drag event handlers to get and modify the state of the drag. The function returns an object that implements nsIDragSession.

The interface nsIDragSession is used to get and set properties of the drag that is currently occuring. The following properties and methods are available:


(Next) In the next section, we'll see how to use the JavaScript wrapper for drag and drop.