Classroom_Desktop/docs/ui-scale.md

Classroom display size (Plasma v2)

Each room keeps its own UI_SCALE in /etc/ekklesia-classroom/device.conf. Package upgrades preserve the value. Plasma applies it at every classroom login. Native display resolution is unchanged.

Administrator setting

On the classroom keyboard press Meta+Ctrl+Alt+Shift+D to open Display size. It is hidden from application lists and the teacher's panel. Saving requires administrator authentication through polkit; the keyboard shortcut grants no privilege. Choose a percentage and press Save and apply. Canceling the password prompt leaves the saved setting unchanged.

Start at 200% for a 4K TV, which gives 1920×1080 logical space while retaining 3840×2160 output. The offered values are 100, 125, 150, 175, 200, 225, 250 and 300%. The choice applies to all connected, enabled displays on that classroom computer.

For SSH administration, the fixed-purpose helper can also be run as root:

sudo /usr/local/bin/classroom-set-scale 2

It writes only UI_SCALE, preserving room configuration, broker credentials and file ownership and permissions. The new size takes effect at the next classroom login, or by running classroom-scale inside the classroom's graphical session. The hidden window saves and applies in one operation.

Implementation and validation limits

classroom-scale uses kscreen-doctor; the login autostart runs only in KDE and the script applies only to the classroom account. Values read from older/manual configurations remain clamped to 0.8–3.0; invalid/nonfinite values become 1.0. The helper accepts only the window's predefined choices, takes no paths, and writes the root-owned settings file atomically. Polkit requires auth_admin for every save, with no retained authorization.

Hardware checks required: shortcut registration, administrator authentication, 200% at 4K, logout/reboot persistence, and Chrome/Parent Call/DVD sizing. XWayland applications may be softer than native Wayland applications when scaled.

Wallpaper in the v2 package

The approved background source is config/wallpapers/classroom-calm.png. The package installs it at /usr/share/backgrounds/ekklesia/classroom-calm.png, the path used by the packaged Plasma layout. The layout is rebuilt at login, so upgraded classrooms receive the package wallpaper without per-room copying.

A desktop the layout never saw (0.2.6.6)

Tiny Pebbles came through the 0.2.2 → 0.2.6.4 upgrade showing Plasma's own purple wallpaper. Its desktop was containment 10 with no Wallpaper group; River Kids' is containment 1 with one. The package and the picture were the same on both.

The layout sets the wallpaper on the desktops that exist while it runs. Plasma makes a desktop for every screen or activity that appears later, and it makes those without the layout. 0.2.2's updater rebooted as soon as it had installed, at 03:00–03:30. A television switched off at the set is usually no screen at all, so the layout would have run with no desktop, and the desktop Plasma made when the television came on was bare. A panel built with no screen takes number 1 and its eight applets 2–9, which is exactly how a desktop ends up as 10. The television is inferred, not observed. See the hardware check in testing.md.

Measured in the lab (Plasma 6.3.6, Debian 13):

What was tried	What happened
Activity manager delayed 20 s at login	Plasma waited for it; desktop 1, wallpaper right. Not the cause
A new activity created mid-session	Plasma made desktop 11 with no Wallpaper group, the same shape as Tiny Pebbles' 10. The screen showed Plasma's Next; the panel was untouched
Look-and-feel default Image= set to a file path (0.2.2–0.2.6.5)	Ignored. DefaultWallpaper in libkworkspace6 looks the value up as a wallpaper package under wallpapers/<name>, the way Breeze says Image=Next
The same default set to a package name, whose one image links to the file	Desktop 11, still with no Image, showed the classroom's picture after a shell restart
Setting it live over D-Bus (evaluateScript, plasma-apply-wallpaperimage)	Refused: "Widgets are locked". The classroom's lockdown forbids the scripting console, and it stays forbidden
Disabling the only screen to reproduce a screenless start	KWin refuses ("Disabling all outputs … is not allowed"), and the nested lab cannot hot-plug a screen

So there are two parts, and they do different jobs:

• The default is now a package, /usr/share/wallpapers/EkklesiaClassroom. Its image is a link to the file above, and the look and feel names it. Any desktop Plasma makes without the layout shows the classroom's picture with nothing having to run. This is the fix for Tiny Pebbles.
• classroom-desktop-wallpaper writes wallpaperplugin=org.kde.image and the classroom Image into every desktop containment already in the file, so the configuration says what the screen shows. It finds desktops by plugin (org.kde.plasma.folder, org.kde.desktopcontainment), never by number. It changes nothing else, and it does not write a file that is already right. It runs as plasmashell's ExecStartPre, the one moment the shell does not own the file: every login, every reboot, every restart after a crash. At a login it usually finds nothing, because classroom-desktop-reset has just removed the file for the layout to rebuild.

To apply it in a running session without logging out, from the maintenance terminal:

classroom-desktop-wallpaper --check                   # read-only
systemctl --user restart plasma-plasmashell.service   # the panel blinks, windows stay

Run without --check while the shell is up, it refuses and prints that second line rather than edit the file underneath the shell.

Tests: tests/test-classroom-desktop-wallpaper.sh (in the build) covers Tiny Pebbles' own file, a healthy River Kids file, differing numbers, idempotence and the guard. tools/lab/wallpaper-check covers real Plasma, reading the colour off the screen, and runs inside tools/lab/dirty-upgrade. tools/validate-trixie-release.sh covers the installed package when upgrading from a previous release.

What the one number reaches

classroom-ui-scale prints it, clamped, and everything that cannot read the display scale for itself asks that command rather than the file:

• Plasma — the panel, the clock, notifications, the volume display and every dialog, because classroom-scale sets it as the display's scale through kscreen-doctor at every login.
• Chrome — --force-device-scale-factor, because Chrome on the sway session was measured not to follow the compositor's output scale on its own. Under Plasma it does, so this is now a second scaling: measured at 150%, Chrome's pages report devicePixelRatio 2.25, not 1.5. Left as it is in 0.2.6.1 because it is the size teachers know; see wonder-ink.md.
• Wonder Ink — its window follows the compositor as every Qt application does, and its pages start at a zoom of UI_SCALE, so a lesson is the size the browser shows it.
• The disc player's own surfaces — they are measured in the logical pixels the compositor is already scaling, so they follow without being told.

The clock is the one thing that used to be left behind. It was pinned at 15 points, which is the same 15 points at every scale, and on a 4K television it was a clock nobody at the back of the room could read. It is sized by the bar now.