Crate sioul_app 

sioul-app: Sioul’s window. The Porch, budgets and accounts, over the same core as the command line; the window only lays out what the core decided. A library: the desktop program (main.rs) runs it, and so does Android’s (android/main.cpp, docs/android.md).

The window is made of QML pages, in crates/sioul-app/qml/ (each one is described in the QML reference: https://aurelienpierre.github.io/sioul/dev/qml.html), and of this crate’s Rust. CXX-Qt joins the two: backend declares the QML type Sioul, whose properties the pages read and whose functions they call, and desktop a second one, Desktop, for the desktop’s icons and title bar. What the pages show comes from sioul-core, as JSON with every sentence already in your language; what comes from servers is fetched with sioul-sync on other threads, so that the window never waits.

Every module here is private: only the window uses them. This reference shows them all.

Where to start reading

• run: the window, from the program’s start to its end.
• backend: the object Sioul. In its bridge, the module qobject, each #[qproperty] is a value the pages read, and are told about when it changes; each #[qinvokable] is a function a page calls, its name in camelCase in QML (text_with is sioul.textWith(…)). SioulRust holds what the object keeps.
• work (tasks, notes, links, focus), mail and pim (contacts and calendars): the same pattern, one area at a time. Most functions there return JSON for a page, or run their work off the window’s thread and hand the result back to it.

Names such as docs/android.md are the design notes in the repository’s docs/ folder. The website shows them too, under the same name: https://aurelienpierre.github.io/sioul/dev/android.html.

Modules, by theme

The window’s objects

• backend: the object behind the window, Sioul, and the work it runs off the window’s thread.
• desktop: the desktop’s icon theme, and where the desktop puts a window’s buttons.
• hours: what now is for (work, admin, leisure, a meal, sleep), as the pages and notifications ask it.
• colour: the sites in the screen’s own colours, and calmer colours (on computers).

Mail

• mail: the mail client: folders and their messages, what you do to them, drafts and sending.
• mailsearch: searching the mail by conditions, here and on the servers.
• gmail: Google’s mail, signed in on Google’s page.
• crypto: OpenPGP: protected messages opened for the reader, drafts signed or encrypted, your keys.
• securitykey: your security key: signing at Send, opening on request, its PIN held a while, its setup.
• senders: who someone is to you: where they stand, and why.
• mailnote: new mail told as a notification, at the times it may come.
• letters: paper letters: scans read in the background, each a card in the Porch.
• outside: writing from other applications: shared files and text, mailto: links.
• sites: sites kept in Sioul: the list, their notifications, logins filled from Bitwarden.
• spam: Sioul’s own spam filter in the mail settings, and on a computer “Train now” (docs/spam-filter.md).

Tasks, projects and time

• work: tasks, notes, links and focus.
• blocks: time blocks: a task pinned to a time, as an event in a calendar.
• capacity: what a day holds, as the window uses it.
• projects: projects, time and invoices.
• github: GitHub’s issues and pull requests, in the local “GitHub” list.
• reviews: the two rituals: closing the work day, and closing the day before sleep.
• remind: reminders before dates, each a quiet notification.
• timenote: the time running, in the system’s notifications.

Contacts and calendars

• pim: contacts and calendars.
• duplicates: duplicates in the contacts, found and cleaned when you ask.
• map: contacts on a map.

Money and papers

• bank: the money watch: bank accounts, where each movement went, what passed and what did not.
• contracts: contracts and subscriptions.
• papers: the papers wallet.

Pauses, do-not-disturb and health

• pauses: the two pauses, Free time and Pause.
• dnd: the system’s do-not-disturb, during the pauses and Sioul’s own, where the system lets an app set it.
• everywhere: do-not-disturb on every device, as this device applies it.
• health: the Health page, its settings, and the minute that reminds a dose.

Your devices

• share: sharing with your other devices: set up, one exchange a minute, versions put back.
• devices: this device’s sessions, as your other devices learn them.

On a phone

• alarms: doses reminded by Android’s alarm clock while Sioul is away.
• eventalarms: reminders before events, by Android’s alarm clock.
• wake: the alarm at waking.
• steps: the phone in the background: a service that keeps your devices in step.
• homecard: the card on the phone’s home screen.
• calls: calls screened on a phone.
• attachments: mail attachments opened in the app you choose and saved where you choose, without an antivirus to call.
• appnotes: other apps’ notifications on a phone: now, or how long they wait.
• reaches: Settings ▸ What reaches you in words, and a person’s sheet.

Modules

alarms 🔒

Doses on a phone, reminded while Sioul is not on the screen (docs/health.md, “On a phone”): Android freezes an app in the background, so each coming dose is given to Android’s alarm clock (android/main.cpp); at its time a receiver asks here what to say (health::alarm_decide), after reading what your other devices marked: taken, nothing; not known, the doubt said first. Elsewhere, nothing here: the window’s minute reminds.

appnotes 🔒

Other apps’ notifications on a phone (docs/android.md, “Notifications from other apps”). Android’s listener (AppNotes.java, in a process of its own, “:listener”) asks here, for each notification of another app, whether it comes now or how long it waits (sioul_appnotes_decide), and, when something moved the times (a pause ended, the hours or the choices changed), how long what it holds waits now (sioul_appnotes_review). The rules are sioul_core::appnotes; what reaches you when, sioul_core::attention, with today’s slots of time for you from their file (hours::slots): Time for you holds in this process too.

attachments 🔒

Mail attachments on a phone (docs/client.md, “Antivirus”). A phone has no antivirus Sioul can call, so none is asked and none is claimed: the words say the file was not checked. The attachment opens in the app you choose, which Android lets read that one file and nothing else of Sioul’s, and “Save…” asks Android where (android/package/src/com/aurelienpierre/sioul/ Attachments.java, AttachmentSave.java). Sioul’s own refusals stand as on a computer: mail set aside keeps its attachments closed, and programs, scripts and installers, Android’s among them, are never opened.

backend 🔒

The object behind the window.

bank 🔒

The money watch, for the window (docs/accounting.md, “The bank” and “Bank accounts”): your bank accounts (a current account, PayPal, Stripe), each with its exports taken in, the budgets it fills, where each movement went and why, what tops it up; then in words what passed and what did not, the week’s payments, and the balance carried forward a month.

blocks 🔒

Time blocks behind the window (docs/tasks.md, “Pinned to a time”): a task pinned to a time is an event in a calendar, made, moved and taken away here, the task tied to it; the plan reads them (sioul_core::blocks).

calls 🔒

Calls screened on a phone, as this device writes and says them (docs/android.md, “Calls”; the rules are sioul_core::calls, the decision Java’s: android/…/Calls.java).

capacity 🔒

What a day holds, as the window uses it (docs/capacity.md): the record gathered for the plan each time it is made (planned) and kept for what the pages show beside it; today’s slots of time for you, named, with a suggestion from your own well-rated items, and written to state/slots.toml for every process of this device to hold what waits in them (sioul_core::attention::Slots, crate::hours::in_slot); the day’s balance, in words, for the evening’s review (day_balance).

colour 🔒

Colours of the sites on the screen, and calmer colours (docs/colour.md).

contracts 🔒

Contracts and subscriptions, for the window (docs/accounting.md): the list on the Budgets page, the recurring payments that have no contract yet, the form, the letter that stops one, a mail kept as a contract.

crypto 🔒

OpenPGP behind the window: protected messages opened for the reader, the keys Autocrypt brings, what a draft can be (signed, encrypted), and your keys: made, imported, exported, removed. Passphrases stay in the keyring; decrypted messages stay in memory.

desktop 🔒

The desktop’s icon theme. Plasma, GNOME and others name one and say where icons live; elsewhere (a bare session, the offscreen platform, Windows, macOS) Qt knows of neither, and icons would be blank. The Breeze icons Sioul uses ship inside it (tools/bundle-icons.py), light and dark, and stand in for whatever the desktop lacks.

devices 🔒

This device’s sessions, as your other devices learn them through the sharing folder (docs/database.md, “Devices”; sioul_sync::devices): its start, its clean close, and between them working, up.

dnd 🔒

Do-not-disturb during the two pauses, “Paused” and “Free time” (docs/pauses.md, “Do-not-disturb”; the research behind it: docs/research/emergency-pause.md, 7 and P7–P10), and for Sioul’s own do-not-disturb on every device (Which::Global: its switch, the focus timer, sleep). Sioul holds its own notifications itself; here, the system’s do-not-disturb, with exceptions set beforehand, where the system lets an application set it, and a sentence saying what was silenced and what could not be.

duplicates 🔒

Duplicates in the contacts, behind the Contacts page’s “Duplicates”: what the core finds (sioul_core::duplicates) said in words, and what the person chooses: these cards cleaned, this pair merged or kept apart, what was done undone. Each change goes to the address books’ folders at once and their accounts’ sync sends it; nothing changes without a click.

eventalarms 🔒

Reminders before events on a phone (docs/android.md, “Events”): Android freezes an app it does not show, so the coming reminders of events (their own alarms, Sioul’s before them, the working day before) are given ahead to Android’s alarm clock (android/package/src/com/aurelienpierre/sioul/ EventAlarms.java), as the doses are (alarms): at the window’s minute, when Sioul is put away, after each ring. At its time a receiver asks here what to say (sioul_event_decide): the event read again (moved, cancelled, told already?), sleep or a pause holding it or not, the time left said as it is then; shown in the quiet “Events” channel, a tap opening the event. Every device tells its own: one held back on the phone because the computer was used a moment ago, then shown on an empty desk, would be an appointment missed.

everywhere 🔒

Do-not-disturb on every device, as this device applies and says it (docs/do-not-disturb.md; the rules are sioul_core::everywhere). The one caller of the do-not-disturb layer (crate::dnd): the pauses (pauses::apply), the switch, the focus timer and the minute all come here, and every device reads the same shared files: quiet.toml (the pauses), time/running.toml (focus), Health (the night), state/do-not-disturb.toml (the switch) and the [dnd] settings.

filters 🔒

Mail filters in the window (docs/client.md, “Filters”; the rules are sioul_core::rules, what reaches the server sioul_sync::filters).

github 🔒

GitHub, once asked in the task settings (docs/github.md): the issues and pull requests that are yours, in the local “GitHub” list every thirty minutes, each in the project whose routes take it; GitHub’s notification mail tied to its task and that task’s project.

gmail 🔒

Google’s mail (Gmail, Google Workspace) signed in on Google’s page, with a key of your own: Google gives its mail’s scope, a restricted one, to no key of Sioul’s yet. Google’s page opens in the system’s browser, its answer comes back to this device (a loopback port, as for the calendars), then IMAP and SMTP are given an access token (SASL XOAUTH2, sioul-sync’s sasl.rs). The other way, an app password, is the usual mail form (backend::add_mail), with Google’s words. docs/google.md, “Mail”.

health 🔒

Health and well-being, for the window: the page (a day, or its week, at a glance: meals, naps, the night and the doses, each day’s own changes; the medicines and the prescriptions), its settings (the usual meals and nights, the pauses), and the minute tick that reminds a dose once, quietly, and turns refills and renewals into tasks in a list your phone has. The rest goes to no server, except sealed to your other computers when you share with them (docs/database.md).

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.

hours 🔒

What now is for, as the window asks it (docs/areas.md): work, admin, leisure, a meal, sleep, the pauses; and what reaches you then, as the one matrix says (attention_now, comes; the model is sioul_core::attention, docs/attention.md). One place for the pages and the notifications; the rule itself is sioul_core::quiet::mode. Health’s meals, naps and nights are read again when its files change, today’s events at most every five minutes, today’s slots of time for you when their file changes: this is asked often (every list of sites, every notification).

letters 🔒

Paper letters, for the window (docs/porch.md, “Paper letters”): the scans dropped in the inbox folder read in the background (no notification: they wait for the Porch’s window, as mail does), then each a card there: who, what, how much, by when; a task for its date, its appointment in the agenda, its scan filed with its project.

mail 🔒

The mail client behind the window: folders and their messages, what you do to them, drafts and sending.

mailnote 🔒

New mail told as a notification, at the times it may come (docs/porch.md, “Notifications”; the rules are sioul_core::mailnote). After each fetch (arrived), the inbox’s arrivals are judged as the Porch judges them and gathered for ten seconds (a minute at most), every account together: then one quiet notification for the batch. What may not come now waits, and comes in one notification when a time begins in which it may (tick, each minute): “The Porch opens: …”.

mailsearch 🔒

Searching the mail by conditions, for the Mail page (docs/client.md, “Searching”).

map 🔒

Contacts on a map: where each postal address is, from the local cache of places; placing the others, once you allow it, one address a second, on a thread, the map told as they come.

outside 🔒

Writing from other applications (docs/client.md, “Writing from other applications”; docs/android.md, “Sharing”). Files and text shared to Sioul, one of your addresses chosen in Android’s share sheet, a mailto: link: each request (sioul_core::handed) becomes a draft whose window opens. On a phone each address that can send is a direct-share target (publish); on a computer sioul-app mailto:… is handed to the Sioul already open (hand_over). Nothing is sent until you press Send.

papers 🔒

The papers wallet, for the window (docs/papers.md): the page, its form, a paper kept from a mail’s attachment or a file, its renewal planned as a task.

pauses 🔒

The two pauses as the window has them (docs/pauses.md; the rules are sioul_core::pause): Free time, a switch in the bottom row, and Pause, a button apart, which covers the window. Their state is in quiet.toml, which the sharing carries to your other devices: a pause pressed on one is a pause on all (P8). Each device puts its own system’s do-not-disturb on and off (dnd): at the press, at each minute (what came from another device, what a crash left), when the window comes back.

phonemsgs 🔒

The phone’s messages on your computers, as this device writes and shows them (docs/android.md, “Messages on your computers”; the rules are sioul_core::phonemsgs).

pim 🔒

Contacts and calendars behind the window.

projects 🔒

Projects, time and invoices, for the window: a project’s page, the Time page, time noted by hand, an invoice made from a project’s unbilled hours (its record kept, its hours marked, its payment expected in the project’s budget), and paid.

reaches 🔒

Settings ▸ What reaches you (« Ce qui vous joint », ReachesTab.qml), as the window reads it: the moment now in sentences, where you started from (the presets), a card per time and per layer saying in words what comes at once, what is shown without a notification, what waits and until when, the matrix’s grid, the exceptions; and a person’s sheet (PersonSheet.qml): their list and why, Always through, and what each channel does with them at each time. The matrix is sioul_core::attention (docs/attention.md); this file says it in words, and writes what is changed here.

remind 🔒

Reminders before dates, for the window (docs/reminders.md): each minute, what is due becomes one quiet notification with “Open”; with the window closed, sioul remind --watch tells them, started with the session when asked on the Parameters page. Each is marked when told: told once, whichever runs. On a phone, the events’ reminders only, through Android’s notifications (eventalarms, whose alarms tell them while Sioul is away); the others wait for a computer.

reviews 🔒

The two rituals, for the window (docs/reviews.md): closing the work day (“Done for today”) and closing the day before sleep, each with how the day felt, all of it optional. The sheet’s view (DayReview.qml), the answers kept (sioul_core::reviews), the status line’s offer, the one notice at the end of the day’s last work or admin hours, and a day’s words for the Health page. Words only: no count, no score, nothing about what was not done.

securitykey 🔒

Your security key behind the window (docs/client.md, “Your keys on a security key”): the band of the writing window and of the Reader (plug the key in, its PIN, a touch, what went wrong, in words), signing at Send before the ten seconds of “Undo”, opening a message on “Open with your security key”, the PIN held in memory for fifteen quiet minutes, the key’s setup in Accounts ▸ Encryption, and “Let GnuPG release it”; GnuPG’s own steps as buttons there (“Import from GnuPG”, “Renew for two years”) and “Send it to keys.openpgp.org”, each run on its press only, its command kept under “By hand” to copy.

senders 🔒

Who someone is to you (docs/porch.md, “Who may reach you, and when”): a message’s sender (“Their mail”), and a contact’s card (“Their list”), where they stand and why, and their own choice set or taken back. The lists and their order are sioul_core::porch’s, the states sioul_core::reach’s.

share 🔒

Sharing with your other computers, for the window (docs/database.md): set up on the Parameters page, one exchange a minute off the window’s thread, the pages read again when another computer’s changes came in. Each part switched on or off on this device; the versions kept before other devices’ changes listed, and put back.

sites 🔒

Sites kept in Sioul, for the window: the list, their notifications (shown at once for a site in real time, else kept for the Porch), the site a message announces, and logins filled from Bitwarden.

spam 🔒

Sioul’s own spam filter in the window (docs/spam-filter.md): what the mail settings say of it, under “Your own spam filter” (SpamFilter.qml), and on a computer its training on demand, “Train now”.

steps 🔒

The phone in the background: “Sioul keeps your devices in step” (docs/android.md, “In the background”; StepService.java). A foreground service in a process of its own (“:steps”), which holds Sioul’s library without Qt’s window, asks Rust for a step at each of its alarms and when the sync app writes another device’s file into the sharing folder:

texts 🔒

Texts read and sent through your phone, as this device does its part (docs/texts.md; the rules are sioul_core::texts, the reading and the sending Java’s: android/…/Texts.java, TextSend.java).

timenote 🔒

The time running, in the system’s notifications (docs/tasks.md): while a focus session runs, one notification says its task and since when, with Pause (Go on, while paused) and Stop, which do what the focus window’s own buttons do. It follows the session from wherever it changes: the window, the notification itself, another device (the sharing brings time/running.toml), the command line. On a computer, the desktop’s (sioul_sync::notify::ongoing), while Sioul runs. On a phone, Android’s own, with a chronometer (android/main.cpp, TimeNote.java): it stays while Sioul is away, and its buttons reach here without the window (sioul_time_action, docs/android.md).

wake 🔒

The alarm at waking, on a phone (docs/health.md, “The alarm at waking”; docs/android.md, “Waking”): it rings when the night ends, on the mornings ticked with the night in the Health page’s settings, each night as that day has it (needs::Needs::alarm_of). Android’s alarm clock rings it (android/package/src/com/aurelienpierre/sioul/WakeAlarms.java): Sioul hands Java the coming wakings, eight days ahead, whenever they change, and Java asks again here at each ring, a little before each and as each night starts (another device may have changed it while Android kept Sioul frozen), after a restart, a change of time or of zone. Elsewhere nothing rings: the setting travels with the night, and the page says when the phone will ring. “Try the alarm” rings it ten seconds on, the same way, handed apart (trial): nothing written, the next waking left as it is.

work 🔒

Tasks, notes, links and focus behind the window (docs/tasks.md).

Statics

STARTED 🔒

When Sioul started, for timing.

Functions

cxx_qt_init_crate_sioul_app 🔒 ^⚠

CXX-Qt’s registration of the window’s QML module, resources and types (cxx-qt-build); runs once however often it is called.

process_age 🔒

How long ago the process started (Linux, Android): what came before run, the libraries loaded above all, for timing.

run

The window, until it is closed; returns what the program returns.

sioul_close_sites 🔒 ^⚠

Sioul has quit: the sites’ pages closed as a browser closes its tabs, before Qt WebEngine shuts down (cpp/webengine.cpp). engine is the QQmlApplicationEngine.

sioul_new_application 🔒 ^⚠

On a computer, Sioul’s application, a widgets application (cpp/application.cpp): the system tray’s menu is made of widgets on Plasma. values holds count C strings, the program’s arguments, which it copies; made with new.

sioul_quit_on_signals 🔒 ^⚠

SIGTERM, SIGINT and SIGHUP end Sioul as its window’s close does (cpp/signals.cpp); once the application is made.

sioul_set_activation_token 🔒 ^⚠

The activation token a second Sioul handed on, for the next window brought forward on Wayland (cpp/application.cpp; outside::activate_with_token). token is a C string, copied.

sioul_set_window_icon 🔒 ^⚠

Sioul’s own icon on its windows (cpp/appicon.cpp); once the application is made.

sioul_start_web_engine 🔒 ^⚠

Qt Quick drawn as Qt WebEngine (the Sites page) needs; before the application is made (cpp/webengine.cpp). Android has no Qt WebEngine: its Sites page opens sites in the browser.

sioul_warm_up 🔒 ^⚠

Sioul’s symbols font, and the system’s fonts and image formats read on a thread of their own (cpp/warmup.cpp); once the application is made.

steady_heap 🔒

Freed memory given back to the system as it is freed (glibc, Linux). By default glibc raises its thresholds after a large block is freed: blocks as large come from its heaps from then on, and each thread’s heap keeps up to twice that free for itself. Sioul’s threads read files of several megabytes, and Chromium’s run in this process: the window held some 15 MB free and unreturned with every page opened, 18 MB more with sites. Fixed thresholds (a block of a quarter of a megabyte or more mapped on its own, at most an eighth kept free at a heap’s end) cost a system call or two for each such block, which Sioul makes a few times a minute.

timed 🔒

Whether the start is timed: always on Android, else with SIOUL_TIMING.

timing 🔒

How long the start has taken so far, written to stderr (logcat on Android) on Android and when SIOUL_TIMING is set: what to make faster, measured.

widgets_application 🔒

A widgets application (QApplication), as the QGuiApplication CXX-Qt works with, which it is: made by cpp/application.cpp from the program’s arguments, as QGuiApplication::new makes its own.