Drag 和 Drop 在 JavaScript 中的使用

  • Revision slug: Drag_和_Drop_在_JavaScript_中的使用
  • Revision title: Drag 和 Drop 在 JavaScript 中的使用
  • Revision id: 273412
  • Created:
  • Creator: Jjcang
  • Is current revision? No
  • Comment 24 words added

Revision Content

{{ PreviousNext("Drag and Drop", "Drag and Drop Example") }}

这一节描述了我们怎么在 JavaScript 中使用 drag and drop.

The JavaScript Drag and Drop Wrapper

Javascript 拖拽对象

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.

javascript拖拽对象包装了xpcom中对应的拖拽对象,简化了操作。你需要实现一个事件处理器的对象,再就是一些简单的函数处理拖拽的数据。

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 another 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 is done at a lower level.

拖拽接口在全局包中:chrome://global/content/nsDragAndDrop.js。在你的xul中把这个js包含进来。

注意你需要在所用的xul页面中导入两个 chrome 路径。

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

This drag and drop library creates an 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.

我们可以参考下这个例子:

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

,它的功能是在我们第一次按下这个按钮时会通过触发nsDragAndDrop.startDrag 而执行buttonObserver方法里的onDragStart事件。第一个参数是所触发的事件元素,适用于所有的事件处理。第二个参数 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:

<description 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. In the above examples, this observer is stored in the buttonObserver andtextObserver variables. The observer is declared in a script which you would include in the XUL file using the script tag. The observer is an object which may have 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, transferData, action) 
Define this function to have something happen when a drag starts. It takes three arguments, the event object as was originally passed to the event handler, the data to drag and the type of drag action. This function should add the data to drag to the transferData object.
onDragOver(event, flavour, session) 
This function should be defined when you want something to happen when an element is dragged over. The first argument is the event object, the second is the flavour of the data and the third is a drag session object which provides more details about the drag that is occurring. You should define this function for elements that allow dragged data to be dropped on them.
onDragExit(event, session) 
This function should be defined when something should happen on a drag exit. It has two arguments, the event object and the drag session.
onDrop(event, dropData, session) 
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. The third argument is the drag session.
getSupportedFlavours() 
This function should return a list of flavours that the object being dragged over can accept. 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 onDragOveronDrop and getSupportedFlavours (and, if desired, onDragExit).

The type of data being dragged is stored as a set of flavours. Often, a dragged object will be available in a number of flavours. That way, a drop target can accept the flavour it finds most suitable. For example, a file may come in two flavours, the file itself and the text name of the file. If the file is dragged and dropped onto a directory, the file flavour will be used. If the file is dropped onto a textbox, the text name flavour will be used. The text is therefore used to insert the name of the file when files can't be dropped directly.

A flavour object has a name, which is a formatted like a MIME type, such as 'text/unicode'. Within the onDragStart function, you specify what flavours are available for the item being dragged. To do this, add data and flavours to the transferDataobject, which is the second argument to onDragStart.

An example should help here. The onDragStart function adds data to the transferData object.

var textObserver = {
  onDragStart: function (event, transferData, action) {
    var htmlText  = "<strong>Cabbage</strong>";
    var plainText = "Cabbage";
    transferData.data = new TransferData();
    transferData.data.addDataForFlavour("text/html",htmlText);
    transferData.data.addDataForFlavour("text/unicode",plainText);
  }
}

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 sets the data that is being dragged.

Once called, it starts a drag for the string data "Cabbage". 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.

We create a TransferData object which can be used to hold all the data to be dragged. We add two pieces of data to the transfer data. The first is a string of HTML text and the second is a string of plain text. If the user drops onto an area which can accept HTML (such as Mozilla's editor window), the HTML flavour will be used and the text will appear bold. Otherwise, the plain text version will be used instead.

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 above, the HTML flavour (text/html) comes first and then the text flavour (text/unicode).

The example below shows how to set the data to be dragged from the element's label attribute. In this case we only provide the data in one flavour.

var textObserver = {
  onDragStart: function (event) {
    var txt = event.target.getAttribute("label");
    transferData.data = new TransferData();
    transferData.data.addDataForFlavour("text/unicode",txt);
  }
}

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 onto it can grab the dragged data.

If you want to send more then one data object, (for example multiple files) you must use an TransferDataSet as follows:

var textObserver = {
  onDragStart: function (event) {
    var txt1 = 'hello';
    var txt2 = 'there';
    transferData.data = new TransferDataSet();

    var tmp = new TransferData();
    tmp.addDataForFlavour("text/unicode",txt1);
    transferData.data.push(tmp);

    new TransferData();
    tmp.addDataForFlavour("text/unicode",txt2);
    transferData.data.push(tmp);
  }
}

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 start 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 getSupportedFlavoursonDragOver andonDrop functions. Some elements may be able to initiate a drag and accept a drop. In this case, the onStartDrag function 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 = new FlavourSet();
    flavours.appendFlavour("text/unicode");
    return flavours;
  }
}

The flavours list contains only one flavour, which is 'text/unicode'. The FlavourSet object can be used to hold a list of flavours. In some cases, you must provide the XPCOM interface as well. For example, for files:

var textObserver = {
  getSupportedFlavours : function () {
    var flavours = new FlavourSet();
    flavours.appendFlavour("application/x-moz-file","nsIFile");
    flavours.appendFlavour("text/unicode");
    return flavours;
  }
}

The onDragOver function defines what happens when an object is dragged over. You might use it to change the appearance of the element as it is being dragged over. In many cases the function can do nothing. It must be defined for elements that accept dragged data however.

Next, the onDrop function should be created. Its second argument is the transfer data object that holds the data being dragged. By the time onDrop is called, the wrapper has called getSupportedFlavours to determine the best flavour for the drop, so the transfer object only contains the data for the best matching flavour.

The transfer object has two properties, data which holds the data and flavour which holds the flavour of the data. Once you have the data, you can add it to the element is some way. For example, you might set the value of a textbox.

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

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.

text/unicode Text data
text/html HTML data
text/x-moz-url A URL
application/x-moz-file A local file

See here for an overview of more data flavours.

{{ PreviousNext("Drag and Drop", "Drag and Drop Example") }}

Original Document Information

 

Revision Source

<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">{{ PreviousNext("Drag and Drop", "Drag and Drop Example") }}</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">这一节描述了我们怎么在 <a href="/en/JavaScript" style="text-decoration: none; color: rgb(4, 137, 183) !important; cursor: default; " title="en/JavaScript">JavaScript</a> 中使用 <a href="/en/Drag_and_Drop" style="text-decoration: none; color: rgb(4, 137, 183) !important; cursor: default; " title="en/Drag_and_Drop">drag and drop</a>.</p>
<h3 name="The_JavaScript_Drag_and_Drop_Wrapper">The JavaScript Drag and Drop Wrapper</h3>
<h3 name="The_JavaScript_Drag_and_Drop_Wrapper">Javascript 拖拽对象</h3>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">The JavaScript wrapper to drag and drop simplifies the process by handling all of the <a href="/en/XPCOM" style="text-decoration: none; color: rgb(4, 137, 183) !important; cursor: default; " title="en/XPCOM">XPCOM</a> 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.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">javascript拖拽对象包装了xpcom中对应的拖拽对象,简化了操作。你需要实现一个事件处理器的对象,再就是一些简单的函数处理拖拽的数据。</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">This drag and drop interface is stored in the global package, in the file <code style="color: rgb(37, 34, 29); font-weight: inherit; "><a class=" external" href="chrome://global/content/nsDragAndDrop.js" rel="freelink">chrome://global/content/nsDragAndDrop.js</a></code>. You can include this file in your XUL file with the <code style="color: rgb(37, 34, 29); font-weight: inherit; ">script</code> tag in the same way you would include your own scripts. The library also depends on another 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 is done at a lower level.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">拖拽接口在全局包中:<code style="color: rgb(37, 34, 29); font-weight: inherit; "><a class=" external" href="chrome://global/content/nsDragAndDrop.js" rel="freelink">chrome://global/content/nsDragAndDrop.js</a>。在你的xul中把这个js包含进来。</code></p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">注意你需要在所用的xul页面中导入两个 <a href="/en/Chrome" style="text-decoration: none; color: rgb(4, 137, 183) !important; cursor: default; " title="en/Chrome">chrome 路径。</a></p>
<pre class="eval" style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; border-top-width: 1px; border-right-width: 1px; border-bottom-width: 1px; border-left-width: 1px; border-top-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-style: solid; border-top-color: rgb(223, 236, 241); border-right-color: rgb(223, 236, 241); border-bottom-color: rgb(223, 236, 241); border-left-color: rgb(223, 236, 241); padding-top: 10px; padding-right: 10px; padding-bottom: 10px; padding-left: 10px; overflow-x: auto; overflow-y: auto; font: normal normal normal 12px/normal 'Courier New', 'Andale Mono', monospace; color: rgb(37, 34, 29); ">&lt;script src="<a class=" external" href="chrome://global/content/nsDragAndDrop.js" rel="freelink">chrome://global/content/nsDragAndDrop.js</a>" /&gt;
&lt;script src="<a class=" external" href="chrome://global/content/nsTransferable.js" rel="freelink">chrome://global/content/nsTransferable.js</a>" /&gt;
</pre>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">This drag and drop library creates an object stored in the variable <code style="color: rgb(37, 34, 29); font-weight: inherit; ">nsDragAndDrop</code>. The object contains a series of functions, one for each event handler (except for <code style="color: rgb(37, 34, 29); font-weight: inherit; ">dragenter</code> 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.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">我们可以参考下这个例子:</p>
<pre class="eval" style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; border-top-width: 1px; border-right-width: 1px; border-bottom-width: 1px; border-left-width: 1px; border-top-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-style: solid; border-top-color: rgb(223, 236, 241); border-right-color: rgb(223, 236, 241); border-bottom-color: rgb(223, 236, 241); border-left-color: rgb(223, 236, 241); padding-top: 10px; padding-right: 10px; padding-bottom: 10px; padding-left: 10px; overflow-x: auto; overflow-y: auto; font: normal normal normal 12px/normal 'Courier New', 'Andale Mono', monospace; color: rgb(37, 34, 29); ">&lt;button label="Drag Me" ondraggesture="nsDragAndDrop.startDrag(event,buttonObserver);" /&gt; </pre>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; "><code style="color: rgb(37, 34, 29); font-weight: inherit; "><span class="Apple-style-span" style="font-family: Verdana; ">,它的功能是在我们第一次按下这个按钮时会通过触发<span class="Apple-style-span" style="font-family: 'Courier New'; font-size: 12px; line-height: normal; white-space: pre; ">nsDragAndDrop.<span class="Apple-style-span" style="font-family: Verdana; font-size: 14px; line-height: 23px; white-space: normal; "><code style="color: rgb(37, 34, 29); font-weight: inherit; ">startDrag</code> </span><span class="Apple-style-span" style="font-family: Verdana; font-size: 14px; line-height: 23px; white-space: normal; "><code style="color: rgb(37, 34, 29); font-weight: inherit; "><span class="Apple-style-span" style="font-family: Verdana; "><span class="Apple-style-span" style="font-family: 'Courier New'; font-size: 12px; line-height: normal; white-space: pre; "><span class="Apple-style-span" style="font-family: Verdana; font-size: 14px; line-height: 23px; white-space: normal; ">而执行</span><span class="Apple-style-span" style="font-family: Verdana; font-size: 14px; line-height: 23px; white-space: normal; "><span class="Apple-style-span" style="font-family: 'Courier New'; font-size: 12px; line-height: normal; white-space: pre; ">buttonObserver<span class="Apple-style-span" style="font-family: Verdana; font-size: 14px; line-height: 23px; white-space: normal; ">方法里的onDragStart事件。第一个参数是所触发的事件元素,适用于所有的事件处理。第二个参数</span></span></span></span></span></code> 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:</span></span></span></code></p>
<pre class="eval" style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; border-top-width: 1px; border-right-width: 1px; border-bottom-width: 1px; border-left-width: 1px; border-top-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-style: solid; border-top-color: rgb(223, 236, 241); border-right-color: rgb(223, 236, 241); border-bottom-color: rgb(223, 236, 241); border-left-color: rgb(223, 236, 241); padding-top: 10px; padding-right: 10px; padding-bottom: 10px; padding-left: 10px; overflow-x: auto; overflow-y: auto; font: normal normal normal 12px/normal 'Courier New', 'Andale Mono', monospace; color: rgb(37, 34, 29); ">&lt;description 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)" /&gt;
</pre>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">As mentioned earlier, there is nothing special that happens during a <code style="color: rgb(37, 34, 29); font-weight: inherit; ">dragenter</code> event, so you can just write that yourself.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">The functions are implemented by the <code style="color: rgb(37, 34, 29); font-weight: inherit; ">nsDragAndDrop</code> object, which is declared in the file <code style="color: rgb(37, 34, 29); font-weight: inherit; ">nsDragAndDrop.js</code>, which was included in one of the <code style="color: rgb(37, 34, 29); font-weight: inherit; ">script</code> tags. They handle the event, handle the XPCOM interfaces and pass a simpler data structure to functions of the observer object.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">The observer is an object that you declare yourself. In the above examples, this observer is stored in the <code style="color: rgb(37, 34, 29); font-weight: inherit; ">buttonObserver</code> and<code style="color: rgb(37, 34, 29); font-weight: inherit; ">textObserver</code> variables. The observer is declared in a script which you would include in the XUL file using the <code style="color: rgb(37, 34, 29); font-weight: inherit; ">script</code> tag. The observer is an object which may have 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.</p>
<dl style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; "> <dt style="font-style: normal; font-weight: bold; ">onDragStart(event, transferData, action) </dt> <dd style="margin-left: 0px; margin-bottom: 0.5em; padding-left: 15px; ">Define this function to have something happen when a drag starts. It takes three arguments, the event object as was originally passed to the event handler, the data to drag and the type of drag action. This function should add the data to drag to the <code style="color: rgb(37, 34, 29); font-weight: inherit; ">transferData</code> object.</dd> <dt style="font-style: normal; font-weight: bold; ">onDragOver(event, flavour, session) </dt> <dd style="margin-left: 0px; margin-bottom: 0.5em; padding-left: 15px; ">This function should be defined when you want something to happen when an element is dragged over. The first argument is the event object, the second is the flavour of the data and the third is a drag session object which provides more details about the drag that is occurring. You should define this function for elements that allow dragged data to be dropped on them.</dd> <dt style="font-style: normal; font-weight: bold; ">onDragExit(event, session) </dt> <dd style="margin-left: 0px; margin-bottom: 0.5em; padding-left: 15px; ">This function should be defined when something should happen on a drag exit. It has two arguments, the event object and the drag session.</dd> <dt style="font-style: normal; font-weight: bold; ">onDrop(event, dropData, session) </dt> <dd style="margin-left: 0px; margin-bottom: 0.5em; padding-left: 15px; ">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. The third argument is the drag session.</dd> <dt style="font-style: normal; font-weight: bold; ">getSupportedFlavours() </dt> <dd style="margin-left: 0px; margin-bottom: 0.5em; padding-left: 15px; ">This function should return a list of flavours that the object being dragged over can accept. This function takes no arguments. This function is necessary so that the wrapper can determine the best flavour to pass to the other functions.</dd>
</dl>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">For an observer that is observing an element that can start a drag, you should define at least the <code style="color: rgb(37, 34, 29); font-weight: inherit; ">onDragStart</code> function. For elements that can have objects dropped on them, you should define <code style="color: rgb(37, 34, 29); font-weight: inherit; ">onDragOver</code>, <code style="color: rgb(37, 34, 29); font-weight: inherit; ">onDrop</code> and <code style="color: rgb(37, 34, 29); font-weight: inherit; ">getSupportedFlavours</code> (and, if desired, <code style="color: rgb(37, 34, 29); font-weight: inherit; ">onDragExit</code>).</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">The type of data being dragged is stored as a set of flavours. Often, a dragged object will be available in a number of flavours. That way, a drop target can accept the flavour it finds most suitable. For example, a file may come in two flavours, the file itself and the text name of the file. If the file is dragged and dropped onto a directory, the file flavour will be used. If the file is dropped onto a textbox, the text name flavour will be used. The text is therefore used to insert the name of the file when files can't be dropped directly.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">A flavour object has a name, which is a formatted like a MIME type, such as 'text/unicode'. Within the <code style="color: rgb(37, 34, 29); font-weight: inherit; ">onDragStart</code> function, you specify what flavours are available for the item being dragged. To do this, add data and flavours to the <code style="color: rgb(37, 34, 29); font-weight: inherit; ">transferData</code>object, which is the second argument to <code style="color: rgb(37, 34, 29); font-weight: inherit; ">onDragStart</code>.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">An example should help here. The <code style="color: rgb(37, 34, 29); font-weight: inherit; ">onDragStart</code> function adds data to the <code style="color: rgb(37, 34, 29); font-weight: inherit; ">transferData</code> object.</p>
<pre class="eval" style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; border-top-width: 1px; border-right-width: 1px; border-bottom-width: 1px; border-left-width: 1px; border-top-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-style: solid; border-top-color: rgb(223, 236, 241); border-right-color: rgb(223, 236, 241); border-bottom-color: rgb(223, 236, 241); border-left-color: rgb(223, 236, 241); padding-top: 10px; padding-right: 10px; padding-bottom: 10px; padding-left: 10px; overflow-x: auto; overflow-y: auto; font: normal normal normal 12px/normal 'Courier New', 'Andale Mono', monospace; color: rgb(37, 34, 29); ">var textObserver = {
  onDragStart: function (event, transferData, action) {
    var htmlText  = "&lt;strong&gt;Cabbage&lt;/strong&gt;";
    var plainText = "Cabbage";
    transferData.data = new TransferData();
    transferData.data.addDataForFlavour("text/html",htmlText);
    transferData.data.addDataForFlavour("text/unicode",plainText);
  }
}
</pre>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">Here, an observer has been declared and stored in the variable <code style="color: rgb(37, 34, 29); font-weight: inherit; ">textObserver</code>. It has one property called <code style="color: rgb(37, 34, 29); font-weight: inherit; ">onDragStart</code>. (In JavaScript, properties can be declared with the syntax <code style="color: rgb(37, 34, 29); font-weight: inherit; ">name : value</code>). This property is a function which sets the data that is being dragged.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">Once called, it starts a drag for the string data "Cabbage". 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 <code style="color: rgb(37, 34, 29); font-weight: inherit; ">target</code> property. The event object is passed as the first argument to <code style="color: rgb(37, 34, 29); font-weight: inherit; ">onDragStart</code>.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">We create a <code style="color: rgb(37, 34, 29); font-weight: inherit; ">TransferData</code> object which can be used to hold all the data to be dragged. We add two pieces of data to the transfer data. The first is a string of HTML text and the second is a string of plain text. If the user drops onto an area which can accept HTML (such as Mozilla's editor window), the HTML flavour will be used and the text will appear bold. Otherwise, the plain text version will be used instead.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">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 above, the HTML flavour (text/html) comes first and then the text flavour (text/unicode).</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">The example below shows how to set the data to be dragged from the element's <code style="color: rgb(37, 34, 29); font-weight: inherit; ">label</code> attribute. In this case we only provide the data in one flavour.</p>
<pre class="eval" style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; border-top-width: 1px; border-right-width: 1px; border-bottom-width: 1px; border-left-width: 1px; border-top-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-style: solid; border-top-color: rgb(223, 236, 241); border-right-color: rgb(223, 236, 241); border-bottom-color: rgb(223, 236, 241); border-left-color: rgb(223, 236, 241); padding-top: 10px; padding-right: 10px; padding-bottom: 10px; padding-left: 10px; overflow-x: auto; overflow-y: auto; font: normal normal normal 12px/normal 'Courier New', 'Andale Mono', monospace; color: rgb(37, 34, 29); ">var textObserver = {
  onDragStart: function (event) {
    var txt = event.target.getAttribute("label");
    transferData.data = new TransferData();
    transferData.data.addDataForFlavour("text/unicode",txt);
  }
}
</pre>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">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 <a href="/en/RDF" style="text-decoration: none; color: rgb(4, 137, 183) !important; cursor: default; " title="en/RDF">RDF</a> 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 onto it can grab the dragged data.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">If you want to send more then one data object, (for example multiple files) you must use an <code style="color: rgb(37, 34, 29); font-weight: inherit; ">TransferDataSet</code> as follows:</p>
<pre class="eval" style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; border-top-width: 1px; border-right-width: 1px; border-bottom-width: 1px; border-left-width: 1px; border-top-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-style: solid; border-top-color: rgb(223, 236, 241); border-right-color: rgb(223, 236, 241); border-bottom-color: rgb(223, 236, 241); border-left-color: rgb(223, 236, 241); padding-top: 10px; padding-right: 10px; padding-bottom: 10px; padding-left: 10px; overflow-x: auto; overflow-y: auto; font: normal normal normal 12px/normal 'Courier New', 'Andale Mono', monospace; color: rgb(37, 34, 29); ">var textObserver = {
  onDragStart: function (event) {
    var txt1 = 'hello';
    var txt2 = 'there';
    transferData.data = new TransferDataSet();

    var tmp = new TransferData();
    tmp.addDataForFlavour("text/unicode",txt1);
    transferData.data.push(tmp);

    new TransferData();
    tmp.addDataForFlavour("text/unicode",txt2);
    transferData.data.push(tmp);
  }
}
</pre>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">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 start a drag, <code style="color: rgb(37, 34, 29); font-weight: inherit; ">onStartDrag</code> is all that is necessary to implement.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">For an element that can be dropped on, the observer will need to implement at least the <code style="color: rgb(37, 34, 29); font-weight: inherit; ">getSupportedFlavours</code>, <code style="color: rgb(37, 34, 29); font-weight: inherit; ">onDragOver</code> and<code style="color: rgb(37, 34, 29); font-weight: inherit; ">onDrop</code> functions. Some elements may be able to initiate a drag and accept a drop. In this case, the <code style="color: rgb(37, 34, 29); font-weight: inherit; ">onStartDrag</code> function will be necessary as well.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">The <code style="color: rgb(37, 34, 29); font-weight: inherit; ">getSupportedFlavours</code> 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 <code style="color: rgb(37, 34, 29); font-weight: inherit; ">getSupportedFlavours</code> function. We'll allow only one flavour here, that for a string.</p>
<pre class="eval" style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; border-top-width: 1px; border-right-width: 1px; border-bottom-width: 1px; border-left-width: 1px; border-top-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-style: solid; border-top-color: rgb(223, 236, 241); border-right-color: rgb(223, 236, 241); border-bottom-color: rgb(223, 236, 241); border-left-color: rgb(223, 236, 241); padding-top: 10px; padding-right: 10px; padding-bottom: 10px; padding-left: 10px; overflow-x: auto; overflow-y: auto; font: normal normal normal 12px/normal 'Courier New', 'Andale Mono', monospace; color: rgb(37, 34, 29); ">var textObserver = {
  getSupportedFlavours : function () {
    var flavours = new FlavourSet();
    flavours.appendFlavour("text/unicode");
    return flavours;
  }
}
</pre>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">The flavours list contains only one flavour, which is 'text/unicode'. The <code style="color: rgb(37, 34, 29); font-weight: inherit; ">FlavourSet</code> object can be used to hold a list of flavours. In some cases, you must provide the XPCOM interface as well. For example, for files:</p>
<pre class="eval" style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; border-top-width: 1px; border-right-width: 1px; border-bottom-width: 1px; border-left-width: 1px; border-top-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-style: solid; border-top-color: rgb(223, 236, 241); border-right-color: rgb(223, 236, 241); border-bottom-color: rgb(223, 236, 241); border-left-color: rgb(223, 236, 241); padding-top: 10px; padding-right: 10px; padding-bottom: 10px; padding-left: 10px; overflow-x: auto; overflow-y: auto; font: normal normal normal 12px/normal 'Courier New', 'Andale Mono', monospace; color: rgb(37, 34, 29); ">var textObserver = {
  getSupportedFlavours : function () {
    var flavours = new FlavourSet();
    flavours.appendFlavour("application/x-moz-file","nsIFile");
    flavours.appendFlavour("text/unicode");
    return flavours;
  }
}
</pre>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">The <code style="color: rgb(37, 34, 29); font-weight: inherit; ">onDragOver</code> function defines what happens when an object is dragged over. You might use it to change the appearance of the element as it is being dragged over. In many cases the function can do nothing. It must be defined for elements that accept dragged data however.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">Next, the <code style="color: rgb(37, 34, 29); font-weight: inherit; ">onDrop</code> function should be created. Its second argument is the transfer data object that holds the data being dragged. By the time <code style="color: rgb(37, 34, 29); font-weight: inherit; ">onDrop</code> is called, the wrapper has called <code style="color: rgb(37, 34, 29); font-weight: inherit; ">getSupportedFlavours</code> to determine the best flavour for the drop, so the transfer object only contains the data for the best matching flavour.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">The transfer object has two properties, <code style="color: rgb(37, 34, 29); font-weight: inherit; ">data</code> which holds the data and <code style="color: rgb(37, 34, 29); font-weight: inherit; ">flavour</code> which holds the flavour of the data. Once you have the data, you can add it to the element is some way. For example, you might set the value of a textbox.</p>
<pre class="eval" style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; border-top-width: 1px; border-right-width: 1px; border-bottom-width: 1px; border-left-width: 1px; border-top-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-style: solid; border-top-color: rgb(223, 236, 241); border-right-color: rgb(223, 236, 241); border-bottom-color: rgb(223, 236, 241); border-left-color: rgb(223, 236, 241); padding-top: 10px; padding-right: 10px; padding-bottom: 10px; padding-left: 10px; overflow-x: auto; overflow-y: auto; font: normal normal normal 12px/normal 'Courier New', 'Andale Mono', monospace; color: rgb(37, 34, 29); ">var textObserver = {
  onDrop : function (event, transferData, session) {
    event.target.setAttribute("value",transferData.data);
  }
}
</pre>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">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.</p>
<table align="center" border="1" style="font-size: 100%; margin-bottom: 1.7em; "> <tbody> <tr> <td style="font-family: inherit; font-size: inherit; color: inherit; ">text/unicode</td> <td style="font-family: inherit; font-size: inherit; color: inherit; ">Text data</td> </tr> <tr> <td style="font-family: inherit; font-size: inherit; color: inherit; ">text/html</td> <td style="font-family: inherit; font-size: inherit; color: inherit; ">HTML data</td> </tr> <tr> <td style="font-family: inherit; font-size: inherit; color: inherit; ">text/x-moz-url</td> <td style="font-family: inherit; font-size: inherit; color: inherit; ">A URL</td> </tr> <tr> <td style="font-family: inherit; font-size: inherit; color: inherit; ">application/x-moz-file</td> <td style="font-family: inherit; font-size: inherit; color: inherit; ">A local file</td> </tr> </tbody>
</table>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">See <a class="external" href="http://www-archive.mozilla.org/xpfe/xptoolkit/DataFlavors.html" title="http://www-archive.mozilla.org/xpfe/xptoolkit/DataFlavors.html">here</a> for an overview of more data flavours.</p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; ">{{ PreviousNext("Drag and Drop", "Drag and Drop Example") }}</p>
<div class="originaldocinfo" style="margin-top: 15px; margin-right: 0px; margin-bottom: 15px; margin-left: 0px; border-top-width: 1px; border-right-width: 1px; border-bottom-width: 1px; border-left-width: 1px; border-top-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-style: solid; border-top-color: rgb(233, 233, 233); border-right-color: rgb(233, 233, 233); border-bottom-color: rgb(233, 233, 233); border-left-color: rgb(233, 233, 233); padding-top: 10px; padding-right: 10px; padding-bottom: 0px; padding-left: 10px; background-image: initial; background-repeat: initial; background-attachment: initial; -webkit-background-clip: initial; -webkit-background-origin: initial; background-color: rgb(243, 243, 243); font-size: 80%; font-family: Verdana, Tahoma, sans-serif; background-position: initial initial; ">
<h2 name="Original_Document_Information">Original Document Information</h2>
<ul style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; margin-left: 25px; padding-left: 0px; "> <li style="margin-bottom: 0.25em; ">Author(s): <a class="link-mailto" href="mailto:enndeakin@sympatico.ca">Neil Deakin</a></li> <li style="margin-bottom: 0.25em; ">Original Document: <a class=" external" href="http://xulplanet.com/tutorials/mozsdk/dragwrap.php" rel="freelink">http://xulplanet.com/tutorials/mozsdk/dragwrap.php</a></li> <li style="margin-bottom: 0.25em; ">Copyright Information: Copyright (C) <a class="link-mailto" href="mailto:enndeakin@sympatico.ca">Neil Deakin</a></li>
</ul>
</div>
<p> </p>
Revert to this revision