win_drag_source #

English · 简体中文

Windows-only Flutter package for native OLE drag-and-drop. Wraps any widget into a drag source with a custom ghost image (no system ghost), supporting both CF_HDROP (file) and CF_UNICODETEXT (text / encrypted payload) modes.

⚠️ Windows-only. On macOS / Linux / Web the wrapper degrades to a plain Listener and never initiates a drag.

Features #

• ✅ Pure Dart FFI — no native code to compile, no plugin registry headache
• ✅ Custom ghost image via RepaintBoundary — exclude badges, frames, captions from the drag preview via imageKey
• ✅ Two payload modes: file path or arbitrary text (typically encrypted)
• ✅ Tap / double-tap semantics with Windows-native 500 ms interval
• ✅ Zero runtime dependencies beyond ffi and win32

Installation #

dependencies:
  win_drag_source: ^0.0.1

Then:

flutter pub get

Quick start #

1. File drag (CF_HDROP) #

The simplest case — drag a real file into Explorer, 3ds Max, SketchUp, chat apps, anything that accepts files:

import 'package:win_drag_source/win_drag_source.dart';

DragSource(
  payload: FilePayload('C:\\path\\to\\file.max'),
  onDropComplete: (accepted) {
    debugPrint('drop ${accepted ? 'accepted' : 'rejected'}');
  },
  child: YourCard(),
)

2. Async payload (DB lookup, decryption, …) #

When the payload needs I/O before the drag can start, use payloadProvider:

DragSource(
  payloadProvider: () async {
    final path = await lookupFilePath(itemId);
    if (path == null) return null;
    return FilePayload(path);
  },
  onDropComplete: (ok) => ...,
  child: YourCard(),
)

If payloadProvider returns null, the drag is silently aborted. The pointer must remain pressed while it resolves; releasing it first also cancels the drag. The asynchronous work itself does not block the UI.

3. Encrypted payload (CF_UNICODETEXT) #

For dragging to a target that knows how to decrypt the payload (e.g. your own renderer / IDE plugin):

DragSource(
  payload: TextPayload(encrypt(yourJson)),
  onDropComplete: (ok) => ...,
  child: YourCard(),
)

The package does not ship an encryption helper — bring your own (package:pointycastle, package:cryptography, …). The package's only job is to deliver the bytes to the OLE drop target.

💡 Plain-text targets (Notepad, chat apps) will also receive the encrypted string and display it as opaque text. Only targets that know your format can decode it.

Custom ghost image #

By default the whole child is rasterized as the drag preview. To drag only the cover image (excluding badges, frames, captions), wrap it in a RepaintBoundary with a GlobalKey and pass the key as imageKey:

final _coverKey = GlobalKey();

@override
Widget build(BuildContext context) {
  return DragSource(
    payload: FilePayload(path),
    imageKey: _coverKey,        // ← rasterize this subtree, not the whole card
    onDropComplete: (ok) => ...,
    child: Stack(
      children: [
        RepaintBoundary(
          key: _coverKey,
          child: Image.file(File(path)),
        ),
        Positioned(right: 8, bottom: 8, child: Badge()),  // excluded from ghost
      ],
    ),
  );
}

API reference #

DragSource #

DragPayload #

DragDrop (low-level FFI) #

Rarely needed directly — exposed for advanced cases (custom ghost-image pipelines, etc.). Public surface:

How it works #

pointer down ──► move > 4 px ──► resolve payload
                                   │
                                   ▼
                          rasterize RepaintBoundary
                                   │
                                   ▼
                       create Win32 layered window
                                   │
                                   ▼
              DoDragDrop (blocking, runs its own modal loop)
                                   │
                                   ▼
                            destroy window
                                   │
                                   ▼
                          fire onDropComplete

The package does not hide your application window during drag. If you need that behavior (e.g. to drop on a window behind your app), call window_manager's hide() / show() yourself around the drag.

Caveats #

• Windows-only. On other platforms DragSource is a no-op.
• Main-thread blocking. DoDragDrop blocks the UI thread by design while its modal message loop runs. payloadProvider may perform async I/O; keep it quick enough that the user can hold the pointer until it resolves.
• pixelRatio: 1.0. Ghost images are rasterized at device pixel ratio 1.0. On high-DPI displays this may look slightly soft; if you need a crisper image, fork and adjust.

Compatibility #

The package requires Flutter 3.32 or later, Dart 3.8 or later, and Windows. It uses OLE initialization internally, so applications do not need to set up COM before using DragSource. A process that has explicitly initialized the UI thread with an incompatible COM apartment model cannot start an OLE drag.

License #

MIT — see LICENSE.