Module homecard 

The cards on a phone’s home screen (docs/android.md, “The card on the home screen”). The full card: today first, the date and the weather (now, the next four hours, the next morning, afternoon, evening and night, then the next seven days); then what the Porch has for you that is not mail (today’s doses due, a code you asked for, reminders of dates, waits, payments and papers, do-not-disturb’s line, the calls declined, two events at once); then Now: the next step when it is the time for one, and where you stopped. The mail card and the agenda card list the latest messages the Porch shows (sender, date, subject, a line of the text, the account’s colour) and the coming appointments, day by day, each in its calendar’s colour. Never a count. Android draws them (android/package/src/com/ aurelienpierre/sioul/HomeCard.java, the lists’ rows HomeCardRows.java), without Qt: Sioul writes what they say in a small file of its own (home-card.json, in its state folder) and tells Android to draw them again.

Android freezes Sioul in the background, so the card is given ahead, in frames: one per change of time until the end of tomorrow (work, admin, a meal, winding down, sleep, waking, the Porch’s hours, midnight), each with its own words, the Porch’s mail as it lets mail through then, the reminders and calls it lets show then, and the next step as the plan stands then. The weather is given hour by hour, from the forecast kept (40 hours and more ahead, weather::card), each hour with its own “now”, next hours and parts of the day. The messages and the events are written once, each word that changes at midnight with until when it holds (“14:05”, then “yesterday”; “Tomorrow, Thu 8 Oct”, then “Today, Thu 8 Oct”). Java shows the frame and the hour for now, leaves out the events over, and draws again at the next change. Rust writes the card when the Porch is computed (mail fetched), when the plan is made, when the agenda is read again (an event changed), when a forecast or the reminders change, at the window’s minute when a frame ended (midnight among them) or five minutes went by, and when Sioul is put away; outside the window, where Rust runs already (a dose’s alarm, its “Taken”), it writes the doses’ lines alone. Nothing here fetches anything. Elsewhere than on Android nothing is written, unless SIOUL_HOME_CARD is set (to read the file on a computer).

Structs

AgendaInput 🔒

The calendars’ events from today’s midnight to the reach’s end, as last read (agenda_input), and whether there is a calendar at all.

AgendaLines 🔒

The coming appointments, from today to a month on.

Code 🔒

Day 🔒

One day of the agenda, and its name as it changes at each midnight.

Dnd 🔒

The do-not-disturb on every device, as the card says it: switched on by hand or for a focus session. Sleep, the pause and free time say their own words in the status line, so they add none here.

Dose 🔒

A dose for the card, as the Health page knows it (health::card_doses).

DoseLine 🔒

Event 🔒

One appointment, as an agenda card shows it.

Frame 🔒

One stretch of time that says the same.

Label 🔒

Mail 🔒

A message, as a mail card lists it.

Moment 🔒

What a card is made from, besides the Porch and the plan.

More 🔒

What the full card is made from besides the Porch, the plan, the agenda and the doses.

PlanInput 🔒

The plan, as the window last made it.

PorchInput 🔒

The Porch’s messages, as the window last gathered them, before the hours sort them.

PorchLines 🔒

The Porch’s part of a frame, as written.

PorchMade 🔒

What the Porch shows at a time, before its messages are given their places.

ReminderLine 🔒

A reminder, as the card says it, from its time while it makes sense.

Snapshot 🔒

What the card says, as Java reads it (HomeCard.java). Times are Unix milliseconds.

Step 🔒

Timed 🔒

A line said from a time until another (Unix ms).

TodayLines 🔒

Today, as the full card begins.

WeatherDay 🔒

One day of the forecast, from its midnight to the next (Unix ms).

WeatherHour 🔒

One hour of the card’s weather: what it says while the hour lasts.

WeatherInput 🔒

The weather the card is made with: whether a place is chosen, and the forecast kept (backend::update_weather).

WeatherLines 🔒

The weather at the place chosen, from the forecast kept.

Words 🔒

The list’s headings, in the person’s language.

Written 🔒

The card last written: what it says, when, and when its first frame ends (Unix seconds).

Constants

EVENTS 🔒

The appointments the card lists, at most, nearest first.

FILE 🔒

The card’s file, in Sioul’s state folder; Java reads it there (files/state/sioul/, android/main.cpp’s XDG folders).

FORECAST_KEPT 🔒

A forecast older than this is not shown: Sioul was not opened for a day.

FRAMES 🔒

Frames at most: each change of time until the end of tomorrow.

FRESH_MS 🔒

How long the card says nothing of its age: past it, “at 14:05”.

HORIZON_DAYS 🔒

The agenda’s reach: today and the days to come.

MAIL 🔒

The Porch’s messages the card lists, at most, newest first.

OPENED 🔒

A tap on the card, kept by Java (HomeCardOpener.java) for the window.

PLAIN 🔒

The flag, among the task pages’ (work::WorkState), that turns the details off.

REMINDERS 🔒

The reminders the card holds, at most, soonest first (Java shows a few).

REWRITE_EVERY 🔒

While the window runs, the card is written again at least this often, its age said afresh.

TAP_KEPT_MS 🔒

A tap older than this is let go: Sioul did not come up meanwhile.

TEXT_CHARS 🔒

A message’s line of text, at most (Java shows one line of it).

VERSION 🔒

The file’s version: 3 from the full card made around today (October 2026). Its frames are named “times”: an older Sioul’s Java reads “frames”, finds none, and says beyond until Sioul opens. This Java reads both.

Statics

AGAIN 🔒

Asked again while being made: once more after. Drawn when asked so once.

AGENDA 🔒

The events as last read for the card, and what the window hides of them.

AGENDA_AGAIN 🔒

Read the calendars again before the next card: an event changed.

DND 🔒

The shared do-not-disturb’s moment, as last seen in this process.

HIDDEN 🔒

PLAN 🔒

PORCH 🔒

What the card is made from, as the window last had it.

REMINDED 🔒

The reminders as last gathered (remind::tick, each minute), the events’ left out.

RUNNING 🔒

TELL 🔒

WRITING 🔒

One writing at a time: the window’s and a dose’s alarm’s.

WRITTEN 🔒

Functions

agenda_day 🔒

A day of the agenda and its names: “Mon 12 Oct” until the day before, “Tomorrow, Mon 12 Oct” that day, “Today, Mon 12 Oct” on the day; seen from today.

agenda_input 🔒

The events of today and the month to come, read from the calendars once, then again when the window read the agenda again or the day changed.

agenda_lines 🔒

The coming appointments, from today to a month on: those not over yet, cancelled ones left out, nearest first; each under its day (Java’s), in its calendar’s colour. Details off, none named: “An event”, its time. None without a calendar.

agenda_seen 🔒

The agenda read again by the window (pim::show_pim: a sync, an event made, moved, removed or undone), with what it hides meanwhile: the card reads the calendars again, and follows.

capital 🔒

“Jeudi 8 octobre”: a heading’s first letter a capital, whatever the language writes.

codes 🔒

The codes and links you asked sites for, still valid, newest first: each as the Porch’s “Right now” says it, its site and the code, with the warning when its sender is not verified, until it expires (porch::sent and its validity, as the Porch hides it). Details off, one line without site or code: “A code waits on the Porch.”

colour 🔒

A calendar’s colour as “#rrggbb”, whatever its tool wrote (“#4C6B5CFF”); “” when it gave none, or one that does not read.

content 🔒

What a card says, its age aside: written again unchanged, Android need not draw it again.

date_labels 🔒

Today’s date, as the full card begins: “Thursday 8 October” until midnight, then “Friday 9 October” until the next (the frames end then).

day_month_short 🔒

“7 Oct”, “7 oct.”, “1er oct.”: a message’s day, as a mail card dates it; with its year when it is not today’s.

day_short 🔒

“Thu 8 Oct”, “jeu. 8 oct.”: a day as an agenda card names it.

details 🔒

The details are on unless “Details on the home screen” was unticked on this device.

dnd_seen 🔒

The do-not-disturb on every device, as its module reads it (everywhere::moment: {on, why, until, until_at, line…}), handed after each of its changes, here or from another device, and when first read in a process. The same as last time: nothing. With the window’s Porch and plan, the card is made again; without (a receiver alone), the card on disk gets its do-not-disturb lines alone, the rest as Sioul last saw it.

dose_lines 🔒

Today’s doses in words: “Magnesium · 300 mg, 12:30”, and once that it was not marked elsewhere is no longer known, “…: check before taking it.” Never “missed”, “late” or “not taken” (docs/health.md, “Knowing”). None with the details off: a medicine’s name, even “a dose”, says health to whoever shares the launcher.

doses_changed 🔒

A dose marked or reminded outside the window (a dose’s alarm, its “Taken”: alarms): the card’s doses written again, the rest as Sioul last saw it. No card yet, nothing.

draw 🔒

Android asked to draw the card again: an explicit broadcast to Sioul’s own receiver (android/main.cpp, the call the sync apps are asked with).

event_time 🔒

An event’s time, as an agenda card says it: “11:00 – 12:00”; ending another day, “23:00 – Fri 9 Oct 01:00”; a whole day, nothing; several whole days, “Until Fri 9 Oct”.

frames_of 🔒

A written card’s frames: “times” from version 3, “frames” before.

has_setting 🔒

Whether the setting shows: on a phone (or with SIOUL_HOME_CARD set).

kind 🔒

What a frame is, for Java’s colours and tests: the time’s word, or the pause’s.

kind_word 🔒

A code’s kind, as the card’s words name it.

labels 🔒

How old the card is, said once it is: “at 14:05” until midnight, “yesterday at 14:05” the next day, a short date after.

mail_came 🔒

New mail fetched outside the window (the phone’s background service, steps, while Sioul is closed or frozen): the card’s messages and codes made again from the Porch as it is now, the rest (its lines, the step, the doses, the agenda) as Sioul last saw it. In the window’s process the window’s own Porch follows (porch_seen): nothing here. No card yet, nothing.

mail_line 🔒

A message the Porch shows, as the card lists it: from the Porch’s line (item, which keeps hostile and rude words out) and its message (triaged: when it came, whether it was read, the account it came to). With when it came, for the order.

mail_when 🔒

When a message came, as the card dates it, each wording until it holds no longer (Java picks the first whose until is ahead, 0 for good): its time today; “Yesterday” from midnight; its day after. Seen from now.

midnight_after 🔒

The midnight after at, in its zone.

ms 🔒

now 🔒

Sioul put away, or a setting of the card changed: written now, and drawn.

on 🔒

Written on Android; on a computer only when SIOUL_HOME_CARD is set.

opened 🔒

A tap on the card, kept by Java (HomeCardOpener.java) and taken once, as main.qml’s openThing takes it {kind, uri, key}: the Porch; a message, on the Porch in its Reader (“card-mail”, its file); Now on a step (“now”, the task’s address); the Agenda; an event in it (“event”, its file); what a reminder is about (its task, budget, paper or contract). One older than five minutes is let go.

overlap_lines 🔒

Two events at once today and tomorrow, each said on its own day until both are over, as the Porch says today’s (overlaps): the time to get there and back counted; those set aside for good left out.

patch_dnd 🔒

The do-not-disturb lines of a card written before, said again: each frame from now on as Dnd::line_in says it, a frame cut where it ends (Unix ms now). Whether anything changed.

patch_mail 🔒

The messages and codes of a card written before, made again from input: each frame’s Porch as snapshot makes it at the frame’s start; the frames that say nothing of the Porch (asleep, a pause, free time) left so. Whether anything changed.

path 🔒

plan_seen 🔒

The plan the window just made (work::show_work): the card follows.

porch_at 🔒

What the Porch shows at at, as backend::compute makes it: the mail the matrix of what reaches you shows at that time (Attention::mail, Free time’s “Nothing at all” too), the Porch open in its hours and in quiet time, closed otherwise with when it opens, resting after a pause until its next hours (pauses::porch_rests). Never “Open it anyway”: a moment’s choice in the window, not the card’s. Its messages newest first, as a mail card lists them; never a count.

porch_key 🔒

What makes the Porch at at say what it says (porch_at): two frames alike are made once. Its mail by the time it is for; open or closed, and when it opens, from which day; resting after a pause.

porch_seen 🔒

The Porch’s messages the window just gathered, before the hours sort them (backend::compute): the card follows.

refresh 🔒

The card made from what the window last had, written, and drawn when it changed (or tell). Not before the window has both the Porch and the plan in this process: a card made without them would lose its mail and its step until Sioul comes back (put away at once after it opened, its pages wait); the card written before stays, its age said.

reminder_lines 🔒

The reminders the card says: those of dates, waits, payments, papers, contracts and the money watch, from their time while they make sense (the events’ come as Android’s notifications, and on the agenda card), soonest first, in one line each: what, then when or why. Details off, none named. Each with whether it is work’s (it waits while work rests).

reminder_opens 🔒

What a reminder’s tap opens, as a reminder’s notification does on a computer (remind::tick): its task, its budget, its paper, its contract; anything else, the Porch.

reminders_seen 🔒

The reminders the window just gathered, told or not (reminders::gather): the card follows when those it may say changed.

said 🔒

A message with its words given, in tr’s language.

setting 🔒

“Details on the home screen”, for Settings (on a phone): its row, in group and section.

snapshot_with 🔒

The card, from now to the end of tomorrow.

soon 🔒

The card made on a thread of its own, several asks in a row making it once.

status 🔒

The status line’s sentence for mode, as seen from at (backend::mode_json’s, and “Work until 17:00.” in working hours, where the window’s line says nothing).

step_at 🔒

The next step at at, as Now would pick it then: only in work or admin time (or with no hours set), never asleep, in a pause, in free time, at leisure or during a meal; offices open or not then, “Not now” and the day’s weather today, a new day starting clean. The page’s own filters (one kind, one category) are the page’s, not the card’s.

tap 🔒

A tap as Java writes it: {“open”: “porch” | “now” | “mail” | “agenda” | “event” | “reminder”, “uid”, “key”, “at” (Unix ms)}. A message or an event without its file opens its page; a reminder, what it is about (“key”: its address, sioul:task/…), else the Porch. The file is the window’s to check, as for any link.

tick 🔒

The window’s minute: the card written again when its first frame ended, or five minutes went by (its age said afresh).

time_for_a_step 🔒

Whether a step is for this time: work or admin time (or no hours set), never asleep, in a pause, in free time, at leisure or during a meal.

timeline 🔒

The changes of time from now to the end of tomorrow (Health’s meals and nights are known that far: Needs::kept_around), each with what it is for: a frame ends when the time changes (quiet::mode’s until), when a meal, a nap or the night begins, starts proper (winding down becomes sleep at bedtime) or ends, when the Porch opens or closes, when it stops resting after a pause, and at midnight, so that “tomorrow” in a frame’s words stays true.

today_lines 🔒

Today, as the full card begins: the date, then the weather at the place chosen, hour by hour from the hour under way until end (the last frame’s) or the forecast’s end, and its days. No place: where to choose one. No forecast, or one older than a day: that none is there yet. The weather is no detail: shown with the details off too.

weather_input 🔒

The weather as the card says it: the place chosen, the forecast kept.

weather_seen 🔒

A forecast fetched, or the place changed (backend::update_weather): the card follows.

when 🔒

“at 14:00”, “tomorrow at 9:00”, “on Monday 12 October at 09:00”, as seen from from.

write 🔒

The card’s text in place of the one before, whole (written beside, then renamed).

Type Aliases

CallsAt 🔒

The calls declined as the Porch lists them at a time (calls::for_card): their lines, seen from the time given, as the moment given lets their callers through.

Hidden 🔒

Removed or skipped in the window, waiting for “Undo” to pass: left out.