class EE::Window::DragAndDrop

Overview

Native cross-application file dragging. More…

#include <draganddrop.hpp>

class DragAndDrop {
public:
    // methods

    static DragAndDrop forWindow(Window& window);
    static bool encodeFileUriList(const DragOffer& offer, std::string& output, std::string* error = nullptr);
    DragCapabilities getCapabilities() const;
    DragStartResult startDrag(const DragOffer& offer, DragCompletionCallback completion = {});
    void cancelDrag();
    bool isDragging() const;
    bool setDataDropHandler(std::vector<std::string> mimeTypes, DataDropCallback callback);
    bool setFileSaveDropHandler(FileSaveDropCallback callback);
};

Detailed Documentation

Native cross-application file dragging. All methods must run on the window/UI thread. This lightweight facade borrows its Window and must not outlive it. A started session owns its serialized payload and completion callback. Rejected starts never invoke completion. Completions run once, outside native event hooks, when input is updated; they may start another drag. Cancellation/closing a source window also completes the session. Callbacks must not borrow objects that may be destroyed before completion (use weak ownership when appropriate). Engine teardown cancels and releases pending sessions without invoking their callbacks. Initially only Copy is supported. Dropped means the native transfer finished, not that a browser uploaded or a file manager copied a file. Existing internal UI dragging is independent.

Methods

static bool encodeFileUriList(const DragOffer& offer, std::string& output, std::string* error = nullptr)

Serialize an offer as text/uri-list (CRLF). Rejects empty, relative, invalid UTF-8 and NUL paths. Preserves order and duplicate entries. On failure output is empty.

DragStartResult startDrag(const DragOffer& offer, DragCompletionCallback completion = {})

Call after a movement threshold, while the initiating left mouse button is still down. Preview images must be RGB/RGBA, at most 2048 pixels per side and 1,048,576 pixels total. The offer is read synchronously; the session retains only its own native representation.

bool setDataDropHandler(std::vector<std::string> mimeTypes, DataDropCallback callback)

Receive drags from other applications that offer one of mimeTypes and no file list (text/uri-list), such as an archive manager’s extraction protocol. Drags with a file list keep arriving as FileDropped events. The callback runs on the UI thread, outside native event hooks, after the source was told the drop succeeded. Replaces this window’s previous handler; an empty list removes it. Returns false where unsupported (see dataTarget).

bool setFileSaveDropHandler(FileSaveDropCallback callback)

Receive drags from other applications whose source saves the file where it is dropped (XDS). These take priority over a file list offered with them, which such sources only fill with temporary copies, if at all. The callback runs on the UI thread, outside native event hooks, when the drag is dropped; the source then saves into the returned folder. Replaces this window’s previous handler; an empty callback removes it. Returns false where unsupported (see dataTarget).