docstrings and comments

qtile · Apr 13, 2024 · c05cec8 · c05cec8
1 parent 1414641
commit c05cec8
Show file tree

Hide file tree

Showing 2 changed files with 85 additions and 4 deletions.
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,5 +1,7 @@
 Qtile x.xx.x, released XXXX-XX-XX:
     * features
+      - Add `Plasma` layout. The original layout (https://github.com/numirias/qtile-plasma) appears to be unmaintained
+        so we have added this to the main codebase.
     * bugfixes
 
 Qtile 0.25.0, released 2024-04-06:

diff --git a/libqtile/layout/plasma.py b/libqtile/layout/plasma.py
@@ -127,6 +127,7 @@ def __repr__(self):
             info += " +%d" % len(self)
         return "<Node %s %x>" % (info, id(self))
 
+    # Define dunder methods to treat Node objects like an iterable
     def __contains__(self, node):
         if node is self:
             return True
@@ -150,8 +151,10 @@ def __len__(self):
     @property
     def root(self):
         try:
+            # Walk way down treet until we find root
             return self.parent.root
         except AttributeError:
+            # Node has no parent (it's None) so node must be root
             return self
 
     @property
@@ -339,8 +342,9 @@ def bottom_right(self):
 
     @property
     def pixel_perfect(self):
-        """Return pixel-perfect int dimensions (x, y, width, height) which
-        compensate for gaps in the layout grid caused by plain int conversion.
+        """
+        Return pixel-perfect int dimensions (x, y, width, height) which
+        compensate for gaps in the layout grid caused by plain int conversions.
         """
         x, y, width, height = self.x, self.y, self.width, self.height
         threshold = 0.99999
@@ -447,7 +451,8 @@ def reset_size(self):
 
     @property
     def flexible(self):
-        """A node is flexible if its size isn't (explicitly or implictly)
+        """
+        A node is flexible if its size isn't (explicitly or implictly)
         determined.
         """
         if self.fixed:
@@ -728,13 +733,80 @@ def find_payload(self, payload):
 
 
 class Plasma(Layout):
-    """A flexible tree-based layout.
+    """
+    A flexible tree-based layout.
 
     Each tree node represents a container whose children are aligned either
     horizontally or vertically. Each window is attached to a leaf of the tree
     and takes either a calculated relative amount or a custom absolute amount
     of space in its parent container. Windows can be resized, rearranged and
     integrated into other containers.
+
+    Windows in a container will all open in the same direction. Calling
+    ``lazy.layout.mode_vertical/horizontal()`` will insert a new container allowing
+    windows to be added in the new direction.
+
+    Windows can be focused selectively by using ``lazy.layout.up/down/left/right()`` to focus
+    the nearest window in that direction relative to the currently focused window.
+
+    "Integrating" windows is best explained with an illustation. Starting with three
+    windows, a, b, c. b is currently focused. Calling ``lazy.layout.integrate_left()``
+    will have the following effect:
+
+    ::
+
+        ----------------------         ----------------------
+        | a    | b    | c    |         | a        | c       |
+        |      |      |      |         |          |         |
+        |      |      |      |  -->    |          |         |
+        |      |      |      |         |----------|         |
+        |      |      |      |         | b        |         |
+        |      |      |      |         |          |         |
+        |      |      |      |         |          |         |
+        ----------------------         ----------------------
+
+    Finally, windows can me moved around the layout with ``lazy.layout.move_up/down/left/right()``.
+
+    Example keybindings:
+
+    .. code:: python
+
+        from libqtile.command import lazy
+        from libqtile.config import EzKey
+        ...
+        keymap = {
+            'M-h': lazy.layout.left(),
+            'M-j': lazy.layout.down(),
+            'M-k': lazy.layout.up(),
+            'M-l': lazy.layout.right(),
+            'M-S-h': lazy.layout.move_left(),
+            'M-S-j': lazy.layout.move_down(),
+            'M-S-k': lazy.layout.move_up(),
+            'M-S-l': lazy.layout.move_right(),
+            'M-A-h': lazy.layout.integrate_left(),
+            'M-A-j': lazy.layout.integrate_down(),
+            'M-A-k': lazy.layout.integrate_up(),
+            'M-A-l': lazy.layout.integrate_right(),
+            'M-d': lazy.layout.mode_horizontal(),
+            'M-v': lazy.layout.mode_vertical(),
+            'M-S-d': lazy.layout.mode_horizontal_split(),
+            'M-S-v': lazy.layout.mode_vertical_split(),
+            'M-a': lazy.layout.grow_width(30),
+            'M-x': lazy.layout.grow_width(-30),
+            'M-S-a': lazy.layout.grow_height(30),
+            'M-S-x': lazy.layout.grow_height(-30),
+            'M-C-5': lazy.layout.size(500),
+            'M-C-8': lazy.layout.size(800),
+            'M-n': lazy.layout.reset_size(),
+        }
+        keys = [EzKey(k, v) for k, v in keymap.items()]
+
+    Acknowledgements:
+    This layout was developed by numirias and published at
+    https://github.com/numirias/qtile-plasma A few minor amendments have been made
+    to that layout as part of incorporating this into the main qtile codebase but the
+    majority of the work is theirs.
+
     """
 
     defaults = [
@@ -746,6 +818,12 @@ class Plasma(Layout):
         ("border_width", 1, "Border width"),
         ("border_width_single", 0, "Border width for single window"),
         ("margin", 0, "Layout margin"),
+        (
+            "fair",
+            False,
+            "When ``False`` effort will be made to preserve nodes with a fixed size. "
+            "Set to ``True`` to enable new windows to take more space from fixed size nodes.",
+        ),
     ]
     # If windows are added before configure() was called, the screen size is
     # still unknown, so we need to set some arbitrary initial root dimensions
@@ -757,6 +835,7 @@ def __init__(self, **config):
         self.root = Node(None, *self.default_dimensions)
         self.focused = None
         self.add_mode = None
+        Node.priority = Priority.BALANCED if self.fair else Priority.FIXED
 
     @staticmethod
     def convert_names(tree):