setStyle

Category: Style Management

Namespace: web.styles.setStyle

Description

Sets the active VCL style by name. Important: This restarts the application to apply the new style. The current URL is preserved and restored after restart.

Syntax

const result = await web.styles.setStyle('Windows10');

Parameters

• styleName (required) - Name of the style to activate (case-insensitive). Must match a style name returned by listStyles().

Returns

Promise<string> - Returns a promise that resolves with the style name if successful, empty string if failed

Examples

Simple example

const result = await web.styles.setStyle('Glow');

if (result) {
    console.log('Style changed to:', result);
    // Application will restart automatically
} else {
    console.log('Failed to change style');
}

Persist style preference (recommended)

// Best practice: save the preference BEFORE calling setStyle,
// because setStyle restarts the app immediately.
// Write vcltheme.txt so the app loads the correct style on next startup.

async function changeAndPersistStyle(styleName) {
    // Save to storage for your app's own reference
    await web.storage.set({ key: 'vclTheme', value: styleName });

    // Write vcltheme.txt so the Delphi runtime loads this style on startup
    const storageDir = await web.storage.getDir();
    await web.files.writeTextFile({
        filePath: storageDir + 'vcltheme.txt',
        contents: styleName
    });

    // Now apply — this restarts the app
    await web.styles.setStyle(styleName);
}

await changeAndPersistStyle('MIDNIGHT EXPRESS GREEN');

Style selector with validation

async function changeStyle(styleName) {
    // Get list of available styles first
    const styles = await web.styles.listStyles();

    // Check if style exists (case-insensitive)
    const match = styles.find(s => s.toUpperCase() === styleName.toUpperCase());
    if (!match) {
        console.error('Style not available:', styleName);
        return false;
    }

    // Persist and apply
    const storageDir = await web.storage.getDir();
    await web.files.writeTextFile({
        filePath: storageDir + 'vcltheme.txt',
        contents: match
    });
    const result = await web.styles.setStyle(match);
    return result !== '';
}

await changeStyle('Windows10');

Minimize before changing (avoid white flash)

// Minimize the window before changing style to avoid a brief white flash
await web.window.setState({ state: 'minimized' });
await new Promise(resolve => setTimeout(resolve, 200));

const storageDir = await web.storage.getDir();
await web.files.writeTextFile({
    filePath: storageDir + 'vcltheme.txt',
    contents: 'MaterialOxfordBlue'
});
await web.styles.setStyle('MaterialOxfordBlue');

Style Persistence

When setStyle() is called, the application restarts with --STYLE parameters. On subsequent normal launches (without --STYLE), the runtime checks for a vcltheme.txt file in the application's storage directory:

%LOCALAPPDATA%\ezWareLab\WebExeBuilder\{APP-GUID}\storage\vcltheme.txt

If this file exists and contains a valid style name, that style is loaded instead of the project's default style. This eliminates the need for a restart loop on startup.

Recommended pattern:

1. Write vcltheme.txt with the chosen style name
2. Call web.styles.setStyle() to apply immediately (triggers restart)
3. On next launch, the runtime reads vcltheme.txt and loads the correct style directly

If vcltheme.txt does not exist or contains an invalid style name, the project's default style (configured in WebExeBuilder) is used as a fallback.

Use Cases

• Allow users to change application theme
• Switch between light and dark themes
• Apply user's saved style preference on startup
• Implement theme selection in settings
• Change appearance based on time of day

Notes

• IMPORTANT: Application automatically restarts to apply the new style
• Current URL is preserved and restored after restart
• Style name is case-insensitive (converted to uppercase internally)
• Returns empty string if style doesn't exist or can't be loaded
• Only styles embedded in the application at compile time can be used (see listStyles())
• The restart happens immediately after successful style change
• Always persist the style choice to vcltheme.txt before calling setStyle() to avoid double-restart issues on next launch
• Style names returned by listStyles() are resource names (typically uppercase, may contain underscores)
• getStyle() returns the internal VCL style name which may differ in casing/spacing from the resource name