Sessions: A new command focus_matching_window to shift focus to a specific window, useful when creating complex layouts with splits

docs/changelog.rst

@@ -76,6 +76,8 @@ Detailed list of changes
 
 - Add NERD fonts builtin so that users don't have to install them to use NERD symbols in kitty. The builtin font is used only if the symbols are not available in some system font
 
+- Sessions: A new command ``focus_matching_window`` to shift focus to a specific window, useful when creating complex layouts with splits (:disc:`7635`)
+
 - Wayland: Allow fractional scales less than one (:pull:`7549`)
 
 - Wayland: Fix specifying the output name for the panel kitten not working (:iss:`7573`)

docs/overview.rst

@@ -176,6 +176,25 @@ option in :file:`kitty.conf`. An example, showing all available commands:
     focus_os_window
     launch emacs
 
+    # Create a complex layout using multiple splits. Creates two columns of
+    # windows with two windows in each column. The windows in the firt column are
+    # split 50:50. In the second column the windows are not evenly split.
+    new_tab complex tab
+    layout splits
+    # First window, set a user variable on it so we can focus it later
+    launch --var window=first
+    # Create the second column by splitting the first window vertically
+    launch --location=vsplit
+    # Create the third window in the second column by splitting the second window horizontally
+    launch --location=hsplit
+    # Make the third window shorter so that the split is not even
+    resize_window shorter 5
+    # Go back to focusing the first window, so that we can split it
+    focus_matching_window var:window=first
+    # Create the final window in the first column
+    launch --location=hsplit
+
+
 .. note::
     The :doc:`launch <launch>` command when used in a session file cannot create
     new OS windows, or tabs.