Module attention

Expand description

What wants a person: the waiting stack, and the ledger an outcome goes to when it does not. Replaces the transient notice as a category. Attention, and the ledger: the two places a thing the system says can go.

A person has two questions about what the system is doing — what wants me? and what happened? — and this module is both answers, kept apart on one rule ([publish]):

something that needs a decision waits in [items], one row each, with the app that asks (icon and name), what it is about, since when, and one thing the person can do. It never expires on its own; it waits, is seen, is deferred (and the count of what is deferred stays on screen) or is acted on. A row that cannot act is not a row.
something that just happened is written to the ledger ([ledger]): append-only, attributed, never on a timer, never stealing focus, read by Activity’s History beside the workspace’s changes.

Both are the system’s, not a window’s: the registries live in the process, so a row raised in one app is read in another and survives the window that raised it.

// An outcome that needs a person: it waits.
ui::attention::publish(
    ui::attention::Notice::needs(owner, "Couldn’t reach the printer", action)
        .because("The print service stopped answering."),
);
// An outcome that does not: it is recorded.
ui::attention::publish(ui::attention::Notice::did(owner, "Moved 3 files to Trash"));

This replaces the transient notice as a category: a toast claims something matters right now and will not matter in four seconds, both halves usually false, and the timer teaches people not to read. What disappears is the timer, not the message. The surface is reachable from anywhere: [CHORD], [open], and the count ([unseen]) a window’s bar can show.

Structs§

Acted: What acting on an item said, for the surface’s caller to carry out.
Action: The one thing a person can do about an item: a verb the app knows, and the words the button shows (“Print again”).
Entry: One thing that happened.
Item: One thing waiting for a person.
ItemId: An item’s identity.
Notice: What the system has to say: a piece of news, and whether it needs a person.
Owner: Who is asking: an app’s identity, as the row carries it. A row always names the app as well as showing its icon.
Presses: The stack’s state: what its rows wrote, which row the keyboard is on, and the revision it last drew.
Stack: The waiting stack as a widget: it keeps its rows, rebuilds them when the stack moves, and reports what was pressed through its Presses.
Watch: A registered watcher of the waiting stack; dropping it stops the wakes.

Enums§

Press: What the person pressed on the stack.
Published: What publish did with a notice.
State: Where an item stands.
Target: What an item is about, when the app that raised it can take it back.
Urgency: How much it costs to leave an item waiting.

Constants§

CHORD: The chord that opens Needs you, wherever the person is.
SHOW_JOB: The verb a failed job’s row carries: open the job’s subject.
UNKNOWN_APP: An app whose own identity a raised notice does not carry: one raised by the toolkit itself, for a failure it saw (a job that could not finish).

Functions§

act: Answer item id: the action it waited on, which the app now performs. The item leaves the stack.
apply: What acting on a row asks of the app: the verb, and what it is about.
clear: Take every item away: a test’s clean slate, and what a session reset does.
defer: Put item id out of the way; it stays counted as deferred.
deferred: How many the person put out of the way: still counted, still honest.
dismiss: Take item id out of the stack: it was answered, or no longer holds.
dismissed: Take back every item about target: the thing that raised it was answered somewhere else (a job’s row was read, its failure with it).
entries: The ledger’s entries, oldest first: every outcome the system recorded.
items: Every item waiting, ordered by urgency and then by age: the first row is the one that costs most to leave.
newest_first: The entries newest first, which is the order History lists them in.
open: Ask for Needs you: what CHORD, the bar’s bell and a record of “3 more” do.
pane: The stack: what is waiting, and what is deferred.
pill: The count a window’s bar shows: nothing while nothing waits, else how many nobody has looked at.
publish: Say it once: an outcome goes to the waiting stack if it needs a person, or to the ledger if it does not.
raise: Put item in the stack. The same news waiting again replaces what waits, so a repeating failure is one row that says the latest why.
recorded: How many entries the ledger holds.
revision: Bumped by every change to the stack.
search_ledger: The entries whose outcome, subject or author match query, newest first.
seen: Note that the stack was shown: everything in it stops counting, and the rows stay. Seeing is not dismissing.
take: Take the item id out of the stack and say what it asked for.
take_opening: Whether the surface was asked for since the last call.
unseen: How many items nobody has looked at: the count a bar shows.
waiting: How many items are waiting and not deferred.
watch: Call wake whenever an item is raised, seen, deferred or acted on, until the returned guard drops: a surface that shows what is waiting redraws then, rather than on a timer.