gib/Panama
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
13f3648e4d131b90fce028287350cb8ea3ab08b5
Panama/docs/settings.md
T
Gabriel Brown 3b01f1e020 Let the Dock choose an edge, choose its screens, and be dragged into order 
Three things that were parked, and the reasons they were parked turned out to be
the useful part of doing them.

The Dock can sit on the left or the right as well as the bottom. Everything that
assumed the bottom edge is now asked which edge it is on: the anchors, the axis
that gets an implicit size, the sliver of input region that survives hiding, the
direction the body slides away in, and which side a tooltip opens towards. The
body was a Row and is a Grid, because one declaration then serves both
orientations -- Row and Column would each need their own children, and the
cross-axis anchors that centre items in a Row are the wrong axis in a Column.

Bottom is unchanged in every particular, and the settings default to it, so a
hot reload in the middle of this work left the running dock exactly where it
was.

One bug worth recording because static review would never have found it: a dock
spans the edge it lives on, which means anchoring BOTH ends of that edge. The
first side dock anchored top and left only, was free to collapse to its implicit
height, and came out one pixel tall. It parsed, it loaded, and it rendered
nothing. The contract measures the geometry rather than reading the source for
that reason, and was verified by putting the single-ended anchor back.

Per-screen is a list of names where empty means every screen, because a list is
what goes stale when a display is unplugged and "all" should not be spelled as
one. Turning off the last screen collapses to "all" rather than leaving no dock
anywhere and no obvious way back.

Pins can be dragged by a grip. The objection this file recorded for a long time
was real -- dragging inside a Flickable inside a scrolling page fails in a way
that reads as breakage -- and the answer is preventStealing on the grip, so the
page cannot claim a gesture that started there. The arrow buttons stay: they are
the keyboard-reachable path and a grip is not. The order is held locally during
the drag and written once on release, rather than rewriting settings.json for
every slot crossed.

Claude-Session: https://claude.ai/code/session_01BRvzt4H8XXLPVH5MyYdk9L
2026-08-20 14:10:22 -04:00

331 lines
21 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.
133 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 |
| **Position**<br>`dockPosition` | bottom | Which edge the Dock lives on Choices: Bottom, Left, Right. |
| **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