Added on_gain_focus, on_lose_focus, on_show & on_hide handlers on toga.Window

android/src/toga_android/app.py

@@ -4,6 +4,7 @@
 from android.content import Context
 from android.graphics.drawable import BitmapDrawable
 from android.media import RingtoneManager
+from android.os import Build
 from android.view import Menu, MenuItem
 from androidx.core.content import ContextCompat
 from java import dynamic_proxy
@@ -35,22 +36,46 @@ def onCreate(self):
 
     def onStart(self):
         print("Toga app: onStart")
+        for window in self._impl.interface.windows:
+            window.on_show()
 
-    def onResume(self):
+    def onResume(self):  # pragma: no cover
         print("Toga app: onResume")
-
-    def onPause(self):
-        print("Toga app: onPause")  # pragma: no cover
-
-    def onStop(self):
-        print("Toga app: onStop")  # pragma: no cover
+        # onTopResumedActivityChanged is not available on android versions less
+        # than Q. onResume is the best indicator for the gain input focus event.
+        # https://developer.android.com/reference/android/app/Activity#onWindowFocusChanged(boolean):~:text=If%20the%20intent,the%20best%20indicator.
+        if Build.VERSION.SDK_INT < Build.VERSION_CODES.Q:
+            for window in self._impl.interface.windows:
+                window.on_gain_focus()
+
+    def onPause(self):  # pragma: no cover
+        print("Toga app: onPause")
+        # onTopResumedActivityChanged is not available on android versions less
+        # than Q. onPause is the best indicator for the lost input focus event.
+        if Build.VERSION.SDK_INT < Build.VERSION_CODES.Q:
+            for window in self._impl.interface.windows:
+                window.on_lose_focus()
+
+    def onStop(self):  # pragma: no cover
+        print("Toga app: onStop")
+        for window in self._impl.interface.windows:
+            window.on_hide()
 
     def onDestroy(self):
         print("Toga app: onDestroy")  # pragma: no cover
 
     def onRestart(self):
         print("Toga app: onRestart")  # pragma: no cover
 
+    def onTopResumedActivityChanged(self, isTopResumedActivity):  # pragma: no cover
+        print("Toga app: onTopResumedActivityChanged")
+        if isTopResumedActivity:
+            for window in self._impl.interface.windows:
+                window.on_gain_focus()
+        else:
+            for window in self._impl.interface.windows:
+                window.on_lose_focus()
+
     def onActivityResult(self, requestCode, resultCode, resultData):
         print(f"Toga app: onActivityResult {requestCode=} {resultCode=} {resultData=}")
         try:

changes/2009.feature.rst

@@ -0,0 +1 @@
+Window can now respond to changes in focus and visibility.

cocoa/src/toga_cocoa/window.py

@@ -68,8 +68,17 @@ def windowDidResize_(self, notification) -> None:
             # Set the window to the new size
             self.interface.content.refresh()
 
+    @objc_method
+    def windowDidBecomeMain_(self, notification):
+        self.impl.interface.on_gain_focus()
+
+    @objc_method
+    def windowDidResignMain_(self, notification):
+        self.impl.interface.on_lose_focus()
+
     @objc_method
     def windowDidMiniaturize_(self, notification) -> None:
+        self.impl.interface.on_hide()
         if (
             self.impl._pending_state_transition
             and self.impl._pending_state_transition != WindowState.MINIMIZED
@@ -80,6 +89,7 @@ def windowDidMiniaturize_(self, notification) -> None:
 
     @objc_method
     def windowDidDeminiaturize_(self, notification) -> None:
+        self.impl.interface.on_show()
         self.impl._apply_state(self.impl._pending_state_transition)
 
     @objc_method
@@ -265,6 +275,7 @@ def set_app(self, app):
 
     def show(self):
         self.native.makeKeyAndOrderFront(None)
+        self.interface.on_show()
 
     ######################################################################
     # Window content and resources
@@ -341,6 +352,7 @@ def set_position(self, position):
 
     def hide(self):
         self.native.orderOut(self.native)
+        self.interface.on_hide()
 
     def get_visible(self):
         return (

core/src/toga/window.py

@@ -106,6 +106,49 @@ def __call__(self, window: Window, **kwargs: Any) -> bool:
         """
 
 
+class OnGainFocusHandler(Protocol):
+    def __call__(self, window: Window, **kwargs: Any) -> None:
+        """A handler to invoke when a window gains input focus.
+        :param window: The window instance that gains input focus.
+        :param kwargs: Ensures compatibility with additional arguments introduced in
+            future versions.
+        """
+        ...
+
+
+class OnLoseFocusHandler(Protocol):
+    def __call__(self, window: Window, **kwargs: Any) -> None:
+        """A handler to invoke when a window loses input focus.
+        :param window: The window instance that loses input focus.
+        :param kwargs: Ensures compatibility with additional arguments introduced in
+            future ver
+        """
+        ...
+
+
+class OnShowHandler(Protocol):
+    def __call__(self, window: Window, **kwargs: Any) -> None:
+        """A handler to invoke when a window becomes visible to the user from a not
+        visible state. Not visible to the user refers to window states like minimized,
+        hidden, etc.
+        :param window: The window instance that becomes visible.
+        :param kwargs: Ensures compatibility with additional arguments introduced in
+            future ver
+        """
+        ...
+
+
+class OnHideHandler(Protocol):
+    def __call__(self, window: Window, **kwargs: Any) -> None:
+        """A handler to invoke when a window becomes not visible to the user.
+        Not visible to the user refers to window states like minimized, hidden, etc.
+        :param window: The window instance that becomes not visible to the user.
+        :param kwargs: Ensures compatibility with additional arguments introduced in
+            future ver
+        """
+        ...
+
+
 _DialogResultT = TypeVar("_DialogResultT")
 
 
@@ -141,6 +184,10 @@ def __init__(
         closable: bool = True,
         minimizable: bool = True,
         on_close: OnCloseHandler | None = None,
+        on_gain_focus: OnGainFocusHandler | None = None,
+        on_lose_focus: OnLoseFocusHandler | None = None,
+        on_show: OnShowHandler | None = None,
+        on_hide: OnHideHandler | None = None,
         content: Widget | None = None,
     ) -> None:
         """Create a new Window.
@@ -193,6 +240,11 @@ def __init__(
 
         self.on_close = on_close
 
+        self.on_gain_focus = on_gain_focus
+        self.on_lose_focus = on_lose_focus
+        self.on_show = on_show
+        self.on_hide = on_hide
+
     def __lt__(self, other: Window) -> bool:
         return self.id < other.id
 
@@ -530,6 +582,42 @@ def cleanup(window: Window, should_close: bool) -> None:
 
         self._on_close = wrapped_handler(self, handler, cleanup=cleanup)
 
+    @property
+    def on_gain_focus(self) -> callable:
+        """The handler to invoke if the window gains input focus."""
+        return self._on_gain_focus
+
+    @on_gain_focus.setter
+    def on_gain_focus(self, handler):
+        self._on_gain_focus = wrapped_handler(self, handler)
+
+    @property
+    def on_lose_focus(self) -> callable:
+        """The handler to invoke if the window loses input focus."""
+        return self._on_lose_focus
+
+    @on_lose_focus.setter
+    def on_lose_focus(self, handler):
+        self._on_lose_focus = wrapped_handler(self, handler)
+
+    @property
+    def on_show(self) -> callable:
+        """The handler to invoke if the window is shown from a hidden state."""
+        return self._on_show
+
+    @on_show.setter
+    def on_show(self, handler):
+        self._on_show = wrapped_handler(self, handler)
+
+    @property
+    def on_hide(self) -> callable:
+        """The handler to invoke if the window is hidden from a visible state."""
+        return self._on_hide
+
+    @on_hide.setter
+    def on_hide(self, handler):
+        self._on_hide = wrapped_handler(self, handler)
+
     ######################################################################
     # 2024-06: Backwards compatibility for <= 0.4.5
     ######################################################################

core/tests/window/test_window.py

@@ -584,6 +584,129 @@ def test_close_rejected_handler(window, app):
     on_close_handler.assert_called_once_with(window)
 
 
+def test_on_gain_focus(window):
+    assert window._on_gain_focus._raw is None
+
+    on_gain_focus_handler = Mock()
+    window.on_gain_focus = on_gain_focus_handler
+
+    assert window.on_gain_focus._raw == on_gain_focus_handler
+
+    window._impl.simulate_on_gain_focus()
+
+    on_gain_focus_handler.assert_called_once_with(window)
+
+
+def test_on_lose_focus(window):
+    assert window.on_lose_focus._raw is None
+
+    on_lose_focus_handler = Mock()
+    window.on_lose_focus = on_lose_focus_handler
+
+    assert window.on_lose_focus._raw == on_lose_focus_handler
+
+    window._impl.simulate_on_lose_focus()
+
+    on_lose_focus_handler.assert_called_once_with(window)
+
+
+def test_on_show(window):
+    assert window.on_show._raw is None
+
+    on_show_handler = Mock()
+    window.on_show = on_show_handler
+
+    assert window.on_show._raw == on_show_handler
+
+    window._impl.simulate_on_show()
+
+    on_show_handler.assert_called_once_with(window)
+
+
+def test_on_hide(window):
+    assert window.on_hide._raw is None
+
+    on_hide_handler = Mock()
+    window.on_hide = on_hide_handler
+
+    assert window.on_hide._raw == on_hide_handler
+
+    window._impl.simulate_on_hide()
+
+    on_hide_handler.assert_called_once_with(window)
+
+
+def test_focus_events(app):
+    """The window can trigger on_gain_focus() and on_lose_focus()
+    event handlers, when the window gains or loses input focus."""
+    window1 = toga.Window()
+    window1.show()
+    window1_on_gain_focus_handler = Mock()
+    window1_on_lose_focus_handler = Mock()
+    window1.on_gain_focus = window1_on_gain_focus_handler
+    window1.on_lose_focus = window1_on_lose_focus_handler
+
+    window2 = toga.Window()
+    window2.show()
+    window2_on_gain_focus_handler = Mock()
+    window2_on_lose_focus_handler = Mock()
+    window2.on_gain_focus = window2_on_gain_focus_handler
+    window2.on_lose_focus = window2_on_lose_focus_handler
+
+    app.current_window = window1
+    window1_on_gain_focus_handler.assert_called_once_with(window1)
+
+    app.current_window = window2
+    window2_on_gain_focus_handler.assert_called_once_with(window2)
+    window1_on_lose_focus_handler.assert_called_once_with(window1)
+
+    app.current_window = window1
+    window1_on_gain_focus_handler.assert_called_with(window1)
+    window2_on_lose_focus_handler.assert_called_once_with(window2)
+
+
+def test_visibility_events(window):
+    """The window can trigger on_show() and on_hide() event handlers,
+    when the window is shown or hidden respectively."""
+    window.show()
+    on_show_handler = Mock()
+    on_hide_handler = Mock()
+    window.on_show = on_show_handler
+    window.on_hide = on_hide_handler
+
+    window.hide()
+    on_hide_handler.assert_called_once_with(window)
+
+    window.show()
+    on_show_handler.assert_called_once_with(window)
+
+
+@pytest.mark.parametrize(
+    "state",
+    [
+        WindowState.NORMAL,
+        WindowState.MAXIMIZED,
+        WindowState.FULLSCREEN,
+        WindowState.PRESENTATION,
+    ],
+)
+def test_visibility_events_on_window_state_change(window, state):
+    """The window can trigger on_hide() and on_show() event handlers,
+    when the window is MINIMIZED and UN-MINIMIZED respectively."""
+    window.show()
+    on_show_handler = Mock()
+    on_hide_handler = Mock()
+    window.on_show = on_show_handler
+    window.on_hide = on_hide_handler
+    window.state = state
+
+    window.state = WindowState.MINIMIZED
+    on_hide_handler.assert_called_once_with(window)
+
+    window.state = state
+    on_show_handler.assert_called_once_with(window)
+
+
 def test_as_image(window):
     """A window can be captured as an image."""
     image = window.as_image()

dummy/src/toga_dummy/app.py

@@ -133,9 +133,15 @@ def get_current_window(self):
         return self._get_value("current_window", main_window)
 
     def set_current_window(self, window):
+        previous_current_window = getattr(self.get_current_window(), "interface", None)
+
         self._action("set_current_window", window=window)
         self._set_value("current_window", window._impl)
 
+        if previous_current_window and previous_current_window != window:
+            previous_current_window.on_lose_focus()
+            window.on_gain_focus()
+
 
 class DocumentApp(App):
     def create(self):