onFileDrop

Category: Events

Namespace: web.events.onFileDrop

Description

Fires when the user drags one or more files from Windows Explorer and drops them onto the application window. The callback receives a JavaScript array of full file paths.

This is the recommended way to implement drag-and-drop file opening in WebExeBuilder apps. It works seamlessly with any file type and does not require any HTML/CSS drag event handling.

Project Setting Required: AllowExternalDrop must be set to False in the Builder project settings for onFileDrop to fire. When set to True (the default), WebView2 handles drops internally — navigable files (HTML, etc.) cause the browser to navigate to them, and non-navigable files (images, PDFs, etc.) open in the Windows default application via ShellExecute. In both cases, onFileDrop is never called.

Syntax

web.events.onFileDrop = function(paths) {
    // paths is a JS array of full file path strings
};

Parameters

The callback receives one argument:

• paths string[] — Array of full Windows file paths that were dropped (e.g. ["C:\\Users\\Alice\\photo.jpg"]). Always an array, even when a single file is dropped.

Returns

Nothing. This is an event handler assignment, not a function call.

Examples

Basic usage — log dropped file paths

document.addEventListener('DOMContentLoaded', () => {
    web.events.onFileDrop = function(paths) {
        console.log('Files dropped:', paths.length);
        paths.forEach(p => console.log(' -', p));
    };
});

Image viewer — open dropped images

const IMG_EXTS = ['.jpg', '.jpeg', '.png', '.gif', '.bmp', '.webp', '.svg'];

document.addEventListener('DOMContentLoaded', () => {
    web.events.onFileDrop = async function(paths) {
        // Filter to supported image types
        const imagePaths = paths.filter(p => {
            const ext = p.substring(p.lastIndexOf('.')).toLowerCase();
            return IMG_EXTS.includes(ext);
        });

        if (imagePaths.length === 0) {
            alert('No supported image files were dropped.');
            return;
        }

        // Load the first dropped image
        const base64 = await web.files.readFileAsBase64({ filePath: imagePaths[0] });
        document.getElementById('preview').src = `data:image/jpeg;base64,${base64}`;
    };
});

Text editor — open dropped text file

document.addEventListener('DOMContentLoaded', () => {
    web.events.onFileDrop = async function(paths) {
        // Only handle the first dropped file
        const filePath = paths[0];

        // Check extension
        const ext = filePath.substring(filePath.lastIndexOf('.')).toLowerCase();
        if (!['.txt', '.md', '.js', '.html', '.css'].includes(ext)) {
            alert('Please drop a text file.');
            return;
        }

        const text = await web.files.readTextFile({ filePath });
        document.getElementById('editor').value = text;
        await web.window.setTitle({ title: filePath.substring(filePath.lastIndexOf('\\') + 1) });
    };
});

Accept any file — show file details

document.addEventListener('DOMContentLoaded', () => {
    web.events.onFileDrop = async function(paths) {
        const list = document.getElementById('file-list');
        list.innerHTML = '';

        for (const filePath of paths) {
            const name = filePath.substring(filePath.lastIndexOf('\\') + 1);
            const size = await web.files.fileSize({ filePath });
            const kb   = (size / 1024).toFixed(1);

            const li = document.createElement('li');
            li.textContent = `${name} (${kb} KB)`;
            list.appendChild(li);
        }
    };
});

Project Settings

The Allow External Drop toggle controls how Windows Explorer drag-drops are handled:

Set it to False in the Builder GUI when you want your app to handle dropped files via web.events.onFileDrop.

Use Cases

• Drag-and-drop file opening (images, text, PDFs, etc.)
• Batch file processing — accept multiple files in one drag
• Quick file import into a notes/editor app
• Media players / galleries that accept dropped media
• Any app where "open file" should feel instant and natural

Notes

• paths is always a JavaScript array, even when only one file is dropped
• Full absolute Windows paths are provided (e.g. C:\Users\Alice\Documents\file.txt)
• Backslashes in paths are literal — use path.lastIndexOf('\\') to parse them in JS
• The callback fires on the main JS thread — you can use await inside an async wrapper
• Register the handler inside DOMContentLoaded or at script load time — before any drop can happen
• Multiple files dragged at once → all paths arrive in a single callback call as one array
• Does not fire for folders — only files
• Works with web.files.readFileAsBase64, web.files.readTextFile, and all other file APIs