XUL Tutorial - Drag and Drop JavaScript Wrapper

This section describes how to use the JavaScript wrapper for drag and drop.

The JavaScript Drag and Drop Wrapper

The JavaScript wrapper to drag and drop simplifies the process by handling all of the XPCOM interfaces for you. It works by providing an object which implements the event handlers. All you have to do is write some simpler functions which work with the data being dragged.

This drag and drop interface is stored in the global package, in the file 'chrome://global/content/nsDragAndDrop.js'. You can include this file in your XUL file with the script tag in the same way you would include your own scripts. The library also depends on some other script libraries, which you should also include, usually at the top of your XUL file. You can look at the contents of these files to see how drag and drop can be done at a lower level.

<script src="chrome://global/content/nsDragAndDrop.js"/>
<script src="chrome://global/content/nsTransferable.js"/>
<script src="chrome://global/content/nsJSSupportsUtils.js"/>
<script src="chrome://global/content/nsJSComponentManager.js"/>

This drag and drop library has one object stored in the variable nsDragAndDrop. The object contains a series of functions, one for each event handler (except for dragenter where it has nothing special to do). Each of the functions takes two parameters, the first is the event object and the second is an observer object that you create. More on that in a moment.

The following is an example of calling the nsDragAndDrop object.

<button value="Drag Me" ondraggesture="nsDragAndDrop.startDrag(event,buttonObserver);

The function 'startDrag' will be called when a drag starts on the button. The first parameter is the event object, available in all event handlers. The second parameter to this function is the observer, which we'll create soon. In this case we only do anything special when the button drag is started. If we wanted to handle the other cases also, we can call the other functions, as in the next example:

<text value="Click and drag this text."
         ondraggesture="nsDragAndDrop.startDrag(event,textObserver)"
         ondragover="nsDragAndDrop.dragOver(event,textObserver)"
         ondragexit="nsDragAndDrop.dragExit(event,textObserver)">
         ondragdrop="nsDragAndDrop.drop(event,textObserver)"

As mentioned earlier, there is nothing special that happens during a dragenter event, so you can just write that yourself.

The functions are implemented by the nsDragAndDrop object, which is declared in the file nsDragAndDrop.js, which was included in one of the script tags. They handle the event, handle the XPCOM interfaces and pass a simpler data structure to functions of the observer object.

The observer is an object that you declare yourself. It has a number of properties, each set to a function which handles a particular aspect of drag and drop. Five functions may be defined. You only have to define the ones that you need.

• onDragStart (event)
  Define this function to have something happen when a drag starts. It takes one argument, the event object as was originally passed to the event handler. This function should return a list of flavours of the data that will be dragged, the format of which will be described later.
• onDragOver (event, flavour)
  This function should be defined when you want something to happen when an element is dragged over. The first argument is the event object and the second is the flavour of the data.
• onDragExit (event)
  This function should be defined when something should happen on a drag exit. It has one argument, the event object.
• onDrop (event, dropdata)
  This function should be defined when you want something to happen when an object is dropped. The first argument is the event object and the second is the data being dragged.
• getSupportedFlavours ( )
  This function should return a list of flavours that the object being dragged over can accept. The returned value is similar to the value returned by onDragStart. This function takes no arguments. This function is necessary so that the wrapper can determine the best flavour to pass to the other functions.

For an observer that is observing an element that can start a drag, you should define at least the onDragStart function. For elements that can have objects dropped on them, you should define onDrop and getSupportedFlavours (and, if desired, onDragOver and onDragExit).

The functions take and return as arguments a flavour or list of flavours. For example, the getSupportedFlavours function returns a list of flavours. Each flavour is used to specify what kind of data is accepted for dropping on an element. For a file, there may be two flavours, one a file and the other text. The text can be used to insert the name of the file somewhere, where files aren't supported directly.

A flavour object has a name, which is a formatted like a MIME type, such as 'text/unicode'. A flavour also has one to three properties:

• iid
  The XPCOM interface ID of the type of data, such as nsIWSupportsString for a string.
• width
  The width of the data. For strings, this should be either 1 or 2. Just use 2 for other types.
• data
  The data to be dragged in the flavour. This property can be left out of when using the getSupportedFlavours function.

An example should help here. The onDragStart function returns a list of flavours.

var textObserver = {
  onDragStart: function (evt){
    var flavours = { };
    flavours["text/unicode"] = { width: 2, data: "Text to drag" };
    return flavours;
  },

Here, an observer has been declared and stored in the variable 'textObserver'. It has one property called onDragStart. (In JavaScript, properties can be declared with the syntax name : value). This property is a function which returns a list of flavour objects.

Once called, it starts a drag for the string data "Text to drag." Of course, you would want to calculate this value from the element that was clicked on. Conveniently, this element is available from the event object's target property. The event object is passed as the first argument to onDragStart.

The 'iid' property does not need to be specified because it can be determined from the data.

The example below shows how to set the data to be dragged from the element's value attribute.

var textObserver = {
  onDragStart: function (evt){
    var txt=evt.target.getAttribute("value");
    var flavours = { };
    flavours["text/unicode"] = { width: 2, data: txt };
    return flavours;
  },

This might be useful when implementing drag and drop for cells in a tree. You can use the value of a cell, or some resource from an RDF file if the tree is built from a template, as the value of a drag. If you store it as a string, any object that accepts strings dragged on it can grab the dragged data.

You will need to add an observer to each element that can either start a drag action or can accept dropped objects. You can reuse the same observer for multiple elements. For an element that can starts a drag, onStartDrag is all that is necessary to implement.

For an element that can be dropped on, the observer will need to implement at least the getSupportedFlavours and onDrop functions. Some elements may be able to initiate a drag and accept a drop. In this case, onStartDrag will be necessary as well.

The getSupportedFlavours function should return a list of flavours that the element being dragged over can accept for dropping. A file system directory view might accept files and perhaps text, but wouldn't accept HTML text. Below, we'll define a getSupportedFlavours function. We'll allow only one flavour here, that for a string.

var textObserver = {
  getSupportedFlavours : function () {
    var flavours = { };
    flavours["text/unicode"] = { width: 2, iid: "nsISupportsWString" };
    return flavours;
  }

The flavours list contains only one flavour, which is 'text/unicode'. This is the flavour to use for text data. We need to specify some additional information about the data, the width and the XPCOM Interface ID. You can repeat this line for other flavours. For example, the following can be used for a file:

var textObserver = {
  getSupportedFlavours : function () {
    var flavours = { };
    flavours["application/x-moz-file"] = { width: 2, iid: "nsIFile" };
    flavours["text/unicode"] = { width: 2, iid: "nsISupportsWString" };
    return flavours;
  }

Usually you will want to provide a text version of the data so that more applications can accept the data. The order that you define the flavours should be from the best match to the weakest match. In this case, the file flavour (application/x-moz-file) and then text (text/unicode).

Next, onDrop should be created. It's second argument is an object that contains the data being dragged. The object has two properties, 'data' which holds the data and 'flavour' which holds the flavour of the data, such as "text/unicode". The function will be called only for the best possible flavour. The wrapper will compare the available flavours of the dragged data and the results of the getSupportedFlavours to determine this.

Once you have the data, you can add it to the element is some way. For example, you might set the value of a textfield.

var textObserver = {
  onDrop : function (evt, dragdata) {
    event.target.setAttribute("value",dragdata.data.data);
  }

The dragdata contains the object in the format described above. The data property of this object is an XPCOM object, which for Unicode text, will be the interface nsISupportsWString. This interface has one property also called 'data' which will hold the actual text.

The onDragOver function might be implemented if you wish to change the appearance of the element as it is being dragged over. Its second argument is the flavour being dragged, such as "text/unicode".

The flavour system used allows multiple objects of various types to be dragged at once and also allows alternative forms of the data to be dragged. The following table describes some of the flavours you might use. You can also make up your own flavours if necessary. More information can be found at . ***

(Next) In the next section, we'll look an example that uses drag and drop.