Sessions: Allow controlling which OS Window is active via the focus_os_window directive

docs/changelog.rst

@@ -42,6 +42,8 @@ Detailed list of changes
 
 - ssh kitten: Fix :envvar:`KITTY_PUBLIC_KEY` not being encoded properly when transmitting (:iss:`5496`)
 
+- Sessions: Allow controlling which OS Window is active via the ``focus_os_window`` directive
+
 0.26.2 [2022-09-05]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/overview.rst

@@ -163,8 +163,10 @@ option in :file:`kitty.conf`. For example:
     launch sh
     # Resize the current window (see the resize_window action for details)
     resize_window wider 2
-    # Make the current window the active (focused) window
+    # Make the current window the active (focused) window in its tab
     focus
+    # Make the current OS Window the globally active window (not supported on Wayland)
+    focus_os_window
     launch emacs
 
 .. note::

kitty/boss.py

@@ -296,14 +296,19 @@ class Boss:
 
     def startup_first_child(self, os_window_id: Optional[int], startup_sessions: Iterable[Session] = ()) -> None:
         si = startup_sessions or create_sessions(get_options(), self.args, default_session=get_options().startup_session)
+        focused_os_window = 0
         for startup_session in si:
-            self.add_os_window(startup_session, os_window_id=os_window_id)
+            wid = self.add_os_window(startup_session, os_window_id=os_window_id)
+            if startup_session.focus_os_window:
+                focused_os_window = wid
             os_window_id = None
             if self.args.start_as != 'normal':
                 if self.args.start_as == 'fullscreen':
                     self.toggle_fullscreen()
                 else:
                     change_os_window_state(self.args.start_as)
+        if focused_os_window > 0:
+            focus_os_window(focused_os_window, True)
 
     def add_os_window(
         self,
@@ -637,14 +642,19 @@ class Boss:
                 args.session = PreReadSession(data['stdin'])
             if not os.path.isabs(args.directory):
                 args.directory = os.path.join(data['cwd'], args.directory)
+            focused_os_window = 0
             for session in create_sessions(opts, args, respect_cwd=True):
                 os_window_id = self.add_os_window(
                     session, wclass=args.cls, wname=args.name, opts_for_size=opts, startup_id=startup_id,
                     override_title=args.title or None)
+                if session.focus_os_window:
+                    focused_os_window = os_window_id
                 if opts.background_opacity != get_options().background_opacity:
                     self._set_os_window_background_opacity(os_window_id, opts.background_opacity)
                 if data.get('notify_on_os_window_death'):
                     self.os_window_death_actions[os_window_id] = partial(self.notify_on_os_window_death, data['notify_on_os_window_death'])
+            if focused_os_window > 0:
+                focus_os_window(focused_os_window, True)
         else:
             log_error('Unknown message received from peer, ignoring')
         return None

kitty/session.py

@@ -60,6 +60,7 @@ class Session:
         self.default_title = default_title
         self.os_window_size: Optional[WindowSizes] = None
         self.os_window_class: Optional[str] = None
+        self.focus_os_window: bool = False
 
     def add_tab(self, opts: Options, name: str = '') -> None:
         if self.tabs and not self.tabs[-1].windows:
@@ -146,6 +147,8 @@ def parse_session(raw: str, opts: Options) -> Generator[Session, None, None]:
                 ans.add_window(rest)
             elif cmd == 'focus':
                 ans.focus()
+            elif cmd == 'focus_os_window':
+                ans.focus_os_window = True
             elif cmd == 'enabled_layouts':
                 ans.set_enabled_layouts(rest)
             elif cmd == 'cd':