Settings dialog¶
Settings in a modal HTML dialog, saved to JSON: colour scheme, text size and reduced motion.
Same example in Python: Settings dialog

Real capture on KDE Plasma 6.6 Wayland with the released packages.
What it teaches: Show-NativeHTMLKitHtmlDialog; popovers; Set-NativeHTMLKitEnvironment; replaceable stylesheet.
Run it¶
pwsh -File 09-settings-dialog.ps1 [-SettingsPath FILE]
Related guide: dialogs and popovers
Source: 09-settings-dialog.ps1¶
# 09-settings-dialog.ps1 - a settings dialog that applies and remembers preferences.
#
# Teaches: an HTML <dialog> opened modally with Show-NativeHTMLKitHtmlDialog and closed with
# a return value, a popover help tip
# (Show-NativeHTMLKitPopover), reading a form inside the dialog, applying a colour scheme
# with Set-NativeHTMLKitEnvironment, replacing one stylesheet in place
# (Add-/Set-NativeHTMLKitStylesheet), and saving settings as JSON.
#
# Run: pwsh -File ./09-settings-dialog.ps1 [-SettingsPath settings.json]
# powershell.exe -NoProfile -File .\09-settings-dialog.ps1
# Default settings file: <ApplicationData>/NativeHTMLKit-Examples/settings.json.
# -SelfTest uses a temporary settings file, changes settings and quits.
param([string]$SettingsPath, [switch]$SelfTest)
$ErrorActionPreference = 'Stop'
Import-Module NativeHTMLKit
$app = Start-NativeHTMLKitScript -Name 'Settings dialog'
try {
if ($SelfTest) { $SettingsPath = Join-Path ([IO.Path]::GetTempPath()) ('nhk-settings-' + [guid]::NewGuid().ToString('N') + '.json') }
if (-not $SettingsPath) {
$SettingsPath = Join-Path (Join-Path ([Environment]::GetFolderPath([Environment+SpecialFolder]::ApplicationData, [Environment+SpecialFolderOption]::Create)) 'NativeHTMLKit-Examples') 'settings.json'
}
$window = New-NativeHTMLKitWindow -Application $app -Title 'Settings dialog' -Width 640 -Height 480
$doc = Open-NativeHTMLKitHtml -Window $window -Html @'
<!doctype html>
<html><head><style>
:root { color-scheme: light dark; }
body { font-family: system-ui, sans-serif; margin: 24px; background: Canvas; color: CanvasText; }
@media (prefers-color-scheme: dark) { body { background: #1d222b; color: #e7ebf3; } }
dialog { padding: 20px 24px; border-radius: 10px; min-width: 320px; }
dialog label { display: block; margin: 10px 0 4px; }
.actions { display: flex; justify-content: flex-end; gap: 8px; margin-top: 18px; }
#help-tip { max-width: 260px; padding: 10px; font-size: 13px; }
#saved { color: #2e7d32; }
</style></head>
<body>
<h1>Report viewer</h1>
<p id="sample">This paragraph follows the chosen text size.</p>
<p><button id="open-settings">Settings...</button> <span id="saved" role="status"></span></p>
<dialog id="settings" aria-labelledby="settings-title">
<h2 id="settings-title">Settings</h2>
<form id="settings-form">
<label for="theme">Colour scheme <button type="button" id="help" aria-label="Help">?</button></label>
<select id="theme" name="theme"><option value="system">Follow the system</option><option value="light">Light</option><option value="dark">Dark</option></select>
<label for="size">Text size (px)</label>
<input id="size" name="size" type="number" min="11" max="24" required>
<label><input type="checkbox" id="motion" name="motion" value="reduce"> Reduce motion</label>
<div class="actions"><button type="button" id="cancel">Cancel</button><button type="submit" id="apply">Save</button></div>
</form>
</dialog>
<div id="help-tip" popover>"Follow the system" uses the desktop colour preference when the host can observe it.</div>
</body></html>
'@
$defaults = @{ theme = 'system'; size = 15; motion = $false }
function Read-Settings {
$settings = $defaults.Clone()
if (Test-Path -LiteralPath $SettingsPath) {
try {
$saved = Get-Content -LiteralPath $SettingsPath -Raw | ConvertFrom-Json
foreach ($name in @('theme', 'size', 'motion')) {
if ($null -ne $saved.PSObject.Properties[$name]) { $settings[$name] = $saved.$name }
}
} catch { Write-Verbose "Ignoring unreadable settings: $($_.Exception.Message)" }
}
return $settings
}
$script:settings = Read-Settings
$script:sizeSheet = (Add-NativeHTMLKitStylesheet -Document $doc -Css '').sheet
function Set-Appearance([hashtable]$Settings) {
# 'system' removes the app override so the observed desktop preference applies again.
$motion = 'system'
if ($Settings.motion) { $motion = 'reduce' }
$null = Set-NativeHTMLKitEnvironment -Document $doc -ColorScheme $Settings.theme -ReducedMotion $motion
# Replace one app stylesheet in place instead of adding a new one each time.
$null = Set-NativeHTMLKitStylesheet -Document $doc -Sheet $script:sizeSheet -Css ('body { font-size: ' + [int]$Settings.size + 'px; }')
}
function Show-Settings {
Set-NativeHTMLKitSelectedValues -Document $doc -Element theme -Values @([string]$script:settings.theme)
Set-NativeHTMLKitDocumentValue -Document $doc -Element size -Value ([string]$script:settings.size)
Set-NativeHTMLKitChecked -Document $doc -Element motion -Checked ([bool]$script:settings.motion)
Show-NativeHTMLKitHtmlDialog -Document $doc -Element settings # modal by default
}
function Save-Settings {
$entries = @{}
foreach ($entry in (Get-NativeHTMLKitFormData -Document $doc -Form settings-form).entries) { $entries[$entry.name] = $entry.value }
$script:settings = @{ theme = [string]$entries['theme']; size = [int]$entries['size']; motion = $entries.ContainsKey('motion') }
$folder = Split-Path -Parent $SettingsPath
if (-not (Test-Path -LiteralPath $folder)) { $null = New-Item -ItemType Directory -Path $folder }
[IO.File]::WriteAllText($SettingsPath, (ConvertTo-Json -InputObject $script:settings), (New-Object Text.UTF8Encoding($false)))
Set-Appearance $script:settings
Show-NativeHTMLKitHtmlDialog -Document $doc -Element settings -Close -ReturnValue 'saved'
# Report here, not in the dialog's close event: a <dialog> keeps its previous return
# value when the user dismisses it with Escape, so 'saved' would be reported again.
Set-NativeHTMLKitDocumentText -Document $doc -Element saved -Text ('Settings saved to ' + $SettingsPath)
}
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type click -Element open-settings -Callback { Show-Settings }
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type click -Element cancel -Callback {
Show-NativeHTMLKitHtmlDialog -Document $doc -Element settings -Close -ReturnValue 'cancelled'
Set-NativeHTMLKitDocumentText -Document $doc -Element saved -Text 'Settings unchanged.'
}
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type click -Element help -Callback { $null = Show-NativeHTMLKitPopover -Document $doc -Element help-tip -Action toggle }
# Native validation (min/max/required) runs before this submit event is dispatched.
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type submit -Element settings-form -Callback { Save-Settings }
Set-Appearance $script:settings
Set-NativeHTMLKitReady -Application $app
if ($SelfTest) {
function Wait-Events { for ($i = 0; $i -lt 10; $i++) { $null = Wait-NativeHTMLKit -Application $app -TimeoutMilliseconds 30 } }
Show-Settings
if (-not (Invoke-NativeHTMLKitDocumentCommand -Document $doc -Operation get_dialog -Parameters @{ element = 'settings' }).open) { throw 'dialog did not open' }
Set-NativeHTMLKitSelectedValues -Document $doc -Element theme -Values @('dark')
Set-NativeHTMLKitDocumentValue -Document $doc -Element size -Value '40'
if ((Submit-NativeHTMLKitForm -Document $doc -Form settings-form).submitted) { throw 'size 40 is above max=24 and must not submit' }
Set-NativeHTMLKitDocumentValue -Document $doc -Element size -Value '18'
Set-NativeHTMLKitChecked -Document $doc -Element motion -Checked $true
$null = Submit-NativeHTMLKitForm -Document $doc -Form settings-form
Wait-Events
$environment = Get-NativeHTMLKitEnvironment -Document $doc
if ($environment.color_scheme -ne 'dark' -or $environment.reduced_motion -ne 'reduce') { throw "environment not applied: $($environment.color_scheme) $($environment.reduced_motion)" }
$size = (Get-NativeHTMLKitComputedStyle -Document $doc -Element sample -Properties @('font-size')).properties.'font-size'.value
if ($size -ne '18px') { throw "font size not applied: $size" }
if ((Get-Content -LiteralPath $SettingsPath -Raw | ConvertFrom-Json).size -ne 18) { throw 'settings not saved' }
if (-not (Get-NativeHTMLKitDocumentText -Document $doc -Element saved).StartsWith('Settings saved')) { throw 'save not reported' }
$dialog = Invoke-NativeHTMLKitDocumentCommand -Document $doc -Operation get_dialog -Parameters @{ element = 'settings' }
if ($dialog.open -or $dialog.return_value -ne 'saved') { throw 'dialog not closed with its return value' }
if (-not (Show-NativeHTMLKitPopover -Document $doc -Element help-tip -Action toggle)) { throw 'popover did not open' }
Remove-Item -LiteralPath $SettingsPath -Force
[Console]::Out.WriteLine('SELFTEST PASS 09-settings-dialog')
$null = Request-NativeHTMLKitQuit -Application $app
}
Wait-NativeHTMLKit -Application $app -UntilShutdown
} finally {
Close-NativeHTMLKit -Application $app
}