gib/Panama
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4cbab01ae2115bef8fad2a506e98962f99eb236b
Panama/docs/settings.md
T
Gabriel Brown 6dc606b872 Give focus modes conditions rather than alarms, and let Gaming hand over 
A mode is on because something is true right now: a game is running, a window is
fullscreen on a given display, a workspace is focused, the clock is inside a
window. That is asked again rather than fired once, and it is the whole reason
schedules could be included here without the usual failure modes. A machine
asleep at 23:30, rebooted at 02:00, or opened at 08:00 into a window that has
already passed all reach the right answer by being asked again; an alarm gets
all three wrong.

The midnight-crossing rule is the part worth being careful about: a window
belongs to the day it STARTS on, so a Friday-only 23:30-07:00 covers Saturday
morning and must not cover Saturday night. That arithmetic was tested as pure
logic before anything was built on it, including every malformed input failing
closed -- silencing someone because a time string was wrong is the worst way
this could fail.

This does not take over the manual timed session. FocusSession already owns
that, with its capsule, shortcut, Quick Settings entry and contracts, so modes
defer entirely while one runs. Two writers of Do Not Disturb would each restore
whatever the other happened to leave behind.

Gaming hands over rather than being duplicated. The hook was silencing
notifications itself, which would have made exactly those two owners -- and
Gaming.active only polls while its settings page is open, so a mode could not
have seen a game reliably in any case. The hook reports the game over IPC now
and the mode decides what that means, the Gaming page points at it, and
gamingSilenceNotifications is retired from the schema, since a setting nothing
reads is the dead row this work keeps removing.

Sleep ships disabled. A desktop that starts silencing someone on first boot has
overstepped, whatever the default hour.

Three contracts moved with it. gaming-contract asserted the hook uses setDnd,
which was right before and wrong now; the shell-side assertions that setDnd and
dndState exist stay, because a toggle would flip an already-silent machine back
on. The new contract is proven to fail by breaking the midnight rule and by
letting modes run alongside a manual session.

Claude-Session: https://claude.ai/code/session_01BRvzt4H8XXLPVH5MyYdk9L
2026-08-20 02:06:50 -04:00

330 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Settings reference
**Generated from `config/dot/quickshell/config/PreferenceSchema.qml`.**
Do not edit this file. Run `quickshell/scripts/panama-settings-docs`
after changing the schema; a contract fails when this copy is stale.
132 settings across 27 groups. 67 of them are applied to the compositor and confirmed by reading the value back.
## accessibility
Found on **Accessibility**.
| Setting | Default | What it does |
|---|---|---|
| **Magnifier**<br>`magnifierFactor` `cursor:zoom_factor` | 1.0 | Magnifies the screen around the pointer. 1.0 is off. Range 1.0–5.0. |
| **Magnifier follows in steps**<br>`magnifierRigid` `cursor:zoom_rigid` | false | Moves the magnified view in increments rather than gliding with the pointer |
| **High contrast**<br>`highContrast` | false | Increases contrast in applications that support it. Modern GTK applications read this from the desktop portal and restyle themselves; older ones need a high-contrast theme, which is not installed here. |
| **Dim inactive windows**<br>`dimInactive` `decoration:dim_inactive` | false | Darkens every window except the focused one, so the active window is unmistakable |
| **Dim amount**<br>`dimStrength` `decoration:dim_strength` | 0.5 | How much darker unfocused windows are. Range 0.05–0.9. |
| **Pointer size**<br>`cursorSize` | 24 px | Applies to the compositor and to applications. Range 16–64. |
| **Text size**<br>`textScale` | 1.0 | Scales interface text everywhere; 1.00 is the design size. Range 0.75–2.0. |
## appearance
Found on **Appearance**.
| Setting | Default | What it does |
|---|---|---|
| **Appearance**<br>`colorScheme` | dark | Light and dark share one identity, not two themes Choices: Dark, Light. |
| **Accent color**<br>`accentName` | blue | Drives the focused window border, the bar hairline, and every active state Choices: Prism blue, Orchid, Teal, Green, Amber, Orange, Rose, Slate. |
## capture
Found on **Screen Intelligence**.
| Setting | Default | What it does |
|---|---|---|
| **Screenshot folder**<br>`screenshotDir` | Pictures/Screenshots | Folder under your home directory for screenshots Choices: Pictures / Screenshots, Pictures, Desktop. |
| **Recording folder**<br>`recordingDir` | Videos/Recordings | Folder under your home directory for screen recordings Choices: Videos / Recordings, Videos, Desktop. |
| **Recording encoder**<br>`recorderArgs` | -c h264_vaapi -d /dev/dri/renderD128 | Hardware encoding keeps recording off the processor while gaming Choices: VAAPI H.264, VAAPI HEVC, CPU x264. |
## clock
Found on **Appearance**.
| Setting | Default | What it does |
|---|---|---|
| **24-hour time**<br>`use24Hour` | false | Use 18:30 instead of 6:30 PM |
| **Show seconds**<br>`showSeconds` | true | Keep a precise clock in the center of the bar |
| **Show weekday**<br>`showWeekday` | true | Include the abbreviated weekday before the date |
## display
Found on **Displays**.
| Setting | Default | What it does |
|---|---|---|
| **Game-aware HDR**<br>`autoHdr` `render:cm_auto_hdr` | true | Hand HDR to fullscreen games while the desktop stays SDR |
| **Variable refresh rate**<br>`vrrPolicy` `misc:vrr` | 3 | Matches the display's refresh rate to what is on screen Choices: Off, Always on, Fullscreen only, Fullscreen games. |
| **Direct scanout**<br>`directScanoutPolicy` `render:direct_scanout` | 2 | Lets fullscreen content bypass compositing Choices: Off, Always on, Automatic. |
## dock
Found on **Desktop & Dock**.
| Setting | Default | What it does |
|---|---|---|
| **Automatically hide the Dock**<br>`dockAutohide` | true | Reveal it at the bottom edge when a workspace is occupied |
| **Icon size**<br>`dockIconSize` | 48 px | How large the Dock's application icons are drawn. Range 32–80. |
| **Reveal delay**<br>`dockRevealDelayMs` | 0 ms | Zero reveals the Dock the instant the pointer reaches the edge. Range 0–1000. |
| **Hide delay**<br>`dockHideDelayMs` | 250 ms | Prevents flicker when crossing between icons. Range 0–2000. |
| **Pinned applications**<br>`dockPinned` | [ | Applications that stay in the Dock whether or not they are running |
## edges
Found on **Desktop & Dock**.
| Setting | Default | What it does |
|---|---|---|
| **Resize by dragging the border**<br>`resizeOnBorder` `general:resize_on_border` | true | Drag a window's edge to resize it, instead of only with the keyboard |
| **Border grab area**<br>`borderGrabArea` `general:extend_border_grab_area` | 15 px | How far outside the border still counts as grabbing it. Larger is easier to hit. Range 0–40. |
| **Show the resize cursor**<br>`hoverIconOnBorder` `general:hover_icon_on_border` | true | Change the pointer when it is over a resizable border |
| **Snap distance between windows**<br>`snapWindowGap` `general:snap:window_gap` | 10 px | How close two floating windows must be before they snap together. Range 0–60. |
| **Snap distance to screen edges**<br>`snapMonitorGap` `general:snap:monitor_gap` | 10 px | How close a floating window must be to an edge before it snaps to it. Range 0–60. |
| **Snapping respects gaps**<br>`snapRespectGaps` `general:snap:respect_gaps` | false | Snapped windows keep the configured gap instead of touching |
## effects
Found on **Appearance**.
| Setting | Default | What it does |
|---|---|---|
| **Blur**<br>`blurEnabled` `decoration:blur:enabled` | true | Blur the desktop behind translucent surfaces |
| **Blur radius**<br>`blurSize` `decoration:blur:size` | 8 | Larger is softer and costs more frame time. Range 1–20. |
| **Blur passes**<br>`blurPasses` `decoration:blur:passes` | 3 | More passes look smoother and cost more frame time. Range 1–5. |
| **Window shadows**<br>`shadowEnabled` `decoration:shadow:enabled` | true | Lift windows off the wallpaper with a soft shadow |
| **Shadow size**<br>`shadowRange` `decoration:shadow:range` | 20 px | How far the shadow spreads from the window edge. Range 0–60. |
| **Hard-edged shadow**<br>`shadowSharp` `decoration:shadow:sharp` | false | A crisp shadow instead of a soft falloff |
| **Shadow falloff**<br>`shadowRenderPower` `decoration:shadow:render_power` | 3 | How sharply the shadow fades out. Higher is tighter to the window. Range 1–4. |
| **Focus glow**<br>`glowEnabled` `decoration:glow:enabled` | true | A faint halo behind the focused window |
| **Glow size**<br>`glowRange` `decoration:glow:range` | 8 px | Kept small deliberately: the gradient border is the signature. Range 0–30. |
| **Animations**<br>`animationsEnabled` `animations:enabled` | true | Window, workspace, and panel motion |
## focus
Found on **Desktop & Dock**.
| Setting | Default | What it does |
|---|---|---|
| **Focus modes**<br>`focusModes` | [ | What quiets this machine, and what turns it on |
| **Focus session length**<br>`focusDurationMinutes` | 45 min | How long a focus session runs before it ends itself. Range 5–180. |
## gaming
Found on **gaming**.
| Setting | Default | What it does |
|---|---|---|
| **Use the performance power profile**<br>`gamingPerformanceProfile` | true | Switches while a game runs and switches back when it exits |
| **Say when Game Mode engages**<br>`gamingNotifyOnStart` | false | A notification when a game requests it, which is otherwise invisible |
## idle
Found on **Power & Lock**.
| Setting | Default | What it does |
|---|---|---|
| **Turn the screen off after**<br>`screenBlankMinutes` | 5 min | Blanks the display; nothing is locked yet. Range 0–120. |
| **Lock the screen after**<br>`lockMinutes` | 10 min | Counted from when the session went idle, not from blanking. Range 0–240. |
| **Suspend after**<br>`suspendMinutes` | 0 min | This is a desktop, so Panama ships with automatic suspend off. Range 0–480. |
| **Lock before sleeping**<br>`lockOnSleep` | true | Requires your password when the machine wakes |
## input
Found on **Keyboard**.
| Setting | Default | What it does |
|---|---|---|
| **Keyboard layout**<br>`keyboardLayout` `input:kb_layout` | us | XKB layout name, or a comma-separated list to switch between |
| **Layout variant**<br>`keyboardVariant` `input:kb_variant` | — | XKB variant, such as dvorak or colemak. Empty for the standard layout |
| **Keyboard options**<br>`keyboardOptions` `input:kb_options` | caps:escape_shifted_capslock | XKB options, such as compose:ralt to make right Alt a compose key |
| **Num Lock on login**<br>`numlockByDefault` `input:numlock_by_default` | true | Turn Num Lock on when the session starts |
| **Repeat delay**<br>`keyRepeatDelay` `input:repeat_delay` | 500 ms | How long a key is held before it starts repeating. Range 150–1000. |
| **Repeat rate**<br>`keyRepeatRate` `input:repeat_rate` | 33 /s | How many characters a second a held key produces. Range 5–100. |
## lockAppearance
Found on **Appearance**.
| Setting | Default | What it does |
|---|---|---|
| **Background**<br>`lockBackgroundMode` | screenshot | What appears behind the lock screen Choices: Blurred desktop, Current wallpaper, Solid color. |
| **Background blur**<br>`lockBlurLevel` | 3 | Softens what is behind the password field. Range 0–5. |
| **Show clock**<br>`lockShowClock` | true | Use the desktop's 12 or 24-hour format |
| **Show date**<br>`lockShowDate` | true | Show the weekday and full date |
| **Show user name**<br>`lockShowUser` | true | Identify the signed-in account |
| **Hide password field until typing**<br>`lockFadeOnEmpty` | false | Keep the empty field out of the way |
## master
Found on **Desktop & Dock**.
| Setting | Default | What it does |
|---|---|---|
| **Master area size**<br>`masterFactor` `master:mfact` | 0.55 | How much of the screen the master window takes. Range 0.1–0.9. |
| **Master area position**<br>`masterOrientation` `master:orientation` | left | Which side of the screen the master window occupies Choices: Left, Right, Top, Bottom, Center. |
| **New windows become**<br>`masterNewStatus` `master:new_status` | slave | Whether a new window takes the master area or joins the stack Choices: The master window, Part of the stack, Whatever the focused window is. |
| **Add new windows at the top**<br>`masterNewOnTop` `master:new_on_top` | false | New stack windows go above the others rather than below |
## multitasking
Found on **Desktop & Dock**.
| Setting | Default | What it does |
|---|---|---|
| **Tiling layout**<br>`windowLayout` `general:layout` | dwindle | Dwindle splits the focused window; master keeps one large window beside a stack Choices: Dwindle, Master and stack. |
| **Keep split direction**<br>`preserveSplit` `dwindle:preserve_split` | true | New windows follow the split of the window they replace, instead of always halving the longer side |
| **New windows open**<br>`forceSplit` `dwindle:force_split` | 0 | Where a new window lands relative to the one that was focused Choices: Where the pointer is, Always left or above, Always right or below. |
| **Snap floating windows**<br>`windowSnapping` `general:snap:enabled` | true | Floating windows stick to screen edges and to each other as you drag them |
| **Switch back and forth**<br>`workspaceBackAndForth` `binds:workspace_back_and_forth` | false | Selecting the workspace you are already on returns you to the previous one |
| **Wrap around at the ends**<br>`allowWorkspaceCycles` `binds:allow_workspace_cycles` | false | Moving past the last workspace continues from the first |
| **Let applications take focus**<br>`focusOnActivate` `misc:focus_on_activate` | false | An application asking for attention is switched to, rather than only highlighted |
| **Pointer changes active display**<br>`mouseMoveFocusesMonitor` `misc:mouse_move_focuses_monitor` | true | Moving the pointer to another display makes it the active one |
## nightLight
Found on **Displays**.
| Setting | Default | What it does |
|---|---|---|
| **Night Light**<br>`nightLightEnabled` | false | Shift the display warmer to reduce blue light |
| **Schedule automatically**<br>`nightLightAutomatic` | false | Turn Night Light on and off at the scheduled hours |
| **Color temperature**<br>`nightLightTemperature` | 3500 K | Lower is warmer. Range 2000–6500. |
| **Turns on at**<br>`nightLightFrom` | 17.0 | Only used when Night Light follows a schedule. Range 0–23.5. |
| **Turns off at**<br>`nightLightTo` | 10.0 | A time earlier than the start simply means the next morning. Range 0–23.5. |
## notices
Found on **Desktop & Dock**.
| Setting | Default | What it does |
|---|---|---|
| **Hyprland wallpaper**<br>`hyprlandLogo` `misc:disable_hyprland_logo` | false | The stock background Hyprland draws when no wallpaper is set |
| **Splash text**<br>`hyprlandSplash` `misc:disable_splash_rendering` | false | The line of text Hyprland renders over the stock background |
| **Update announcements**<br>`hyprlandUpdateNews` `ecosystem:no_update_news` | false | The window Hyprland opens after an update to describe what changed |
| **Donation reminders**<br>`hyprlandDonationNag` `ecosystem:no_donation_nag` | false | The prompt Hyprland shows twice a year asking for support |
## notifications
Found on **Notifications & Focus**.
| Setting | Default | What it does |
|---|---|---|
| **Notification duration**<br>`notificationTimeoutMs` | 5000 ms | How long ordinary notification banners remain visible. Range 1000–30000. |
| **Critical notification duration**<br>`notificationTimeoutCriticalMs` | 0 ms | Zero keeps critical notification banners visible until dismissed. Range 0–60000. |
| **Notification history**<br>`notificationHistoryLimit` | 100 | Maximum notifications retained in the notification center. Range 10–500. |
| **Visible banners**<br>`maxVisibleToasts` | 4 | Maximum notification banners shown at once. Range 1–8. |
## pointer
Found on **Mouse & Touchpad**.
| Setting | Default | What it does |
|---|---|---|
| **Pointer focus**<br>`followMouse` `input:follow_mouse` | 1 | What moving the pointer does to which window is focused Choices: Click to focus, Focus follows pointer, Pointer detached, Pointer fully separate. |
| **Pointer speed**<br>`pointerSensitivity` `input:sensitivity` | 0.0 | Zero is flat, unaccelerated response. Range -1.0–1.0. |
| **Hide pointer after**<br>`cursorInactiveTimeout` `cursor:inactive_timeout` | 4 s | Seconds of stillness before the pointer fades out; 0 never hides it. Range 0–60. |
| **Natural scrolling**<br>`naturalScroll` `input:natural_scroll` | false | Content follows the direction of your fingers, as on a phone |
| **Acceleration**<br>`accelProfile` `input:accel_profile` | flat | Flat moves the pointer the same distance however fast you move Choices: Flat, Adaptive. |
| **Scroll speed**<br>`scrollFactor` `input:scroll_factor` | 1.0 | Multiplies how far one notch of the wheel scrolls. Range 0.1–4.0. |
| **Left-handed**<br>`leftHanded` `input:left_handed` | false | Swap the primary and secondary buttons |
| **Middle-click paste**<br>`middleClickPaste` `misc:middle_click_paste` | true | Paste the primary selection in GTK and native Wayland applications |
## themes
Found on **Appearance**.
| Setting | Default | What it does |
|---|---|---|
| **Pointer theme**<br>`cursorTheme` | oreo_blue_cursors | The pointer design used by applications and Hyprland |
| **Application icons**<br>`iconTheme` | Adwaita | The icon set used by GTK applications |
## titlebar
Found on **Appearance**.
| Setting | Default | What it does |
|---|---|---|
| **Button side**<br>`titlebarButtonSide` | right | Place application titlebar buttons on the left or right Choices: Left, Right. |
| **Maximize button**<br>`titlebarMaximizeButton` | false | Show a maximize button in application titlebars that support it |
| **Double-click titlebar**<br>`titlebarDoubleClick` | toggle-maximize | Choose what a double-click on an application titlebar does Choices: Toggle maximize, Do nothing. |
## touchpad
Found on **Mouse & Touchpad**.
| Setting | Default | What it does |
|---|---|---|
| **Tap to click**<br>`touchpadTapToClick` `input:touchpad:tap-to-click` | true | A tap counts as a click without pressing down |
| **Natural scrolling**<br>`touchpadNaturalScroll` `input:touchpad:natural_scroll` | true | Content follows the direction of your fingers |
| **Disable while typing**<br>`touchpadDisableWhileTyping` `input:touchpad:disable_while_typing` | true | Ignore the touchpad briefly after a keystroke, so a palm cannot move the pointer |
| **Scroll speed**<br>`touchpadScrollFactor` `input:touchpad:scroll_factor` | 1.0 | Multiplies how far a two-finger scroll travels. Range 0.1–4.0. |
| **Drag lock**<br>`touchpadDragLock` `input:touchpad:drag_lock` | 0 | Keeps a tap-and-drag active when you lift a finger mid-drag Choices: Off, On, On, until you tap again. |
| **Middle-click by pressing both buttons**<br>`touchpadMiddleButtonEmulation` `input:touchpad:middle_button_emulation` | false | Pressing left and right together acts as a middle click |
## typography
Found on **Appearance**.
| Setting | Default | What it does |
|---|---|---|
| **Interface font**<br>`interfaceFont` | Adwaita Sans | Used for every piece of text in the shell |
| **Icon font**<br>`iconFont` | VictorMono Nerd Font | Draws the shell's glyphs, so it must be a Nerd Font |
| **Interface text size**<br>`interfaceFontSize` | 13 px | The base size the rest of the shell's type scales from. Range 10–18. |
| **Application font**<br>`applicationFont` | Adwaita Sans | Used by menus, controls, and labels in applications |
| **Application text size**<br>`applicationFontSize` | 11 pt | The base text size used by applications. Range 6–32. |
| **Document font**<br>`documentFont` | Adwaita Sans | Used for document content when an application follows the system choice |
| **Document text size**<br>`documentFontSize` | 12 pt | The default text size for document content. Range 6–32. |
| **Monospace font**<br>`monospaceFont` | VictorMono Nerd Font | Used by terminals, editors, and code fields that follow the system choice |
| **Monospace text size**<br>`monospaceFontSize` | 10 pt | The default text size for terminals and code. Range 6–32. |
| **Font hinting**<br>`fontHinting` | slight | How strongly text aligns to the pixel grid Choices: None, Slight, Medium, Full. |
| **Text smoothing**<br>`fontAntialiasing` | rgba | How application text softens its edges Choices: None, Grayscale, Subpixel. |
## vitals
Found on **Appearance**.
| Setting | Default | What it does |
|---|---|---|
| **Processor**<br>`showCpu` | true | Show processor usage beside the workspace indicator |
| **Memory**<br>`showMemory` | true | Show memory usage beside the workspace indicator |
| **Graphics**<br>`showGpu` | true | Show graphics usage beside the workspace indicator |
| **Vitals refresh**<br>`vitalsIntervalMs` | 2000 ms | How often processor, memory, and graphics usage update. Range 500–10000. |
## wallpaper
Found on **Appearance**.
| Setting | Default | What it does |
|---|---|---|
| **Wallpaper**<br>`wallpaperPath` | — | Shown on every output |
| **Wallpaper mode**<br>`wallpaperMode` | single | Use one image, rotate a collection, or choose per display Choices: Single, Slideshow, Per display. |
| **Change background every**<br>`wallpaperIntervalMinutes` | 30 min | Time between slideshow images. Range 5–1440. |
| **Shuffle**<br>`wallpaperShuffle` | true | Show every selected image before repeating |
## weather
Found on **Home**.
| Setting | Default | What it does |
|---|---|---|
| **Temperature unit**<br>`temperatureUnit` | fahrenheit | Choose Fahrenheit or Celsius for the weather card Choices: Fahrenheit, Celsius. |
| **Weather refresh**<br>`weatherRefreshMinutes` | 20 min | How often Panama updates the current conditions. Range 5–120. |
## windows
Found on **Appearance**.
| Setting | Default | What it does |
|---|---|---|
| **Inner gaps**<br>`gapsIn` `general:gaps_in` | 5 px | Space between neighboring tiled windows. Range 0–40. |
| **Outer gaps**<br>`gapsOut` `general:gaps_out` | 10 px | Space between the tiled area and the screen edge. Range 0–80. |
| **Border width**<br>`borderSize` `general:border_size` | 2 px | Thickness of the gradient border on the focused window. Range 0–10. |
| **Corner radius**<br>`windowRounding` `decoration:rounding` | 18 px | Matches the shell's popover radius so windows and panels agree. Range 0–40. |
| **Unfocused window opacity**<br>`inactiveOpacity` `decoration:inactive_opacity` | 1.0 | Fade windows that do not have focus. Range 0.5–1.0. |
| **Focused window opacity**<br>`activeOpacity` `decoration:active_opacity` | 1.0 | Fade even the focused window; 1.0 is fully opaque. Range 0.5–1.0. |
| **Fullscreen opacity**<br>`fullscreenOpacity` `decoration:fullscreen_opacity` | 1.0 | Applied instead of the focused opacity when a window is fullscreen. Range 0.5–1.0. |
| **Corner shape**<br>`roundingPower` `decoration:rounding_power` | 2.0 | 2 is a circular corner; higher values approach a squircle. Range 2.0–10.0. |
Reference in New Issue View Git Blame Copy Permalink