Allow tracking focus change events in watchers

Fixes #2918

docs/changelog.rst

@@ -19,6 +19,8 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 - Add a new extensible escape code to allow terminal programs to trigger
   desktop notifications. See :ref:`desktop_notifications` (:iss:`1474`)
 
+- Allow tracking focus change events in watchers (:iss:`2918`)
+
 
 0.18.3 [2020-08-11]
 -------------------

docs/launch.rst

@@ -74,6 +74,9 @@ functions for the events you are interested in, for example:
     def on_resize(boss, window, data):
         # Here data will contain old_geometry and new_geometry
 
+    def on_focus_change(boss, window, data):
+        # Here data kill contain focused
+
     def on_close(boss, window, data):
         # called when window is closed, typically when the program running in
         # it exits.

kitty/launch.py

@@ -216,6 +216,9 @@ def load_watch_modules(opts: LaunchCLIOptions) -> Optional[Watchers]:
         w = m.get('on_resize')
         if callable(w):
             ans.on_resize.append(w)
+        w = m.get('on_focus_change')
+        if callable(w):
+            ans.on_focus_change.append(w)
     return ans
 
 

kitty/window.py

@@ -90,6 +90,7 @@ class Watchers:
     def __init__(self) -> None:
         self.on_resize: List[Watcher] = []
         self.on_close: List[Watcher] = []
+        self.on_focus_change: List[Watcher] = []
 
 
 def call_watchers(windowref: Callable[[], Optional['Window']], which: str, data: Dict[str, Any]) -> None:
@@ -459,6 +460,7 @@ class Window:
     def focus_changed(self, focused: bool) -> None:
         if self.destroyed:
             return
+        call_watchers(weakref.ref(self), 'on_focus_change', {'focused': focused})
         if focused:
             self.needs_attention = False
             if self.screen.focus_tracking_enabled: