Focus timer¶
A countdown timer that asks before quitting while it runs.
Same example in Python: Focus timer

Real capture on KDE Plasma 6.6 Wayland with the released packages.
What it teaches: Set-NativeHTMLKitBeforeQuit; saving after shutdown; desktop.paths; Request-NativeHTMLKitAttention.
Run it¶
pwsh -File 17-focus-timer.ps1
Related guide: lifecycle
Source: 17-focus-timer.ps1¶
# 17-focus-timer.ps1 - application lifecycle, quit confirmation and saving state on shutdown.
#
# Teaches: a quit policy (Set-NativeHTMLKitBeforeQuit) that vetoes a quit while the timer runs
# and asks with an HTML <dialog>; saving statistics after Wait-NativeHTMLKit -UntilShutdown
# returns (the host has shut down, so no more cmdlet calls that talk to it); per-application
# folders from the host (Invoke-NativeHTMLKitRpc desktop.paths); Request-NativeHTMLKitAttention
# where the platform supports it and Set-NativeHTMLKitWindow -Title; a ticking timer built from a
# background task that stops with the application.
#
# Run: pwsh -File ./17-focus-timer.ps1 [-StatsPath stats.json]
# powershell.exe -NoProfile -File .\17-focus-timer.ps1
# Default statistics file: <per-application state folder>/focus-timer.json.
# -SelfTest runs a one-second session, checks the quit veto and the saved file, and quits.
param([string]$StatsPath, [switch]$SelfTest)
$ErrorActionPreference = 'Stop'
Import-Module NativeHTMLKit
$app = Start-NativeHTMLKitScript -Name 'Focus timer' -AppId 'org.nativehtmlkit.examples.powershell.focus_timer'
try {
if ($SelfTest -and -not $StatsPath) { $StatsPath = Join-Path ([IO.Path]::GetTempPath()) ('nhk-focus-' + [guid]::NewGuid().ToString('N') + '.json') }
if (-not $StatsPath) {
# desktop.paths: XDG folders on Linux, AppData folders on Windows. The host does not create them.
$StatsPath = Join-Path (Invoke-NativeHTMLKitRpc -Application $app -Method 'desktop.paths').state 'focus-timer.json'
}
$window = New-NativeHTMLKitWindow -Application $app -Title 'Focus timer' -Width 420 -Height 360
$doc = Open-NativeHTMLKitHtml -Window $window -Html @'
<!doctype html>
<html><head><meta charset="utf-8"><style>
body { margin:0; font:15px sans-serif; background:#1e2233; color:#eef0f7; text-align:center; }
main { padding:28px 20px; }
#clock { font-size:64px; font-variant-numeric:tabular-nums; margin:12px 0; }
form { display:flex; gap:8px; justify-content:center; align-items:center; }
input { width:60px; padding:6px; }
button { padding:7px 14px; border:0; border-radius:6px; background:#5b7cfa; color:#fff; cursor:pointer; }
button.secondary { background:#3a4058; }
#sessions { color:#a8afc6; margin-top:14px; }
dialog { border:0; border-radius:10px; padding:20px; background:#2b3047; color:#eef0f7; }
.running #clock { color:#8ef0b6; }
</style></head>
<body id="body"><main>
<h1>Focus timer</h1>
<div id="clock">25:00</div>
<form id="controls">
<label>Minutes <input id="minutes" type="number" min="1" max="120" value="25"></label>
<button id="start" type="submit">Start</button>
<button id="pause" type="button" class="secondary">Pause</button>
<button id="reset" type="button" class="secondary">Reset</button>
</form>
<p id="sessions">Completed sessions: 0</p>
<dialog id="confirm-quit"><p>The timer is still running. Quit anyway?</p>
<button id="quit-anyway">Quit</button> <button id="keep" class="secondary">Keep running</button></dialog>
</main></body></html>
'@
function Read-Stats {
try { return @{ completed = [int](Get-Content -LiteralPath $StatsPath -Raw | ConvertFrom-Json).completed } }
catch { return @{ completed = 0 } } # missing or unreadable file
}
# Everything the callbacks change lives in this hashtable.
$timer = @{ Stats = (Read-Stats); Saved = 0; Remaining = 25 * 60.0; Deadline = $null; AllowQuit = $false; Stopped = $false }
$timer.Saved = $timer.Stats.completed
function Get-Minutes {
$value = Get-NativeHTMLKitValue -Document $doc -Element minutes
if ($value -match '^\d+$') { return [Math]::Min(120, [Math]::Max(1, [int]$value)) }
return 25
}
function Show-Clock {
$left = $timer.Remaining
if ($null -ne $timer.Deadline) { $left = [Math]::Max(0.0, ($timer.Deadline - [DateTime]::UtcNow).TotalSeconds) }
$total = [int][Math]::Round($left)
$text = '{0:D2}:{1:D2}' -f [int][Math]::Floor($total / 60), ($total % 60)
Set-NativeHTMLKitDocumentText -Document $doc -Element clock -Text $text
$title = 'Focus timer'
if ($null -ne $timer.Deadline) { $title = '{0} {1} Focus timer' -f $text, [char]0x2014 }
$null = Set-NativeHTMLKitWindow -Window $window -Title $title
}
function Start-Timer([double]$Seconds) {
$timer.Remaining = $Seconds
$timer.Deadline = [DateTime]::UtcNow.AddSeconds($Seconds)
Set-NativeHTMLKitClass -Document $doc -Element body -Name running
Show-Clock
}
function Suspend-Timer {
if ($null -eq $timer.Deadline) { return }
$timer.Remaining = [Math]::Max(0.0, ($timer.Deadline - [DateTime]::UtcNow).TotalSeconds)
$timer.Deadline = $null
Set-NativeHTMLKitClass -Document $doc -Element body -Name running -Remove
}
function Reset-Timer {
$timer.Deadline = $null
$timer.Remaining = (Get-Minutes) * 60.0
Set-NativeHTMLKitClass -Document $doc -Element body -Name running -Remove
Show-Clock
}
function Complete-Session {
$timer.Deadline = $null; $timer.Remaining = 0.0
$timer.Stats.completed++
Set-NativeHTMLKitClass -Document $doc -Element body -Name running -Remove
Set-NativeHTMLKitDocumentText -Document $doc -Element sessions -Text "Completed sessions: $($timer.Stats.completed)"
Show-Clock
try { Request-NativeHTMLKitAttention -Window $window -Kind informational }
catch [NativeHTMLKit.RpcException] { $null = $_ } # not available (headless, some compositors)
}
# A periodic tick: a background task that only sleeps; its completion callback runs on this
# runspace, updates the clock and schedules the next tick. Close-NativeHTMLKit stops it.
function Start-Tick {
$null = Start-NativeHTMLKitTask -Application $app -ScriptBlock { Start-Sleep -Milliseconds 250 } -OnCompleted {
if ($timer.Stopped) { return }
if ($null -ne $timer.Deadline) {
if ([DateTime]::UtcNow -ge $timer.Deadline) { Complete-Session } else { Show-Clock }
}
Start-Tick
}
}
# The host asks before quitting (last window closed, or Request-NativeHTMLKitQuit).
Set-NativeHTMLKitBeforeQuit -Application $app -Callback {
if ($null -ne $timer.Deadline -and -not $timer.AllowQuit) {
Show-NativeHTMLKitHtmlDialog -Document $doc -Element confirm-quit
$false
return
}
$true
}
function Confirm-Quit {
$timer.AllowQuit = $true
Show-NativeHTMLKitHtmlDialog -Document $doc -Element confirm-quit -Close -ReturnValue quit
$null = Request-NativeHTMLKitQuit -Application $app # asks the policy again, which now allows it
}
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type submit -Element controls -Callback { Start-Timer ((Get-Minutes) * 60) }
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type click -Element pause -Callback { Suspend-Timer }
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type click -Element reset -Callback { Reset-Timer }
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type click -Element quit-anyway -Callback { Confirm-Quit }
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type click -Element keep -Callback {
Show-NativeHTMLKitHtmlDialog -Document $doc -Element confirm-quit -Close -ReturnValue keep
}
Set-NativeHTMLKitDocumentText -Document $doc -Element sessions -Text "Completed sessions: $($timer.Stats.completed)"
Show-Clock
Start-Tick
Set-NativeHTMLKitReady -Application $app
if ($SelfTest) {
function Wait-For([scriptblock]$Condition) {
$clock = [Diagnostics.Stopwatch]::StartNew()
while (-not (& $Condition)) {
if ($clock.ElapsedMilliseconds -gt 20000) { throw "timed out waiting for: $Condition" }
$null = Wait-NativeHTMLKit -Application $app -TimeoutMilliseconds 50
}
}
function Test-DialogOpen { return [bool](Invoke-NativeHTMLKitDocumentCommand -Document $doc -Operation get_dialog -Parameters @{ element = 'confirm-quit' }).open }
# The form's submit starts the timer with the minutes field.
Set-NativeHTMLKitDocumentValue -Document $doc -Element minutes -Value '3'
$null = Submit-NativeHTMLKitForm -Document $doc -Form controls
Wait-For { $null -ne $timer.Deadline }
if ((Get-NativeHTMLKitWindow -Window $window).title -notmatch '^0[23]:\d\d .+ Focus timer$') { throw 'the title does not show the time' }
Suspend-Timer
if ((Get-NativeHTMLKitDocumentText -Document $doc -Element clock) -notmatch '^0[23]:\d\d$') { throw 'pause lost the time' }
Reset-Timer
if ((Get-NativeHTMLKitDocumentText -Document $doc -Element clock) -ne '03:00') { throw 'reset failed' }
# A one-second session completes through the tick.
Start-Timer 1
Wait-For { $timer.Stats.completed -eq 1 }
if ((Get-NativeHTMLKitDocumentText -Document $doc -Element sessions) -ne 'Completed sessions: 1') { throw 'session not counted' }
if ((Get-NativeHTMLKitWindow -Window $window).title -ne 'Focus timer') { throw 'title not restored' }
# While the timer runs, a quit is vetoed and the dialog asks.
Start-Timer 600
$null = Request-NativeHTMLKitQuit -Application $app
Wait-For { Test-DialogOpen }
if ($app.ShutdownRequested) { throw 'the quit was not vetoed' }
Show-NativeHTMLKitHtmlDialog -Document $doc -Element confirm-quit -Close -ReturnValue keep
Confirm-Quit
}
Wait-NativeHTMLKit -Application $app -UntilShutdown
# The host has shut down: plain PowerShell only from here on.
$timer.Stopped = $true
if ($timer.Stats.completed -ne $timer.Saved) {
$folder = Split-Path -Parent $StatsPath
if (-not (Test-Path -LiteralPath $folder)) { $null = New-Item -ItemType Directory -Path $folder }
Set-Content -LiteralPath $StatsPath -Value (ConvertTo-Json @{ completed = $timer.Stats.completed } -Compress) -Encoding UTF8
}
if ($SelfTest) {
if ((Get-Content -LiteralPath $StatsPath -Raw | ConvertFrom-Json).completed -ne 1) { throw 'statistics were not saved' }
Remove-Item -LiteralPath $StatsPath
[Console]::Out.WriteLine('SELFTEST PASS 17-focus-timer')
}
} finally {
Close-NativeHTMLKit -Application $app
}