Skip to content

Welcome App

Jump to bottom
P3DROVFX edited this page Oct 12, 2026 · 1 revision

Welcome App

The Welcome app is the guided first-run of the shell — a short, animated tour that gets a fresh install from "a bare desktop" to your desktop: language, keyboard layout, date and time, network, your name, a look (wallpaper + colours, or a whole preset from the store), your monitors, your bar, the shortcuts worth remembering, how Search works, and the accounts you may want to connect (Gmail, Google Calendar, Google Drive backup, TickTick). It can restore a previous settings backup before anything else, and you can reopen it at any time.

When it opens

  • After installing. The installer (ii-p3drovfx install, the same setup-ii-p3drovfx.sh CLI that updates the shell) starts the shell and opens the Welcome over IPC once the shell answers — it polls for up to 15 seconds in the background rather than holding up the summary. Every successful deployment opens it, except update. (It does not depend on whether the fork's Hyprland files were installed; those only make the compositor float the window.)
  • From the upstream ./setup a first install on a TTY can't reach a running shell, so the request waits as a file, ~/.local/state/quickshell/user/welcome_pending: the shell reads it at startup, waits 2.5 s for the session to draw, opens the Welcome and deletes the file. It means "setup asked for it", never "already shown" — a new install, or ./setup resetfirstrun followed by an install, re-arms it; an update does not.
  • On demand: Super + Shift + Alt + /, or qs -c ii ipc call welcome toggle (open, close).

Every way of opening it goes through GlobalStates.openWelcome(), which first moves you to the nearest empty workspace (the guide is a window in the middle of the screen, and on a fresh install the desktop underneath is whatever terminal ran the installer) — skipped if the current workspace is already empty. The switch is asynchronous, so the window opens ~220 ms later to avoid mapping on the workspace it is leaving.

The pages

Thirteen steps with stable ids (WelcomePageRegistry); the button of each page names the next step ("Add your name"), not the action.

# Page What it does
1 Hi there (hello) A rotating greeting; "Let's go". At the bottom-left, Restore from a [[settings backup
2 Choose your language Only the languages that have translations; English first. A note says missing strings are completed later by AI
3 Keyboard layout The current XKB layout and variants from Hyprland, a list of known layouts, and manual fields behind a switch. It applies at once and writes a managed block in custom/input.lua. Skippable
4 Date and time Formats shown as the rendered date (never as a format string), 12/24 h, week starting Monday
5 Get connected (start) Wi-Fi (choose a network inline), Bluetooth, audio output, battery — online means Wi-Fi or ethernet. "Set up later" appears only when nothing is connected
6 Add your name (profile) Name, photo, avatar shape and colour ([[Customization
7 Make it yours (personalize) Two tabs: pick a wallpaper and colour scheme, or ready-made looks from the Preset Store — one click installs and applies a preset ([[Preset Store
8 Set up your displays Arrange monitors by dragging; each physical screen shows a big number for ~3 s on arrival (and on demand) so you know which is which
9 Arrange your bar (bar) Opens the real [[Edit Mode
10 Shortcuts to remember Keybind cards derived from your actual Hyprland binds (never hard-coded keys); clicking a card runs that shortcut; a checklist ticks what you've tried but never blocks
11 One box for everything (search) The launcher's panels and prefixes, derived from the live settings — a disabled panel vanishes and a rebound prefix shows the new symbol
12 Connect your accounts (learn) Four tutorial cards, below
13 All set! (finish) Done; opens Settings if you want

Navigation: the floating buttons, Alt + ← / →, Esc (back out of a tutorial, then close). Pages slide with an interruptible transition; hovering Next or Back nudges the current page slightly in that direction (a predictive preview) without loading the destination, and an animation level of "reduced" turns the motion, blur and stagger off.

The account tutorials

Each tutorial is a short step list with live "done" states, linking to the console you need and to the Settings page that finishes the job; they don't duplicate OAuth or sync code.

Tutorial Walks through
Set up Gmail Google Cloud project → Gmail API → consent screen (scopes) → test user → Desktop OAuth client → paste the ID and secret → Connect Account → verify ([[Gmail Integration
Set up Google Calendar Install khal and vdirsyncer (the right command for your distribution) → OAuth credentials → ~/.config/vdirsyncer/config (a copyable sample) → vdirsyncer discover / sync → khal configure → verify ([[Khal Integration
Set up Google Drive backup Check rclone → enable the Drive API in the same project → Settings → Accounts & Backup ([[Rclone and Google Drive
TickTick Developer Center app → client ID / secret → authorize ([[To-Do and Tasks

The credentials flow is shared: all four reuse one Google Cloud project.

Under the hood

  • In-process. welcome.qml is only a compatibility wrapper for the legacy keybind; shell.qml keeps WelcomeWindow.qml behind a Loader gated by Config.ready && GlobalStates.welcomeOpen, so the whole tree is released when the Welcome closes. It always starts at hello.
  • One page alive. WelcomeFlow holds only the current page (and, mid-transition, the one leaving); no page is preloaded or remembered as visited.
  • Previews it opens, it closes. Sidebar/Search previews and dialogs shown by a page are cleaned up when you leave it — but only those the Welcome itself opened; something you already had open stays.
  • Deep links. GlobalStates.openSettingsPage(pageId, subPageId) validates ids against SettingsPageRegistry; tutorials use it to land you on the right settings page, even if Settings is already open.
  • Shortcut cards resolve actions through WelcomeKeybindRegistry, which lists candidate descriptions per action (the default Shell: Open search only is commented out in the shipped binds, so Search also falls back to the Super tap) and formats modifiers from your Cheat Sheet options.
  • Files: modules/welcome/ (WelcomeWindow, WelcomeFlow, WelcomePageRegistry, Welcome*Page.qml, WelcomeMotion, WelcomeRestoreDialog, WelcomePresetStorePane, tutorials/), modules/common/ShellModePolicy.qml, GlobalStates.qml.

Related pages

← Back to Home

Clone this wiki locally