kitty/docs/kittens/panel.rst

Draw a GPU accelerated dock panel on your desktop
====================================================================================================

.. highlight:: sh

.. only:: man

    Overview
    --------------

.. include:: ../quake-screenshots.rst

Draw the desktop wallpaper or docks and panels using arbitrary
terminal programs, For example, have `btop
<https://github.com/aristocratos/btop>`__ or `cava
<https://github.com/karlstav/cava/>`__ be your desktop wallpaper.

It is useful for showing status information or notifications on your desktop
using terminal programs instead of GUI toolkits.


The screenshot to the side shows some uses of the panel kitten to draw various
desktop components such as the background, a quick access floating terminal and
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)

.. versionadded:: 0.34.0

   Support for Wayland. See :ref:`below <panel_wayland_status>` 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'

This will show ``Hello, world.`` at the top edge of your screen for five
seconds. Here, the terminal program we are running is :program:`sh` with a script
to print out ``Hello, world!``. You can make the terminal program as complex as
you like, as demonstrated in the screenshots.

If you are on Wayland or macOS, you can, for instance, run::

    kitten panel --edge=background htop

to display ``htop`` as your desktop background. Remember this works in everything
but GNOME and also, in sway, you have to disable the background wallpaper as
sway renders that over the panel kitten surface.

There are projects that make use of this facility to implement generalised
panels and desktop components:

.. _panel_projects:

    * `kitty panel <https://github.com/5hubham5ingh/kitty-panel>`__
    * `pawbar <https://github.com/codelif/pawbar>`__


.. _remote_control_panel:

Controlling panels via remote control
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can control panels via the kitty :doc:`remote control </remote-control>` facility. Create a panel
with remote control enabled::

    kitten panel -o allow_remote_control=socket-only --lines=2 \
        --listen-on=unix:/tmp/panel kitten run-shell


Now you can control this panel using remote control, for example to show/hide
it, use::

    kitten @ --to=unix:/tmp/panel resize-os-window --action=toggle-visibility

To move the panel to the bottom of the screen and increase its height::

    kitten @ --to=unix:/tmp/panel resize-os-window --action=os-panel \
        --incremental edge=bottom lines=4

To create a new panel running the program top, in the same instance
(like creating a new OS window)::

    kitten @ --to=unix:/tmp/panel launch --type=os-panel --os-panel edge=top \
        --os-panel lines=8 top


.. include:: ../generated/cli-kitten-panel.rst


.. _quake_ss:

How the screenshots were generated
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The system statistics in the background were created using::

    kitten panel --edge=background -o background_opacity=0.2 -o background=black btop

This creates a kitty background window and inside it runs the `btop
<https://github.com/aristocratos/btop>`__ program to display the statistics.

The floating quick access window was created by running::

    kitten quick-access-terminal kitten run-shell \
       zsh -c 'printf "\e]66;s=4;Quick access kitty in Hyprland\a\n\n\n\nAlso uses kitty to draw desktop background\n"'

This starts the quick access window and inside it runs ``kitten run-shell``, which
in turn first runs ``zsh`` to print out the message and then starts the users login
shell.

The Linux dock panel was::

    kitten panel kitty +launch my-panel.py

This creates the panel window and runs the ``my-panel.py`` script inside it
using the Python interpreter that comes bundled with kitty. Unfortunately the
actual script is not public, but there are :ref:`public projects implementing
general purpose panels using kitty <panel_projects>`.


.. _panel_wayland_status:

Wayland compositor status
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Below is a list of the status of various Wayland compositors. The panel kitten
relies of the `wlr layer shell protocol
<https://wayland.app/protocols/wlr-layer-shell-unstable-v1#compositor-support>`__,
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

**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.

GNOME (mutter) 🔴
    Does not implement the wlr protocol at all, nothing works.

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.