DropTarget Reference

This is a reference for the DropTarget object, which allows executing drag-and-drop operations (IDropTarget) on folders and files via script.

• This object is used to programmatically perform drag-and-drop operations for files. (To write handlers for when items are dropped, use events like te.OnDrop).
• Related: FolderItem Reference, FolderItems Reference, Memory Reference, FolderView Reference, api Reference, te Reference

Notation: P = Property, M = Method. Member names are case-insensitive.

Table of Contents

1. How to Obtain
2. Methods
3. Properties
4. Execution Flow and Script Events
5. Constants
6. Examples

1. How to Obtain

• Even if the item does not provide an IDropTarget (such as regular files that do not accept drop operations), the object itself is still returned. In that case, shell-side drop processing will not occur (only script events will execute). While some standard scripts use if (api.DropTarget(item)) to determine whether an item accepts drops, it cannot be conclusively determined from the implementation whether non-accepting items return empty or an object (Needs Verification).
• In asynchronous scripts (ui.js, WebView2 side, etc.), await is required for each method call.

2. Methods

DragEnter, DragOver, and Drop accept the same arguments.

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

A minimum of 3 arguments (dataObj, grfKeyState, pt) is required. If insufficient arguments are provided, nothing is executed and E_INVALIDARG is returned.

The return value is S_OK (0) on success, or a negative value on failure (e.g., E_INVALIDARG = 0x80070057).

3. Properties

4. Execution Flow and Script Events

When called with bSingle set to false (or omitted), preceding stages are executed sequentially within a single call.

Normally, calling Drop(…) once is sufficient, and explicitly calling preceding stages is unnecessary (standard add-ons and sync1.js call Drop or DragOver individually). When bSingle is set to true, only the called stage is executed, and DragLeave is not automatically invoked (useful when you want to call DragEnter/DragOver/Drop sequentially by yourself, ending with DragLeave()).

Integration with Script Events

A DropTarget created with api.DropTarget(item) (with a target item) will, at each stage, first call the script events (te.OnDragEnter / te.OnDragOver / te.OnDrop) before proceeding to standard shell processing.

• Event parameters are (Ctrl, dataObj, pgrfKeyState, pt, pdwEffect), where Ctrl is caller (defaults to DropTarget itself if omitted), and pgrfKeyState and pdwEffect are Memory(DWORD) objects (in sync1.js, they are read/written via pgrfKeyState[0] and pdwEffect[0]).
• pt passed to events is always (0, 0), not the actual drop position (positional info is not passed in implementation).
• Re-entering DropTarget from within event handlers will cease to trigger events if recursion becomes too deep (internally limited to fewer than 10 nested levels).

5. Constants

Defined in 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 (Value returned by Type)

6. Examples

// "Drop" selected files to another folder (with Ctrl key = Copy)
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);
    // Success if hr === 0 (S_OK). Actual effect applied will be stored in pdwEffect[0]
}

// Query drop effect only (without executing drop)
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);

// Delegate to default drop behavior inside an event
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);
    }
};

// Manual stage control (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();

Re-invoking its own event inside te.OnDrop may cause infinite recursion if Ctrl refers to the same item. In standard scripts, Target in api.DropTarget(Target) is limited to Ctrl.FolderItem or the result of HitTest.

Related

• FolderItem Reference
• FolderItems Reference
• FolderView (ShellBrowser) Reference
• Memory Reference
• api Reference
• te Reference