From f4610390177df8e3752a903182713c0794d3240a Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Thu, 1 May 2025 21:48:27 +0530 Subject: [PATCH] Modify docs in light of X11 support --- docs/kittens/panel.rst | 81 +++++++++++++------------- docs/kittens/quick-access-terminal.rst | 3 +- kitty/simple_cli_definitions.py | 9 ++- 3 files changed, 45 insertions(+), 48 deletions(-) diff --git a/docs/kittens/panel.rst b/docs/kittens/panel.rst index cb4bfac74..fb11bca56 100644 --- a/docs/kittens/panel.rst +++ b/docs/kittens/panel.rst @@ -25,20 +25,14 @@ a dock panel showing system information (Linux only). .. versionadded:: 0.42.0 - Support for macOS (the edge based panels do not prevent other windows from - floating over them because of limitations in Cocoa, but background and - overlay panels work well) + Support for macOS, see :ref:`compatibility matrix ` for details. + and X11 (background and overlay). .. versionadded:: 0.34.0 - Support for Wayland. See :ref:`below ` for which + Support for Wayland. See :ref:`below ` for which Wayland compositors work. -.. note:: - - On X11, only the ``top`` and ``bottom`` panels are widely supported, - the other types depend on the window manager used. - Using this kitten is simple, for example:: kitten panel sh -c 'printf "\n\n\nHello, world."; sleep 5s' @@ -128,44 +122,49 @@ actual script is not public, but there are :ref:`public projects implementing general purpose panels using kitty `. -.. _panel_wayland_status: +.. _panel_compat: -Wayland compositor status -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. tab:: Wayland -Below is a list of the status of various Wayland compositors. The panel kitten -relies of the `wlr layer shell protocol -`__, -which is technically supported by almost all Wayland compositors, but the -implementation in some of them is quite buggy. + Below is a list of the status of various Wayland compositors. The panel kitten + relies of the `wlr layer shell protocol + `__, + which is technically supported by almost all Wayland compositors, but the + implementation in some of them is quite buggy. -🟢 **Hyprland** - Fully working, no known issues + 🟢 **Hyprland** + Fully working, no known issues -🟢 **KDE** (kwin) - Fully working, no known issues + 🟢 **KDE** (kwin) + Fully working, no known issues -🟠 **Sway** - Partially working. Issues include: - * Renders its configured background over the background window instead of - under it. This is likely because it uses the wlr protocol for - backgrounds itself. - * Hiding a dock panel (unmapping the window) does not release the space - used by the dock. + 🟠 **Sway** + Partially working. Issues include: + * Renders its configured background over the background window instead of + under it. This is likely because it uses the wlr protocol for + backgrounds itself. + * Hiding a dock panel (unmapping the window) does not release the space + used by the dock. -🟠 niri - Breaks when hiding (unmapping) layer shell windows. This means the quick - access terminal is non-functional, but background and dock panels work. - More technically, keyboard focus gets stuck in the hidden window and when trying - to remap the hidden window niri never sends configure events for the remapped surface. + 🟠 **niri** + Breaks when hiding (unmapping) layer shell windows. This means the quick + access terminal is non-functional, but background and dock panels work. + More technically, keyboard focus gets stuck in the hidden window and when trying + to remap the hidden window niri never sends configure events for the remapped surface. -🟠 labwc - Breaks when hiding (unmapping) layer shell windows. This means the quick - access terminal is non-functional, but background and dock panels work. - More technically, when unmapping the surface (attaching a NULL buffer to - it) labwc continues to send configure events to the unmapped surface, - leading to Wayland protocol errors and a crash of labwc. + 🟠 **labwc** + Breaks when hiding (unmapping) layer shell windows. This means the quick + access terminal is non-functional, but background and dock panels work. + More technically, when unmapping the surface (attaching a NULL buffer to + it) labwc continues to send configure events to the unmapped surface, + leading to Wayland protocol errors and a crash of labwc. -🔴 GNOME (mutter) - Does not implement the wlr protocol at all, nothing works. + 🔴 **GNOME** (mutter) + Does not implement the wlr protocol at all, nothing works. + +.. tab:: macOS + + Mostly everything works, with the notable exception that dock panels do not + prevent other windows form covering them. This is because Apple does not + provide and way to do this in their APIs. diff --git a/docs/kittens/quick-access-terminal.rst b/docs/kittens/quick-access-terminal.rst index 9ddfd2523..6bc389da7 100644 --- a/docs/kittens/quick-access-terminal.rst +++ b/docs/kittens/quick-access-terminal.rst @@ -14,8 +14,7 @@ Make a Quake like quick access terminal .. include:: ../quake-screenshots.rst .. versionadded:: 0.42.0 - Works on macOS and Wayland, see :ref:`here for Wayland compositor support - status `. + See :ref:`here for what platforms it works on `. This kitten can be used to make a quick access terminal, that appears and disappears at a key press. To do so use the following command: diff --git a/kitty/simple_cli_definitions.py b/kitty/simple_cli_definitions.py index 8baa05039..cbac502fb 100644 --- a/kitty/simple_cli_definitions.py +++ b/kitty/simple_cli_definitions.py @@ -597,10 +597,9 @@ choices=top,bottom,left,right,background,center,none default={edge} Which edge of the screen to place the panel on. Note that some window managers (such as i3) do not support placing docked windows on the left and right edges. -The value :code:`background` means make the panel the "desktop wallpaper". This -is not supported on X11 and note that when using sway if you set -a background in your sway config it will cover the background drawn using this -kitten. +The value :code:`background` means make the panel the "desktop wallpaper". +Note that when using sway if you set a background in your sway config it will +cover the background drawn using this kitten. Additionally, there are two more values: :code:`center` and :code:`none`. The value :code:`center` anchors the panel to all sides and covers the entire display (on macOS the part of the display not covered by titlebar and dock). @@ -655,7 +654,7 @@ default={focus_policy} On a Wayland compositor that supports the wlr layer shell protocol, specify the focus policy for keyboard interactivity with the panel. Please refer to the wlr layer shell protocol documentation for more details. Note that different Wayland compositors behave very differently with :code:`exclusive`, your mileage may vary. -On macOS, :code:`exclusive` and :code:`on-demand` are currently the same. Ignored on X11. +On macOS, :code:`exclusive` and :code:`on-demand` are currently the same. --hide-on-focus-loss