message

Category: Dialog Operations

Namespace: web.dialogs.message

Description

Display a native Windows Task Dialog — a modern, configurable modal dialog that supports an instruction heading, body text, icon, preset or custom buttons, a verification checkbox, a footer, and clickable hyperlinks. Returns an object describing which button was clicked and whether the checkbox was checked.

All text fields support <a href="..."> hyperlinks — clicking them opens the URL in the system default browser.

Syntax

const result = await web.dialogs.message({
    title:         string,   // window title bar
    heading:       string,   // large bold instruction text
    content:       string,   // smaller body text
    icon:          string,   // 'info' | 'warning' | 'error' | 'shield' | 'none'
    buttons:       string,   // preset button group (see below)
    defaultButton: string,   // which button is pre-selected
    checkbox:      string,   // verification checkbox label (omit = no checkbox)
    footer:        string,   // footer text (supports hyperlinks)
    customButtons: array     // custom button definitions (overrides buttons)
});

Parameters

buttons presets

customButtons array

customButtons: [
    { id: 1, text: 'Save and Close', default: true },
    { id: 2, text: 'Discard Changes' },
    { id: 3, text: 'Cancel' }
]

• id — integer returned in result.button when this button is clicked
• text — button label
• default — (optional) true = pre-selected button

Returns

Promise<{ button: string|number, checked: boolean }>

If the user closes the dialog with Escape or the X button, button will be "cancel".

Examples

Simple alert

await web.dialogs.message({
    heading: 'File Saved',
    content: 'Your document has been saved successfully.',
    icon: 'info'
});

Confirm before delete

const result = await web.dialogs.message({
    title:         'Confirm Delete',
    heading:       'Delete this file?',
    content:       'This action cannot be undone.',
    icon:          'warning',
    buttons:       'yesno',
    defaultButton: 'no'
});

if (result.button === 'yes') {
    await deleteFile();
}

Verification checkbox ("don't ask again")

const result = await web.dialogs.message({
    heading:  'Overwrite existing file?',
    icon:     'warning',
    buttons:  'yesno',
    checkbox: "Don't ask again"
});

if (result.checked) {
    await web.variables.setVar('skipOverwriteWarning', 'true');
    await web.variables.saveVariables('prefs.json');
}

if (result.button === 'yes') {
    await saveFile();
}

Custom buttons

const result = await web.dialogs.message({
    heading: 'Unsaved Changes',
    content: 'You have unsaved changes. What would you like to do?',
    icon:    'warning',
    customButtons: [
        { id: 1, text: 'Save and Close', default: true },
        { id: 2, text: 'Discard Changes' },
        { id: 3, text: 'Cancel' }
    ]
});

if (result.button === 1) await saveAndClose();
else if (result.button === 2) discardAndClose();
// result.button === 3 → do nothing

Hyperlinks in content and footer

await web.dialogs.message({
    heading: 'Update Available',
    content: 'Version 2.0 is ready to install. <a href="https://example.com/changelog">View changelog</a>',
    footer:  'Visit <a href="https://example.com/support">example.com/support</a> for help.',
    icon:    'info',
    buttons: 'okcancel'
});

Use Cases

• Replace alert() with a native-looking dialog
• Confirm destructive actions (delete, overwrite, close without saving)
• Present multi-choice decisions with clear button labels
• Collect a "don't ask again" preference alongside a decision
• Show informational messages with links to documentation or support

Notes

• Hyperlinks are always enabled — <a href="url">text</a> in any text field opens the URL in the default browser. Plain text renders identically whether or not links are present.
• Only <a href> tags are recognised. Other HTML tags appear as literal text.
• customButtons overrides buttons and defaultButton entirely. Use one or the other.
• The dialog is modal — it blocks the app window until dismissed.
• Closing with Escape or the title bar X returns { button: "cancel", checked: false }.

Related Methods

• web.dialogs.openFile() — native Windows file open dialog
• web.dialogs.saveFile() — native Windows file save dialog
• web.dialogs.selectFolder() — native Windows folder picker