Google Gadgets API 入門 (7)

2007-01-11 Google Gadgets API 入門 (7)

■[Google Gadgets] Google Gadgets API 入門 (7)

今回は Feature-specific ライブラリから、ドラッグ機能を提供する drag ライブラリについて解説します。

drag ライブラリとは

drag ライブラリとは、Gadget に含まれる HTML 要素のドラッグ＆ドロップ機能を実現するための Feature-specific ライブラリです。drag ライブラリでは、任意の HTML 要素をドラッグ＆ドロップの対象にすることができます。

drag ライブラリの使用

drag ライブラリを使用するには、以下のように Gadget-Spec で宣言する必要があります：

<Module>
  <ModulePrefs ...>
    <Require feature="drag" />
  </ModulePrefs>
  ...
</Module>

プログラム側では、ドラッグ＆ドロップ機能を提供する drag オブジェクトをインスタンス化します：

var drag = new _IG_Drag()

drag オブジェクトはグローバル変数として一つだけ用意すれば良いでしょう。

用語の定義

drag ライブラリに含まれる関数の説明に入る前に、drag ライブラリで使用される用語を以下に示します：

Source: ドラッグ対象の HTML 要素です。
Target: ドロップ先の HTML 要素です。
Drag-ID: drag オブジェクトに追加された Source や Target に割り当てられる識別子です。
Surrogate: ドラッグ中の要素を表すオブジェクトです。以下を参照してください。

Surrogate とはドラッグ中のオブジェクトの HTML です。例として Surrogate に "<b>Dragging!!</b>" が指定されている要素をドラッグする様子を下図に示します：

関数

drag オブジェクトでは以下の関数が提供されています。これらの関数を用いて、Source や Target の追加/削除を行います：

_IG_Drag()	drag オブジェクトのコンストラクタです。
addSource(DOM_id)	drag オブジェクトに Source を追加します。DOM_id には Source に追加する HTML 要素に割り当てられた ID を指定します。例として、<div id="hoge">piyo</div> という HTML 要素を追加する場合は addSource("hoge") と指定します。DOM_id に指定した値は、そのまま Drag-ID に使用されます。
addSource(drag_id, HTML_element, surrogate)	drag オブジェクトに Source を追加します。例として、<div id="hoge">piyo</div> という HTML 要素を "id-1" という Drag-ID として追加する場合は、addSource("id-1", _gel("hoge")) と指定します。また、ドラッグ中の HTML 表現を指定する場合は Surrogate も指定します（例："<b>Dragging!!</b>" など）。Surrogate を省略した場合は、Source を複製したものが使用されます。
removeSource(drag_id)	指定された Drag-ID を持つ Source を drag オブジェクトから削除します。
removeAllSources()	drag オブジェクトから全ての Source を削除します。
addTarget(DOM_id)	drag オブジェクトに Target を追加します。DOM_id には Target に追加する HTML 要素に割り当てられた ID を指定します。例として、<div id="hoge">piyo</div> という HTML 要素を追加する場合は addTarget("hoge") と指定します。DOM_id に指定した値は、そのまま Drag-ID に使用されます。
addTarget(drag_id, HTML_element, priority)	drag オブジェクトに Target を追加します。例として、<div id="hoge">piyo</div> という HTML 要素を "id-1" という Drag-ID として追加する場合は、addTarget("id-1", _gel("hoge")) と指定します。priority は複数の Target がヒットしえる状況で、どの Target が優先されるかを決める整数値です（値が大きいほうが優先順位が高くなります）。
removeTarget(drag_id)	指定された Drag-ID を持つ Target を drag オブジェクトから削除します。
removeAllTargets()	drag オブジェクトから全ての Target を削除します。

コールバック関数

drag ライブラリでは、ドラッグの開始や終了などの通知にコールバック関数が使用されます。コールバック関数は drag オブジェクトのプロパティに設定します：

onDragStart = function(newSource) {}	ドラッグ開始時に呼び出されます。
onDragTargetHit = function(newTarget, lastTarget) {}	ドラッグ中かつドロップ対象の上にマウスが侵入した時に呼び出されます。
onDragTargetLost = function(lastTarget) {}	ドラッグ中かつドロップ対象の上からマウスが離れた時に呼び出されます。
onDragEnd = function(source, target) {}	ドロップされた時に呼び出されます。
onDragClick = function(source) {}	ドラッグ開始後、マウスが移動されることなくマウス・ボタンが離された時に呼び出されます。

各関数の引数には、ドラッグ対象やドロップ先の HTML 要素を表す DOM-Node が渡されます。そこから DOM-ID を取得するには source.id などとします。

読み取り専用のプロパティ

以下に drag オブジェクトの読み取り専用のプロパティを示します：

isDragging	ドラッグ中である場合に true となります。
hasDragged	isDragging が true かつ最後の mouseDown からユーザがマウスを移動した場合に true となります。
surrogate	現在の Surrogate を指します。
surrogateInitialX surrogateInitialY	ドラッグが開始された Surrogate の場所です。
curSource	現在の Source を指します。ドラッグが行われていない場合は null です。
curTargetId	現在の Target の ID です。ドラッグが行われていない場合は null です。

読み書き可能なプロパティ

以下に drag オブジェクトの読み書き可能なプロパティを示します：

leftMargin rightMargin topMargin bottomMargin	各 Target の周囲のマージンです。マージンの値が大きいほど、ヒットしたと判定される範囲が大きくなります。デフォルトのマージンは 2 ピクセルです。
surrogateOffsetX surrogateOffsetY	ドラッグを開始するときの Surrogate のオフセットです。デフォルトは 1 ピクセルです。ユーザにドラッグが開始したことを伝えるために、1 以上の値を指定することが推奨されます。

これらのプロパティの値を変更することによる影響は、視覚的に比べてみると理解しやすいと思います。

以下の画像は、左側が bottomMargin=2（デフォルト）の場合、右側が bottomMargin=10 の場合の、ヒットしたと判定される境界の位置を比べたものです。bottomMargin=10 とした方が、ヒットしたと判定される範囲が広いことが分かります：

以下の左側の画像は surrogateOffsetY=1（デフォルト）、右側の画像は surrogateOffsetY=20 の場合のドラッグ開始時の画像です。ドラッグ開始時の Surrogate の位置が異なることが分かります：

サンプル Gadget

最後に、冒頭の「drag ライブラリとは」で示した Gadget の Gadget-Spec を示します。ドラッグ＆ドロップのイベントが発生するのか確かめることができます：

<?xml version="1.0" encoding="UTF-8" ?>

<Module>
  <ModulePrefs title="Hello, drag Library" scrolling="true">
    <Require feature="drag" />
  </ModulePrefs>
  <Content type="html">
  <![CDATA[

<!-- Source/Target に使用する要素. -->
<ul>
<li id="id-0">[id-0] アヒルのように歩き</li>
<li id="id-1">[id-1] アヒルのように鳴くならば</li>
<li id="id-2">[id-2] それはアヒルに違いない</li>
</ul>

<!-- 状態表示用に使用する. -->
<pre id="status" style="font-size:small">status:</pre>

<script language="JavaScript">

// グローバル・スコープに drag オブジェクトを用意する.
var drag = new _IG_Drag()

// Source/Target を追加する.
drag.addSource("id-0")
drag.addSource("id-1")
drag.addSource("id-2")
drag.addTarget("id-0")
drag.addTarget("id-1")
drag.addTarget("id-2")

drag.onDragStart = function(source)
{
    _gel("status").innerHTML = "start: " + source
}

drag.onDragTargetHit = function(new_target, last_target)
{
    _gel("status").innerHTML += "<br />hit: " + last_target.id + " -> " + new_target.id
}

drag.onDragTargetLost = function(last_target)
{
    _gel("status").innerHTML += "<br />lost: " + (last_target == null ? null : last_target.id)
}

drag.onDragEnd = function(source, target)
{
    _gel("status").innerHTML += "<br />end: " + source.id + " -> " + target.id
}

drag.onDragClick = function(source)
{
    _gel("status").innerHTML += "<br />click: " + source.id
}

function showDragStatus()
{
    _gel("status").innerHTML = ""
        + "isDragging        = " + drag.isDragging        + "<br />"
        + "hasDragged        = " + drag.hasDragged        + "<br />"
        + "surrogate         = " + drag.surrogate         + "<br />"
        + "surrogateInitialX = " + drag.surrogateInitialX + "<br />"
        + "surrogateInitialY = " + drag.surrogateInitialY + "<br />"
        + "curSource         = " + drag.curSource         + "<br />"
        + "curTargetId       = " + drag.curTargetId       + "<br />"
        + "leftMargin        = " + drag.leftMargin        + "<br />"
        + "rightMargin       = " + drag.rightMargin       + "<br />"
        + "topMargin         = " + drag.topMargin         + "<br />"
        + "bottomMargin      = " + drag.bottomMargin      + "<br />"
        + "surrogateOffsetX  = " + drag.surrogateOffsetX  + "<br />"
        + "surrogateOffsetY  = " + drag.surrogateOffsetY  + "<br />"
}

</script>

  ]]>
  </Content>
</Module>

ソースコードの最後の方にある showDragStatus() 関数は drag オブジェクトのプロパティの値を表示する関数です。上のコード内では使用していませんが、必要ならばそれを呼び出すコードを追加してみてください。

次回予告

次回は Feature-specific ライブラリの MiniMessage ライブラリについて解説します。

紅孔雀