Skip to content

notification: and onNotification: a widget's own notification, counting down on the lock screen, with buttons - #280

Open
petrzpav wants to merge 3 commits into
SimonSchubert:mainfrom
petrzpav:widget-notification
Open

petrzpav wants to merge 3 commits into
SimonSchubert:mainfrom
petrzpav:widget-notification

Conversation

@petrzpav

Copy link
Copy Markdown
Contributor

What

A widget or a face can keep a notification of its own (owl 23). notification: is a live property, like lock: and fps:: posted while it's a map, taken away while it's null, and posted again when what it says changes. onNotification runs when one of its buttons is pressed, with the button's value.

widget "tea" {
  meta { owl: 23 }
  source now = clock every 1s
  state endsAt = 0 persist
  notification: endsAt > 0 ? {title: "tea", until: endsAt, buttons: ["+1m", "stop"]} : null
  onNotification: endsAt = value == "stop" ? 0 : max(endsAt, now) + 60
  at endsAt { notify("tea", "it's ready"); endsAt = 0 }
  onTap: endsAt = now + 3 * 60
  Text { text: endsAt > now ? fmtTime(endsAt - now, "m:ss", "UTC") : "tea" }
}

The map takes title (the widget's name without it), text, until (a Unix time it counts down to) or since (one it counts up from), and up to 3 buttons, each a text or {text, value}. The clock is a chronometer Android runs, so the lock screen keeps time while the widget, off screen, doesn't redraw. On Android 16 QPR2 and later, a notification with a running clock asks to be a live update: it's at the top of the lock screen and a chip in the status bar.

Why

notify() posts a new notification each time and can't change or take one back, so nothing a widget follows can show outside home. My case is a countdown timer tile (no Linux: a clock, states and at). Once the phone is locked there's no way to see how long is left, and pausing or adding a minute means unlocking and finding the page. With this, the timer counts down on the lock screen like the Clock app's, and pause, +1m and stop work from there.

Other uses: a pomodoro or workout interval, a stopwatch (since), a parking meter, a build or download a widget already follows.

How

  • owl: notification: on widgets and faces (not apps, which only run while open), and onNotification next to onTap, with value. onNotification without notification: doesn't compile. In SINCE as "a widget's notification", since plain notification is the owl 4 action. LEVEL goes to 23, as 22 shipped in 1.3.0.
  • WidgetNotification (runtime): the map as data. What's wrong with it (an unknown field, both until and since, over 3 buttons, a button without text) goes to .errors/ like other runtime errors. Unit-tested.
  • WidgetNotifications: one notification per widget file, tagged with its name, on a new channel "Widget timers and status". The channel is default importance with no sound or vibration, so the lock screen shows it where it hides silent ones and updates make no noise. Public visibility, setOnlyAlertOnce, ongoing. Buttons are immutable broadcast PendingIntents to a not-exported receiver the engine registers, carrying the file and the button's index; the value comes from what was last shown.
  • WidgetInstance: evaluates notification: with snapshotFlow from start, whether its page shows or not. pressNotification sets the widget's clock sources to now before running onNotification, because they stand still off screen and a pause pressed on the lock screen has to count from now.
  • WidgetEngine: after each reload, notifications of widgets that are gone, not compiling, waiting for Linux or without notification: are taken away. At startup that includes those a launcher that stopped left behind.
  • Docs: a section "A notification of its own" in declarations.md (with the example above, and why to work it out from states rather than now), a row in its table, a pointer from notify in handlers.md, versions.md, and the README's level and index.
  • POST_PROMOTED_NOTIFICATIONS in the manifest (a normal permission), and one new string with de, es, in, pt and zh.

Screenshots

On a Pixel 9 Pro XL with Android 17, with my timer widget (its owl 23 version, not part of this PR):

Lock screen, runningShade, runningPausedRung: counting up

The live update's chip in the status bar while it runs:

What to look at

  • Live updates. I ask for promotion only while until or since runs a clock, which is what Android means them for: something under way and time-sensitive. A paused timer has no clock, so it's an ordinary notification, collapsed on the lock screen until expanded. If you'd rather a widget ask for it itself, or not have it at all, it's one line.
  • Public visibility. It shows in full on the lock screen even with sensitive content hidden, like a clock app's timer. The docs say so, to keep private things out of it.
  • The ring stays the widget's own notify(...) from an at; this notification makes no sound. The countdown is Android's and runs without the launcher. The at, the ring and the buttons need the launcher's process, which as home it nearly always has; the docs already say an at can run a little late while the phone sleeps. If it does, the chronometer runs past zero until it fires.
  • Tapping the notification opens home, as notify's do. Opening the widget's screen would suit a timer better; I left it out to keep this small.

Testing

On a Pixel 9 Pro XL with Android 17, as the side-by-side debug copy (an applicationIdSuffix from a Gradle init script, not in the branch), with the timer widget on its home:

  • ./gradlew :owl:test :app:testDebugUnitTest :owl:owlJar and ./gradlew :app:assembleDebug :app:lintDebug pass. New tests: LangTest.aWidgetHasANotificationOfItsOwn, and WidgetNotificationTest (parsing, errors, a press running onNotification with the clock set to now). owl check passes on the docs example.
  • Started from the tile: dumpsys notification shows it posted with PROMOTED_ONGOING, a countdown chronometer, three actions and vis=PUBLIC, in the alerting section, not the silent one. On the lock screen it counts down with pause, +1m and stop, and the status bar shows the chip.
  • Pause pressed on the lock screen: "paused · 0:21 left", the real time left at that moment.
  • From the shade: +1m while paused (1:21), resume (the countdown again), the ring at the end ("2m is up" from notify, while this one turned to "time's up", counting up, with +1m and stop), +1m after the ring (a fresh minute), and stop (gone).
  • Deleting the widget file takes its notification away.
  • Not tested: a ring after minutes with the screen off while the phone dozes, and a launcher killed with a notification up. For the latter, the code posts it again under the same tag or takes it away after the first load.

🤖 Generated with Claude Code

…ification:` (owl 23) shows a title, a text, a countdown or count up that Android keeps running, and up to three buttons whose presses run `onNotification`, so a timer shows what's left on the lock screen and pauses or stops from there

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
petrzpav and others added 2 commits November 18, 2026 10:52
…5, the level not yet released, as 23 and 24 have shipped (1.7.0 has 24); the top-level handler check keeps main's widget-or-face condition, now that strips check their own; registerNotExported and EmbeddedTerminal are imported from dev.omalauncher.system and dev.omalauncher.ui.home, where the source tree reorganisation moved them (40c8a10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ian and Japanese too, as lint asks now that main speaks them (SimonSchubert#280)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant