Desktop settings

A practical guide to the settings center: change the look, shape your workspaces, choose default applications, and understand which controls belong to your host desktop.

# Use your preferred applications
ludashctl default-apps '{"terminal":["konsole","-e","fish"],"files":["dolphin"]}'

# Restore Dolphin and Kitty
ludashctl default-apps '{"terminal":[],"files":[]}'
ludashctl launch-default terminal

Software updates

About shows one current update status, the running version and the latest version checked on the selected channel. Installation progress appears only while an update is running. Previous installation results stay in a separate history section. A completed installation asks for a restart during the current session and prevents reinstalling the same target; old records no longer hide new checks after restarting. Switch between stable releases and development commits, then check for updates. A tag such as 1.2.0-rc1 is compared as a pre-release, not as the final release.

The built-in plugin manager and LunaDash file chooser share the desktop palette, rounded controls, font, and accent settings. Their opaque widget surfaces follow appearance changes while open; applications using a different file chooser retain their own styling.

The Plugins Store reads the reviewed index.json from LunaDash-Plugins. The shell shows the bundled registry if the HTTPS refresh fails; appearing in the Store does not install or enable native code automatically.

The running desktop keeps its current QML configuration during package updates. Log out and back in, or reboot, to load the complete updated shell.

Background updates handle package confirmation automatically. Administrator approval remains a separate step: About shows “Waiting for authorization” before installation and lets the system dialog receive focus. LunaDash starts an installed KDE, LXQt, or GNOME polkit agent for login and updates; Arch installation includes polkit-kde-agent. If no desktop authentication agent is available, the update reports an error so you can use the installer from a terminal.

Display and startup

Display settings control an available backlight through brightnessctl, provide a separate DDC/CI brightness slider for each compatible external monitor through ddcutil, and expose the primary output's supported resolution, refresh rate and scale. Confirm a new display configuration within 15 seconds or it reverts automatically. Nested sessions keep physical monitor modes under the host desktop's control; external brightness controls require DDC/CI enabled in the monitor menu and permission to access its I2C device. Refresh monitors after reconnecting a display or changing permissions.

The desktop shows an animated LunaDash startup screen while its initial state and wallpaper load, with a minimum visible interval counted from the first rendered frame. Shell startup no longer waits for portal theme queries. Installed sessions use their installed interface files. Translated controls adapt to the available width. Hidden panels load on demand and native window effects follow output frame callbacks. These changes still need hardware checks for physical display switching and actual FPS.

Window animations

All normal tiles stay within one screen. New profiles use 12 px gaps and a consistent centered size for a lone tiled window; adding windows grows that state into the persistent split tree. Dropping, swapping or grouping animates the affected tiles into position. Relayout snapshots fill the interpolated tile while the live client cross-fades in earlier, avoiding the late resize pop from the previous transition. Alt+Tab shows a 2×5 overview of workspaces 1–10; hovering a cell selects it immediately and clicking only confirms the switch.

In Appearance settings, use Animations and Animation duration to adjust motion. The default is 220 ms. Turning animations off applies changes immediately. Effects follow the display's frame callbacks, and resizing does not repeatedly relayout the application on every frame.

Application compatibility

Native application menus keep their pointer grab without repeated focus updates on each click. Discord's input helper also needs an X11 connection while its main window uses Wayland. Launch Discord through LunaDash's application menu so the authenticated XWayland service is ready; its helper root stays hidden. Direct terminal launches bypass this preparation. The Discord-only software rendering fallback remains available, but GPU flags alone cannot fix the helper's missing connection.

Tap Meta by itself to open application search immediately. Meta+key shortcuts remain available because the launcher opens only when Meta is released without another key. The Dashboard changes tabs on hover and automatically closes after the pointer leaves its surface. The status area also exposes session-only text clipboard history: choose an entry to copy it again or clear the history. Entries are kept under $XDG_RUNTIME_DIR/lunadash, not persisted in the home configuration.

Taskbar icons follow application IDs and installed desktop entries. Changing a document or tab title does not change the app icon. Selecting a task restores its window, changes workspace when needed and focuses its tile. Tasks are grouped into workspace capsules without numeric badges. The active workspace is brighter and the other capsules use a darker shade; every window remains individually selectable. Selecting a tiled task maximizes it and hides the other windows in its workspace. They remain in the taskbar. Click the active task again or press Super+F to restore the saved tiling arrangement. Each Alt+Tab cell represents a whole workspace and shows its current visible window arrangement.

File dialogs require xdg-desktop-portal and xdg-desktop-portal-gtk alongside the LunaDash backend. Hardware and full Discord compatibility still need real-session verification.

Select a screenshot region

Press Meta+Shift+S, drag a rectangle and release to save it to Pictures/Screenshots. Escape cancels. Install grim and slurp for this feature. The control command lunadashctl screenshot starts selection asynchronously; capture /absolute/path.png retains full-output capture for automation.

The selection overlay opens immediately. Pressing the shortcut again keeps the current selection, and Escape closes it without saving a file or showing an error. After updating the compositor, log out and back in to use the corrected shortcut behavior.

Where preferences live

Desktop settings use ~/.config/LuDash/LuDash.conf, respecting XDG_CONFIG_HOME. Shell module JSON lives beside it as shell-modules.json. Custom QML belongs in the sibling modules/ directory. Module code is disabled until explicitly trusted.

ludashctl appearance '{"accent":"#c4b5fd","gap":16,"blur":true,"blurRadius":18}'
ludashctl open-settings appearance

Each block can also have its own dimensions, color and corner radius. Follow the module guide for the JSON schema, user QML and recovery commands.

Dolphin and file selection

Files shortcuts open Dolphin by default. Settings can select another installed file manager. The former built-in file manager and private file-operation engine have been removed. Dolphin manages its own theme, file operations and MIME preferences.

LunaDash retains its portal file picker, Settings image picker and screen/window sharing chooser. Compositor opacity and frosted-glass controls apply to ordinary Dolphin windows.

Media

The Media tab combines a circular album cover, lyrics, playback controls and a player selector. Choose a player or follow the currently playing source. Seeking, volume, shuffle and repeat follow each player's supported capabilities. Lyrics come from the player or a local LRC file; applications need MPRIS support to appear.