From 5f60081169a8273a23a0c5736e1ec155c62737b0 Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Wed, 16 Jul 2025 08:53:03 +0530 Subject: [PATCH] Add more docs for the desktop-ui kitten --- docs/kittens/desktop-ui.rst | 102 ++++++++++++++++++++++++++++++++++-- 1 file changed, 98 insertions(+), 4 deletions(-) diff --git a/docs/kittens/desktop-ui.rst b/docs/kittens/desktop-ui.rst index 959b12cf1..35b9cc03d 100644 --- a/docs/kittens/desktop-ui.rst +++ b/docs/kittens/desktop-ui.rst @@ -14,8 +14,102 @@ provide parts of the desktop environment that are missing from such setups, and does so using keyboard friendly, terminal first UI components. Some of its features are: - * Replace the typical File Open/Save dialogs used in GUI programs with the - fast and keyboard centric :doc:`choose-files ` kitten - running in a semi-transparent kitty overlay. +* Replace the typical File Open/Save dialogs used in GUI programs with the + fast and keyboard centric :doc:`choose-files ` kitten + running in a semi-transparent kitty overlay. - * Allow simple command line based management of the desktop light/dark modes. +* Allow simple command line based management of the desktop light/dark modes. + + +How to install +------------------- + +.. note:: + + This kitten relies on the :doc:`panel kitten ` + under the hood to supply UI components. Check :ref:`the documentation ` + of that kitten to see if your window manager works with it. + +First, run:: + + kitten desktop-ui enable-portal + +Then, set the following two environment variables, *system wide*, that means in +:file:`/etc/environment` or the equivalent for your distribution:: + + QT_QPA_PLATFORMTHEME=xdgdesktopportal + GTK_USE_PORTAL=1 + + +Finally, reboot. Now, when you open a file dialog in most GUI applications, it +should open the :doc:`choose-files kitten ` instead +of a normal file open dialog. You can change the current light/dark mode of +your desktop by running:: + + kitten desktop-ui set-color-scheme dark + kitten desktop-ui set-color-scheme light + +Check the current value using:: + + dbus-send --session --print-reply --dest=org.freedesktop.portal.Desktop /org/freedesktop/portal/desktop org.freedesktop.portal.Settings.Read string:org.freedesktop.appearance string:color-scheme + +How it works +---------------- + +Modern Linux desktops have so called `portals +`__ that were +invented for sandboxed applications and provide various facilities to such +applications over DBUS, including file open dialogs, common desktop settings, +etc. This kitten works by implementing a backend for some of these services. + +Normal GUI applications can then be told to make use of these services, thereby +allowing us to replace parts of the desktop experience as needed. + +There are multiple competing implementations of the backends. Each desktop +environment like KDE or GNOME has it's own backend and many window managers +provide implementations for some backends as well. Service discovery and +configuring which backend to use happens via the :file:`xdg-desktop-portal` +program, usually found at :file:`/usr/lib/xdg-desktop-portal`. + +It can be configured by files in :file:`~/.local/share/xdg-desktop-portal`. See +`man portals.conf `__. The +``kitten desktop-ui enable-portal`` command takes care of the setup for you +automatically. If you want to customize exactly which services to use this +kitten for, run the command and then edit the conf file that the command says +it has patched. + + +Troubleshooting +------------------- + +First, ensure that DBUS is able to auto-start the kitten when it is needed. If +the kitten is not already running, try the following command:: + + dbus-send --session --print-reply --dest=org.freedesktop.impl.portal.desktop.kitty \ + /net/kovidgoyal/kitty/portal org.freedesktop.DBus.Properties.GetAll \ + string:net.kovidgoyal.kitty.settings + +If DBUS is able to start the kitten or if it is already running it will print +out the version property, otherwise it will fail with an error. If it fails, +check the file +:file:`.local/share/dbus-1/services/org.freedesktop.impl.portal.desktop.kitty.service` +that should have been created by the ``enable-portal`` command. It's ``Exec`` +key must point to the full path to the kitten executable. + +Next, check that the XDG portal system is actually using this kitten for its +settings backend. Run:: + + dbus-send --session --print-reply --dest=org.freedesktop.portal.Desktop \ + /org/freedesktop/portal/desktop org.freedesktop.portal.Settings.Read \ + string:net.kovidgoyal.kitty string:status + +If this returns a reply then the kitten is being used, as expected. If it +returns a not found error, then some other backend is being used for settings. + +Read the ``portals.conf`` man page and run:: + + /usr/lib/xdg-desktop-portal -r v + +this will output a lot of debug information, which should tell you which +backend is chosen for which service. Read the debug output carefully to +determine why the kitten is not being selected.