Add border decorations

CHANGELOG

@@ -1,3 +1,4 @@
+2024-05-09: [FEATURE] Add window border decorations (NB experimental)
 2024-04-26: [FEATURE] Add hooks to `ALSAWidget` and `PulseVolumeExtra`
 2024-04-25: [FEATURE] Add ability to drag `PopupSlider` and `PopupCircularProgress` controls (NB experimental)
 2024-04-25: [BREAKING CHANGE] Update to using lazy calls in popups. Needs latest qtile.

docs/index.rst

@@ -22,6 +22,7 @@ There's a :ref:`mixin <tooltip-mixin>` if you want to add tooltips to widgets.
 I've also added some "eye candy" in the form of:
 
   - :ref:`Widget Decorations <widget-decorations>`
+  - :ref:`Window Border Decorations <border-decorations>`
   - :ref:`Wallpapers <wallpapers>`
 
 Lastly, I've created a new ``ImgMask`` class which, rather than drawing the source image,
@@ -44,6 +45,7 @@ without needing to recrate the icons themselves. You can see the class :ref:`her
     manual/install
     manual/how_to/popup
     manual/how_to/decorations
+    manual/how_to/borders
     manual/how_to/img-mask
     manual/how_to/tooltips
 
@@ -56,6 +58,7 @@ without needing to recrate the icons themselves. You can see the class :ref:`her
     manual/ref/hooks
     manual/ref/popup
     manual/ref/decorations
+    manual/ref/borders
     manual/ref/imgmask
 
 .. toctree::

docs/manual/how_to/borders.rst

@@ -0,0 +1,51 @@
+.. _border-decorations:
+
+=========================
+Window Border Decorations
+=========================
+
+.. warning::
+
+    This feature is experimental.
+
+    The decorations may behave unexpectedly, have missing features and will
+    probably crash at some point!
+
+    Feedback on any issues would be appreciated.
+
+Window border decorations provide the ability to have different style borders
+rather than the standard single, solid colour borders.
+
+The following decorations are available:
+
+.. list_objects:: qtile_extras.layout.decorations
+    :baseclass: qtile_extras.layout.decorations.borders._BorderStyle
+
+Using the decorations is simple:
+
+.. code:: python
+
+    from qtile_extras.layout.decorations import GradientBorder
+
+    ...
+
+    layouts = [
+        layout.Max(
+            border_width=10,
+            margin=5,
+            border_focus=GradientBorder(colours=["00f", "0ff"])
+        ),
+        ...
+    ]
+
+Results in a window looking like this:
+
+.. image:: /_static/images/max_gradient_border.png
+
+See :ref:`this page<ref-borders>` for details of the various borders available.
+
+.. important::
+
+    You must import the decorations from ``qtile_extras.layout.decorations`` as importing
+    this file will add a hook to inject the code needed to allow qtile to render these
+    borders.

docs/manual/ref/borders.rst

@@ -0,0 +1,20 @@
+.. _ref-borders:
+
+=========================
+Window Border Decorations
+=========================
+
+.. warning::
+
+    This feature is experimental.
+
+    The decorations may behave unexpectedly, have missing features and will
+    probably crash at some point!
+
+    Feedback on any issues would be appreciated.
+
+.. qtile_module:: qtile_extras.layout.decorations.borders
+    :baseclass: qtile_extras.layout.decorations.borders._BorderStyle
+    :exclude-base:
+    :no-commands:
+    :show-config:

qtile_extras/layout/__init__.py

@@ -0,0 +1,20 @@
+# Copyright (c) 2024 elParaguayo
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+from libqtile.layout import *  # noqa: F401, F403

qtile_extras/layout/decorations/__init__.py

@@ -0,0 +1,52 @@
+# Copyright (c) 2024 elParaguayo
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+from libqtile import hook
+
+from qtile_extras.layout.decorations.borders import (  # noqa: F401
+    GradientBorder,
+    GradientFrame,
+    ScreenGradientBorder,
+)
+
+
+# We need to inject code into qtile to allow the windows to render the new
+# decorations. To simplify this, we can use a hook so it's invisible to
+# users.
+@hook.subscribe.startup_once
+def inject_border_methods():
+    from libqtile import qtile
+
+    if qtile.core.name == "wayland":
+        from libqtile.backend.wayland.window import Window
+
+        from qtile_extras.layout.decorations.injections import (
+            wayland_paint_borders,
+            wayland_window_init,
+        )
+
+        Window.__init__ = wayland_window_init
+        Window.paint_borders = wayland_paint_borders
+
+    else:
+        from libqtile.backend.x11.window import XWindow
+
+        from qtile_extras.layout.decorations.injections import x11_paint_borders
+
+        XWindow.paint_borders = x11_paint_borders