このセクションでは、ドラッグとドロップのための JavaScript ラッパー (wrapper) の使い方を説明します。
| ドラッグとドロップラッパー API は、最近変更されました。以下で文書化したのは、新しいインターフェースです。 |
ドラッグとドロップのための JavaScript ラッパーは、XPCOM インターフェースすべてを処理することによって、プロセスを単純化してくれます。これは、イベントハンドラーを実装するオブジェクトを提供することによって、動作します。利用者がしなければならないのは、ドラッグされるデータを使って作業をする簡単な関数を幾つか書くことだけです。
このドラッグとドロップのインターフェースは、'chrome://global/content/nsDragAndDrop.js' ファイル内の global パッケージに保存されています。このファイルは、自分自身のスクリプトをインクルードするのと同じ方法で、script タグを使って自分の XUL ファイルにインクルードできます。そのライブラリーも、通常 XUL ファイルの先頭にインクルードするはずの他のスクリプトライブラリーの幾つかに依存します。もっと低いレベルでドラッグとドロップがどのように行なわれているのか理解するために、これらのファイルの内容を見るとよいでしょう。
これらのライブラリーは、クロム URL を使ってロードされた XUL 内部からしか使えないことに注意して下さい。
<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"/> |
このドラッグとドロップのライブラリーには、変数 nsDragAndDrop に保存されたオブジェクトがあります。オブジェクトには、(特にやることのない dragenter を除く) 個々のイベントハンドラーのための一連の関数があります。関数はそれぞれパラメータを 2 つ取ります。最初は、イベントオブジェクトで、2 番目は、利用者が作るオブザーバーオブジェクトです。これについてはすぐ後で見ることにします。
以下は、 nsDragAndDrop オブジェクトを呼び出す例です。
<button label="Drag Me" ondraggesture="nsDragAndDrop.startDrag(event,buttonObserver); |
関数 'startDrag' は、ボタンでドラッグが始まると呼び出されます。最初のパラメータは、イベントハンドラーすべてで利用できるイベントオブジェクトです。この関数の 2 番目のパラメータは、オブザーバーです。これについては、すぐに作ります。この場合、ボタンのドラッグが開始されたときにしか特別なことはしません。他の場合も処理したければ、次の例にあるように、別の関数を呼び出すことができます。
<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)"
|
前で述べたように、dragenter イベントの間には特別なことは何も起きません。そのため、それは自分で書いて構いません。
関数は、nsDragAndDrop オブジェクトが実装しています。これは、ファイル nsDragAndDrop.js で宣言されており、script タグの一つでインクルードされています。それらはイベントを処理し、XPCOM インターフェースを処理して、比較的単純なデータ構造をオブザーバーオブジェクトに渡します。
オブザーバーは、利用者が宣言するオブジェクトです。上の例では、このオブザーバーは、buttonObserver と textObserver 変数に保存されています。オブザーバーは、script タグを使って XUL ファイルにインクルードするスクリプト内で宣言します。オブザーバーオブジェクトは、多数のプロパティーをもつ場合もあります。これらのプロパティーは、ドラッグとドロップの特定の局面を処理する関数に設定されます。関数が 5 つ定義されるかもしれません。利用者は、自分が必要とする関数だけを定義するだけで構いません。
ドラッグを開始できる要素を監視している (observing) オブザーバーのため、少なくとも onDragStart 関数を定義すべきです。また、ドロップできるオブジェクトのある要素のため、onDragOver、onDrop、getSupportedFlavours (そして必要なら、onDragExit) を定義すべきです。
ドラッグされるデータの型は、フレーバーのセットとして保存されます。しばしば、ドラッグされるオブジェクトは、多数のフレーバーで利用可能です。そのため、ドロップのターゲットは、最も適切と思えるフレーバーを受け入れることができます。例えば、ファイルは、ファイル自身に関するものとファイルのテキスト名という の2 つのフレーバー付きでやって来るかもしれません。ファイルがドラッグされディレクトリーにドロップされると、ファイルフレーバーが使われるでしょう。ファイルがテキストボックスにドロップされると、テキスト名フレーバーが使われるでしょう。そのため、ファイルを直接ドロップできない場合、テキストがファイルの名前を挿入するのに使われます。
フレーバーには名前があります。これは、'text/unicode' などの MIME 型のようなフォーマットです。onDragStart 関数内では、ドラッグされる項目に対してどのフレーバーが利用できるか指定します。このためには、transferData オブジェクトにデータとフレーバーを追加します。これは、onDragStart への 2 番目の引数です。
ここでは、例を使うと分かりやすいでしょう。onDragStart 関数は、transferData オブジェクトにデータを追加します。
var textObserver = {
onDragStart: function (evt , transferData, action){
var htmlText="<b>Cabbage</b>";
var plainText="Cabbage";
transferData.data=new TransferData();
transferData.data.addDataForFlavour("text/html",htmlText);
transferData.data.addDataForFlavour("text/unicode",plainText);
},
|
ここでは、オブザーバーが宣言され、変数 'textObserver' に保存されています。ここには onDragStart という名前のプロパティーが一つあります。(JavaScript では、プロパティーは、名前 : 値というシンタックスを使って宣言できます。) このプロパティーは、ドラッグされるデータの設定を行なう関数です。
呼び出されると、これは、文字列データ "Cabbage" のドラッグを開始します。もちろん、この値をクリックされた要素から計算したいかもしれません。便利なことに、この要素は、イベントオブジェクトの target プロパティーから利用できます。イベントオブジェクトは、onDragStart への最初の引数として渡されます。
ドラッグされるデータすべてを保持するのに使うことのできる TransferData オブジェクトを作ります。TransferData にデータを 2 つ追加します。最初のものは、HTML テキストからなる文字列で、2 番目のものは、プレーンテキストからなる文字列です。ユーザーが (Mozilla の編集ウィンドウなどの) HTML を受け入れることのできる領域にドロップすると、HTML フレーバーが使われ、テキストは太字で表示されます。それ以外の場合は、プレーンテキストバージョンが使われるでしょう。
通常、多くのアプリケーションがデータを受け入れることができるように、データのテキストバージョンを提供したいことでしょう。フレーバーを定義する順番は、最善のマッチとなるものから始めて、最も特殊なマッチとなるようにすべきです。上の場合では、HTML フレーバー (text/html) が最初に来て、次にテキストフレーバー (text/unicode) としています。
下の例は、要素の label 属性からドラッグされるデータを設定する方法を示しています。この場合、データは、フレーバー一つだけで提供されています。
var textObserver = {
onDragStart: function (evt){
var txt=evt.target.getAttribute("label");
transferData.data=new TransferData();
transferData.data.addDataForFlavour("text/unicode",txt);
},
|
これは、ツリーのセルのドラッグとドロップを実装する場合に役立つかもしれません。セルの値、あるいはツリーがテンプレートから作られている場合は RDF ファイルのリソースの幾つかがドラッグの値として使えます。それを文字列として保存すると、ドラッグされる文字列を受け入れるオブジェクトはどれも、ドラッグされたデータを捉えることができます。
ドラッグを開始できるかドロップされるオブジェクトを受け入れることのできる個々の要素にオブザーバーを追加する必要があります。同じオブザーバーを複数の要素で再利用することができます。ドラッグを開始できる要素にとって、実装する必要があるのは onDragStart だけです。
ドロップできる要素にとって、オブザーバーは、少なくとも getSupportedFlavours、onDragOver、onDrop 関数を実装する必要があります。要素の中には、ドラッグを開始し、ドロップを受け入れることのできるものもあります。その場合は、onDragStart も必要になります。
getSupportedFlavours 関数は、上をドラッグされる要素が受け入れることのできるドロップのフレーバーのリストを返します。ファイルシステムディレクトリーのビューはファイルとおそらくテキストを受け入れるでしょうが、HTML テキストは受け入れないでしょう。下で、getSupportedFlavours 関数を定義します。ここでは、一つのフレーバー、つまり文字列のためのフレーバーだけを許すことにします。
var textObserver = {
getSupportedFlavours : function () {
var flavours = new FlavourSet();
flavours.appendFlavour("text/unicode");
return flavours;
}
|
フレーバーリストには、フレーバーが一つだけあります。'text/unicode' です。FlavourSet オブジェクトは、フレーバーのリストを保持するのに使用できます。場合によっては、XPCOM インターフェースも提供する必要があるでしょう。例えば、ファイルの場合は、次のようになります。
var textObserver = {
getSupportedFlavours : function () {
var flavours = new FlavourSet();
flavours.appendFlavour("application/x-moz-file","nsIFile");
flavours.appendFlavour("text/unicode");
return flavours;
}
|
onDragOver 関数には、オブジェクトがその要素上をドラッグされると何が起こるかを定義します。要素上をドラッグされると、要素の外見を変えるためにこれが使えるかもしれません。多くの場合、この関数は何もできません。しかし、ドラッグされるデータを受け入れる要素のために定義しなければなりません。
次に、onDrop を作るべきです。その 2 番目の引数は、ドラッグされるデータを保持する転送データオブジェクトです。onDrop が呼び出される時までに、ラッパーは、ドロップのための最適なフレーバーを判断するために、getSupportedFlavours を呼び出しました。その結果、転送オブジェクトには、マッチした最適のフレーバーのためのデータだけがあります。
転送オブジェクトにはプロパティーが 2 つあります。データを保持する 'data' とデータのフレーバーを保持する 'flavour' です。データがあれば、何らかの方法で、それを要素に追加することができます。例えば、次のようにすれば、テキストボックスの値の設定ができるでしょう。
var textObserver = {
onDrop : function (evt, transferData, session) {
event.target.setAttribute("value",transferData.data);
}
|
使われているフレーバーシステムによって、様々な型をもつ複数のオブジェクトを同時にドラッグしたり、代替形式のデータのドラッグもできます。以下のテーブルで、使用できるフレーバーの幾つかを記述します。必要なら自分自身のフレーバーを作ることもできます。これ以上の情報は、 *** にあります。(訳注: この文章は不完全です。いずれ書き換えられると思います。)
| text/unicode | テキストデータ |
| text/html | HTML データ |
| application/x-moz-file | ローカルファイル |
(進む) 次のセクションでは、ドラッグとドロップを使った例を見ることにしましょう。