From 983e570bbe1d6bffa7b621d43725cca9eb6c76a2 Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Wed, 23 Apr 2025 20:52:11 +0530 Subject: [PATCH] Update docs to note that macOS is supported by the panel kitten as well --- docs/kittens/panel.rst | 20 ++++++++++++-------- kittens/panel/main.py | 23 ++++++++++++++--------- 2 files changed, 26 insertions(+), 17 deletions(-) diff --git a/docs/kittens/panel.rst b/docs/kittens/panel.rst index 3609ff804..b4c29c252 100644 --- a/docs/kittens/panel.rst +++ b/docs/kittens/panel.rst @@ -14,7 +14,8 @@ screen or as the desktop wallpaper, that shows the output from an arbitrary terminal program. It is useful for showing status information or notifications on your desktop -using terminal programs instead of GUI toolkits. +using terminal programs instead of GUI toolkits. It can also be used for a +:ref:`Quake like quick access terminal`. .. figure:: ../screenshots/panel.png :alt: Screenshot, showing a sample panel @@ -28,15 +29,18 @@ The screenshot above shows a sample panel that displays the current desktop and window title as well as miscellaneous system information such as network activity, CPU load, date/time, etc. -.. versionadded:: 0.34.0 - Support for Wayland +.. versionadded:: 0.42.0 + Support for macOS and support for Wayland was added in 0.34.0 .. note:: - This kitten currently only works on X11 desktops and Wayland compositors + This kitten currently only works on macOS and Wayland compositors that support the `wlr layer shell protocol `__ - (which is almost all of them except the, as usual, crippled GNOME). + (which is almost all of them except GNOME). On macOS the panels do not + prevent other windows from floating over them because of limitations in + Cocoa. 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:: @@ -47,11 +51,11 @@ seconds. Here, the terminal program we are running is :program:`sh` with a scrip to print out ``Hello, world!``. You can make the terminal program as complex as you like, as demonstrated in the screenshot above. -If you are on Wayland, you can, for instance run:: +If you are on Wayland or macOS, you can, for instance run:: kitty +kitten panel --edge=background htop -to display htop as your desktop background. Remember this works in everything +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. @@ -68,7 +72,7 @@ Make a Quake like quick access terminal ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. versionadded:: 0.42.0 - Support for quake mode, works only on Wayland, except for GNOME. + Support for quake mode, works only on macOS and Wayland, except for GNOME. 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/kittens/panel/main.py b/kittens/panel/main.py index 43121d8d9..7e60e129e 100644 --- a/kittens/panel/main.py +++ b/kittens/panel/main.py @@ -50,28 +50,28 @@ If it has the suffix :code:`px` then it sets the width of the panel in pixels in type=int default=0 Set the top margin for the panel, in pixels. Has no effect for bottom edge panels. -Only works on a Wayland compositor that supports the wlr layer shell protocol. +Only works on macOS and Wayland compositors that supports the wlr layer shell protocol. --margin-left type=int default=0 Set the left margin for the panel, in pixels. Has no effect for right edge panels. -Only works on a Wayland compositor that supports the wlr layer shell protocol. +Only works on macOS and Wayland compositors that supports the wlr layer shell protocol. --margin-bottom type=int default=0 Set the bottom margin for the panel, in pixels. Has no effect for top edge panels. -Only works on a Wayland compositor that supports the wlr layer shell protocol. +Only works on macOS and Wayland compositors that supports the wlr layer shell protocol. --margin-right type=int default=0 Set the right margin for the panel, in pixels. Has no effect for left edge panels. -Only works on a Wayland compositor that supports the wlr layer shell protocol. +Only works on macOS and Wayland compositors that supports the wlr layer shell protocol. --edge @@ -85,10 +85,11 @@ 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) by default. -The panel can be shrunk using the margin parameters. +display (on macOS the part of the display not covered by titlebar and dock). +The panel can be shrunk and placed using the margin parameters. The value :code:`none` anchors the panel to the top left corner and should be -placed and sized using the margin parameters. +placed and using the margin parameters. It's size is set bye :option:`--lines` +and :option:`--columns`. --layer @@ -96,7 +97,8 @@ choices=background,bottom,top,overlay default=bottom On a Wayland compositor that supports the wlr layer shell protocol, specifies the layer on which the panel should be drawn. This parameter is ignored and set to -:code:`background` if :option:`--edge` is set to :code:`background`. +:code:`background` if :option:`--edge` is set to :code:`background`. On macOS, maps +these to appropriate NSWindow *levels*. --config -c @@ -133,6 +135,7 @@ choices=not-allowed,exclusive,on-demand default=not-allowed 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. +Ignored on X11 and macOS. --exclusive-zone @@ -143,12 +146,14 @@ Please refer to the wlr layer shell documentation for more details on the meanin If :option:`--edge` is set to anything other than :code:`center` or :code:`none`, this flag will not have any effect unless the flag :option:`--override-exclusive-zone` is also set. If :option:`--edge` is set to :code:`background`, this option has no effect. +Ignored on X11 and macOS. --override-exclusive-zone type=bool-set On a Wayland compositor that supports the wlr layer shell protocol, override the default exclusive zone. This has effect only if :option:`--edge` is set to :code:`top`, :code:`left`, :code:`bottom` or :code:`right`. +Ignored on X11 and macOS. --single-instance -1 @@ -185,7 +190,7 @@ For internal debugging use. args = PanelCLIOptions() -help_text = 'Use a command line program to draw a GPU accelerated panel on your X11 desktop' +help_text = 'Use a command line program to draw a GPU accelerated panel on your desktop' usage = '[cmdline-to-run ...]'