DropTarget リファレンス

フォルダやファイルへのドロップ操作(IDropTarget)をスクリプトから実行する DropTarget オブジェクトのリファレンスです。

• ファイルのドラッグ&ドロップを「プログラムから」行うためのものです(ドロップされたときの処理を書くには te.OnDrop などのイベントを使います)。
• 関連: FolderItem リファレンス、FolderItems リファレンス、Memory リファレンス、FolderView リファレンス、api リファレンス、te リファレンス

記法: P=プロパティ、M=メソッド。メンバー名の照合は大文字小文字を区別しません。

目次

1. 取得方法
2. メソッド
3. プロパティ
4. 動作の流れとスクリプトのイベント
5. 定数
6. 使用例

1. 取得方法

• 項目が IDropTarget を提供しない場合(ドロップを受け付けない通常ファイルなど)でも、オブジェクト自体は返ります。その場合、シェル側のドロップ処理は行われません(スクリプトのイベントのみ動作)。ドロップを受け付けるかどうかの判定には、if (api.DropTarget(item)) のように戻り値の有無を使っている標準スクリプトがありますが、受け付けない項目で空が返るのかオブジェクトが返るのかは実装から断定できません(要確認)。
• 非同期スクリプト(ui.js など WebView2 側)では、各メソッド呼び出しに await が必要です。

2. メソッド

DragEnter / DragOver / Drop は、同じ引数を取ります。

DropTarget.Drop(dataObj, grfKeyState, pt [, pdwEffect [, bSingle [, caller]]])

引数は最低3個(dataObj, grfKeyState, pt)必要です。足りない場合は何も実行せず E_INVALIDARG を返します。

戻り値は S_OK(0)で成功、失敗は負値(E_INVALIDARG = 0x80070057 など)です。

3. プロパティ

4. 動作の流れとスクリプトのイベント

bSingle を偽(省略)にして呼ぶと、1回の呼び出しの中で、それより前の段階も順に実行されます。

通常は Drop(…) を1回呼ぶだけでよく、1つ前の段階を明示的に呼ぶ必要はありません(sync1.js や標準アドオンも、Drop または DragOver を単独で呼んでいます)。 bSingle を真にすると、呼んだ段階だけが実行され、DragLeave も自動では呼ばれません(DragEnter/DragOver/Drop を自分で順に呼び、最後に DragLeave() を呼びたいときに使います)。

スクリプトのイベントとの連携

api.DropTarget(item) で作った DropTarget(対象項目あり)は、各段階で、まずスクリプトのイベント(te.OnDragEnter / te.OnDragOver / te.OnDrop)を呼び、続いてシェル標準の処理を行います。

• イベントの引数は (Ctrl, dataObj, pgrfKeyState, pt, pdwEffect) で、Ctrl は caller(省略時は DropTarget 自身)、pgrfKeyState と pdwEffect は Memory(DWORD)です(sync1.js の実装では pgrfKeyState[0]、pdwEffect[0] で読み書きしています)。
• イベントに渡される pt は常に (0, 0) で、実際のドロップ位置ではありません(実装上、位置情報は渡されない)。
• イベント内から DropTarget を再び呼ぶ(再入)場合、再入が深くなりすぎると、イベントは呼ばれなくなります(内部で10回未満に制限)。

5. 定数

consts.js で定義されています。

DROPEFFECT_*: DROPEFFECT_NONE = 0 / DROPEFFECT_COPY = 1 / DROPEFFECT_MOVE = 2 / DROPEFFECT_LINK = 4

MK_*: MK_LBUTTON = 1 / MK_RBUTTON = 2 / MK_SHIFT = 4 / MK_CONTROL = 8 / MK_MBUTTON = 0x10 / MK_XBUTTON1 = 0x20 / MK_XBUTTON2 = 0x40

CTRL_DT = 0x80000(Type が返す値)

6. 使用例

// 選択中のファイルを、別のフォルダへ「ドロップ」する(Ctrl 付き=コピー)
const FV = te.Ctrl(CTRL_FV);
const Items = FV.SelectedItems();
const DropTarget = api.DropTarget("C:\\Backup");
if (DropTarget) {
    const pdwEffect = api.Memory("DWORD");
    pdwEffect[0] = DROPEFFECT_COPY | DROPEFFECT_MOVE | DROPEFFECT_LINK;
    const pt = api.Memory("POINT");
    api.GetCursorPos(pt);
    const hr = DropTarget.Drop(Items, MK_LBUTTON | MK_CONTROL, pt, pdwEffect);
    // hr === 0 (S_OK) なら成功。pdwEffect[0] に実際の効果が入る
}

// 効果だけ調べる(実際には実行しない)
const dt = api.DropTarget(dest);
const eff = api.Memory("DWORD");
eff[0] = DROPEFFECT_COPY | DROPEFFECT_MOVE | DROPEFFECT_LINK;
dt.DragOver(Items, MK_LBUTTON, pt, eff);
const canMove = !!(eff[0] & DROPEFFECT_MOVE);

// イベントの中で、標準のドロップ処理に委ねる
te.OnDrop = function (Ctrl, dataObj, pgrfKeyState, pt, pdwEffect) {
    const Target = Ctrl.FolderItem;
    const DropTarget = api.DropTarget(Target);
    if (DropTarget) {
        return DropTarget.Drop(dataObj, pgrfKeyState[0], pt, pdwEffect);
    }
};

// 段階を自分で制御(bSingle = true)
const d = api.DropTarget(dest);
d.DragEnter(Items, MK_LBUTTON, pt, eff, true);
d.DragOver(Items, MK_LBUTTON, pt, eff, true);
d.Drop(Items, MK_LBUTTON, pt, eff, true);
d.DragLeave();

te.OnDrop の中で自分自身のイベントを再び呼び出してしまうと、Ctrl が同じ項目のときに無限に呼び合う可能性があります。標準スクリプトでは api.DropTarget(Target) の Target を Ctrl.FolderItem や HitTest の結果に限定して使っています。

関連

• FolderItem リファレンス
• FolderItems リファレンス
• FolderView(ShellBrowser)リファレンス
• Memory リファレンス
• api リファレンス
• te リファレンス