notification

Category: System Integration

Namespace: web.system.notification

Description

Displays a native Windows system tray notification (toast notification). Users can click on the notification to trigger custom actions in your application.

Syntax

const success = await web.system.notification({
    name: 'update-available',
    title: 'Update Available',
    message: 'Version 2.0 is ready to install'
});

Parameters

• name (required) - Unique identifier for the notification (used in click event handling)
• title (required) - Notification title text
• message (optional) - Notification body/message text (parameter name is message in JavaScript, body in Delphi)

Returns

Promise<boolean> - Returns a promise that resolves with true if the notification was displayed successfully, false otherwise

Examples

Simple example

const success = await web.system.notification({
    name: 'hello',
    title: 'Hello!',
    message: 'Welcome to the application'
});

if (success) {
    console.log('Notification displayed');
}

Download complete notification

// Notify user when download completes
const result = await web.files.downloadFromUrl({
    url: 'https://example.com/file.zip',
    filePath: 'C:\\Downloads\\file.zip',
    overwrite: true
});

if (result.success) {
    await web.system.notification({
        name: 'download-complete',
        title: 'Download Complete',
        message: 'file.zip has been downloaded successfully'
    });
}

Handle notification clicks

// Set up click event handler
web.events.onNotificationClick = function(notificationName) {
    console.log('Notification clicked:', notificationName);
    
    if (notificationName === 'update-available') {
        // Show update dialog
        showUpdateDialog();
    } else if (notificationName === 'download-complete') {
        // Open downloads folder
        web.shell.showInExplorer({ 
            filePath: 'C:\\Downloads' 
        });
    }
};

// Show notification
await web.system.notification({
    name: 'update-available',
    title: 'Update Ready',
    message: 'Click to install version 2.0'
});

Progress notification

// Show progress notifications
async function processFiles(files) {
    for (let i = 0; i < files.length; i++) {
        await processFile(files[i]);
        
        await web.system.notification({
            name: 'progress',
            title: 'Processing Files',
            message: `Completed ${i + 1} of ${files.length}`
        });
    }
}

Use Cases

• Notify users of completed background tasks
• Alert users to important events or updates
• Show download/upload completion messages
• Display system status changes
• Provide non-intrusive user notifications
• Implement clickable notifications for user actions

Notes

• Uses native Windows system tray notifications (Shell_NotifyIcon)
• Notifications appear in the Windows Action Center
• Works on Windows 10 and Windows 11
• Non-blocking - doesn't interrupt application flow
• The name parameter is used to identify which notification was clicked
• Set web.events.onNotificationClick to handle notification clicks
• Both name and title are required parameters
• Returns false if notification system is unavailable
• Note: JavaScript parameter is message, but Delphi backend expects body (both work due to parameter mapping)