onCloseQuery

Category: Application Events

Namespace: web.events.onCloseQuery

Description

An event handler called when the user attempts to close the application window — by clicking the X button, pressing Alt+F4, or selecting Close from the taskbar context menu.

Assign a function to intercept the close request and decide whether to allow it. If no handler is assigned, the application closes immediately.

Important: You must call web.app.close() yourself when you are ready to close. If you never call it, the window cannot be closed.

Syntax

web.events.onCloseQuery = function() {
    // Your close logic here
    // Call web.app.close() when ready to close
};

Parameters

This event handler receives no parameters.

Returns

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

Examples

Allow close immediately

// Simplest usage — just close the app
web.events.onCloseQuery = function() {
    web.app.close();
};

Prompt for unsaved changes

let hasUnsavedChanges = false;

web.events.onCloseQuery = function() {
    if (hasUnsavedChanges) {
        const confirmed = confirm('You have unsaved changes. Close anyway?');
        if (confirmed) {
            web.app.close();
        }
        // If not confirmed, do nothing — the window stays open
    } else {
        web.app.close();
    }
};

Save before closing

web.events.onCloseQuery = async function() {
    // Auto-save on close
    const appDir = await web.directory.getAppDir();
    const filePath = appDir + '\\autosave.txt';

    try {
        await web.files.writeTextFile({ filePath, contents: editorContent });
    } catch (_) {
        // Save failed — ask user what to do
        const proceed = confirm('Auto-save failed. Close without saving?');
        if (!proceed) return;
    }

    web.app.close();
};

Save window position before closing

web.events.onCloseQuery = async function() {
    // Persist window geometry before exit
    // BEGINNER NOTE: web.window.getSize() returns the current width and height
    const size = await web.window.getSize();

    // BEGINNER NOTE: web.variables.setVar() stores a named value in memory
    await web.variables.setVar('windowWidth',  String(size.width));
    await web.variables.setVar('windowHeight', String(size.height));

    // BEGINNER NOTE: web.variables.saveVariables() writes variables to disk
    await web.variables.saveVariables();

    web.app.close();
};

Use Cases

• Warn the user about unsaved changes before exit
• Auto-save application state or user data on close
• Save window size and position for the next session
• Run cleanup tasks (clear temp files, release resources)
• Confirm exit for critical or long-running applications

Notes

• Assign the handler once at startup, inside a DOMContentLoaded listener
• You must call web.app.close() to complete the close — the handler intercepts the request but does not close the window automatically
• If web.events.onCloseQuery is null or not a function, the application closes immediately without calling your code
• The handler can be async — await works correctly inside it
• To cancel a close, simply return from the handler without calling web.app.close()
• This event fires for all close triggers: the title bar X button, Alt+F4, the taskbar right-click menu, and programmatic calls to close the window from outside the app
• It does not fire when web.app.close() is called from your own JavaScript — that closes directly

How It Works

Unlike other web.* API calls that send messages from JavaScript to the Windows app, onCloseQuery works in reverse. When the user attempts to close the window, the Windows application sends a message to the JavaScript layer. The bridge intercepts this message and calls your handler:

User clicks X  →  Window intercepts  →  Sends message to JS  →  Your handler runs
                                                                        ↓
                                                               web.app.close()
                                                                        ↓
                                                               Window closes

This design gives your JavaScript code full control over whether and when the application exits.