Desktop

Dragging files in and out

Receive files dropped onto a window as real paths, with several drop areas, and let users drag files out to the desktop.

Available since 0.4.1. Users expect to drop a picture onto an avatar, attach files by dragging them into a message, or drag an attachment out onto the desktop. A web page is never told where a file lives, so on its own a dropped file would be a name and some bytes. Jolt gives the path to your Java code instead. This page goes from the simplest drop to several drop areas, then to dragging files out, and ends with how Jolt keeps a page from naming files it should not touch.

1. Drop files onto the window

Register a listener with onFileDrop. It receives a FileDrop with the absolute local paths of everything that was dropped, files and folders alike:

WebWindow window = app.createWindow(WindowOptions.defaults().withTitle("Importer"));
window.onFileDrop(drop -> {                      // UI thread. Register before the page loads.
    for (Path path : drop.files()) {
        System.out.println("Dropped " + path);
    }
});
window.loadResources(AppResources.classpath("ui"));
  • The listener runs on the UI thread. For a big import, hand the paths to another thread.
  • Once onFileDrop is registered, the web view never navigates to a dropped file. Without it, dropping a PDF on the window would replace your app with the PDF.
  • The page's own drop event handlers still run, so the page can show a preview with FileReader while Java gets the path.

2. Show where the files will land

While files are dragged over the window, Jolt sets attributes you can style:

<style>
  html[data-jolt-drop-active] body { cursor: copy; }   /* files are being dragged over the window */
</style>
  • data-jolt-drop-active is on <html> for as long as a file drag is over the page.
  • data-jolt-drop-over is on the drop area under the pointer (next section).

3. Several drop areas

Mark an element with data-jolt-drop="name" and the listener learns which one the files landed on. One window can then handle an avatar, an attachment tray and an import area differently:

<div class="avatar" data-jolt-drop="avatar">Drop a picture here</div>
<div class="tray"   data-jolt-drop="attachments">Drop files to attach</div>

<style>
  [data-jolt-drop-over] { outline: 2px dashed dodgerblue; }   /* the area under the pointer */
</style>
window.onFileDrop(drop -> {
    switch (String.valueOf(drop.zone())) {
        case "avatar"      -> setAvatar(drop.files().get(0));
        case "attachments" -> addAttachments(drop.files());
        default            -> { /* dropped somewhere else on the page */ }
    }
});
FileDropMeaning
files()Absolute local paths, files or folders.
zone()The data-jolt-drop value of the element they landed on, or null outside every such element.
x(), y()Where the pointer was, in page pixels.

The window accepts a drop anywhere on the page, not only inside zones. Check zone() if drops outside your areas should be ignored.

4. Drag files out of the window

The other direction: the user drags an item from your page into the file manager, onto the desktop or into another application. The page never names a file. It puts a token, a string you made up, on a draggable element, and your Java code says which files that token stands for:

<li draggable="true" data-jolt-drag-file="attachment:42">report.pdf</li>
window.setFileDragSource(token -> token.startsWith("attachment:")
        ? List.of(store.fileOf(token.substring("attachment:".length())))   // absolute paths of files that exist
        : null);                                                           // null or empty refuses the drag
  • You decide. A page can only hand over a token, so it cannot drag out an arbitrary file of the user's disk.
  • The target can only copy. Dropping on a folder makes a copy and never moves or deletes your original.
  • It is asked the moment the drag starts, on the UI thread. Write a file that does not exist yet before the user can start dragging it, or write it inside filesFor if it is small.
  • At most 4096 files per drag. A path that does not exist cancels the drag.

5. Clean up after a drag

An export you wrote to a temporary file should not stay behind. Implement FileDragSource as a class to also hear how the drag ended:

window.setFileDragSource(new FileDragSource() {
    @Override public List<Path> filesFor(String token) {
        return List.of(exportToTemp(token));                 // write the file now
    }
    @Override public void finished(String token, boolean dropped) {
        deleteTemp(token);                                   // dropped: a copy was made. false: cancelled or no target.
    }
});

dropped is true when a target accepted the files and made a copy, and false when the user cancelled or let go over something that takes no files.

6. Why a page cannot make up a file

The path of a dropped file is sensitive, and the page is the one sending the message, so Jolt does not trust it:

  • The platform supplies the paths. On Windows, WebView2 attaches the dropped File objects to the page's message, and Jolt reads their paths from there. On Linux, WebKitGTK reports the drag to the window itself. The page only adds the names and the zone.
  • Names must match. A message whose names do not match the platform's files is ignored, so a page cannot claim "the user dropped C:\Users\me\secrets.txt".
  • Paths must be absolute and local. A network path such as \\server\share is refused, because opening it would send the user's credentials to that server.
  • Drag-out goes through your token check. Nothing leaves the window unless filesFor returns it.
  • As with every bridge feature, only pages the SecurityPolicy trusts get these.
  • Windows uses the shell's own drag loop and data object, the same thing Explorer offers for the same files. Dropping in needs a current WebView2 Runtime, one that supports postMessageWithAdditionalObjects.
  • Linux offers a text/uri-list through GTK when dragging out.