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,40 @@ def onCreate(self):
 
     def onStart(self):
         print("Toga app: onStart")
+        self._impl.interface.current_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:
+            self._impl.interface.current_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:
+            self._impl.interface.current_window.on_lose_focus()
+
+    def onStop(self):  # pragma: no cover
+        print("Toga app: onStop")
+        self._impl.interface.current_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:
+            self._impl.interface.current_window.on_gain_focus()
+        else:
+            self._impl.interface.current_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 @@
+Windows 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.interface.on_gain_focus()
+
+    @objc_method
+    def windowDidResignMain_(self, notification):
+        self.interface.on_lose_focus()
+
     @objc_method
     def windowDidMiniaturize_(self, notification) -> None:
+        self.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.interface.on_show()
         self.impl._apply_state(self.impl._pending_state_transition)
 
     @objc_method
@@ -257,7 +267,14 @@ def set_app(self, app):
         pass
 
     def show(self):
+        previously_visible = self.get_visible()
+        previous_state = self.get_window_state(in_progress_state=True)
         self.native.makeKeyAndOrderFront(None)
+        # Avoid triggering the event here, as makeKeyAndOrderFront() also
+        # deminiaturizes the window, which will trigger windowDidDeminiaturize_.
+        # This could lead to double triggering, so prevent it here.
+        if not previously_visible and previous_state != WindowState.MINIMIZED:
+            self.interface.on_show()
 
     ######################################################################
     # Window content and resources
@@ -333,7 +350,13 @@ def set_position(self, position):
     ######################################################################
 
     def hide(self):
+        previously_visible = self.get_visible()
+        previous_state = self.get_window_state(in_progress_state=True)
         self.native.orderOut(self.native)
+        # Avoid triggering the event if the window was already in a
+        # not-visible-user(minimized or hidden) state.
+        if previously_visible and previous_state != WindowState.MINIMIZED:
+            self.interface.on_hide()
 
     def get_visible(self):
         return (

cocoa/tests_backend/window.py

@@ -16,6 +16,9 @@ class WindowProbe(BaseProbe, DialogsMixin):
     supports_unminimize = True
     supports_minimize = True
     supports_placement = True
+    # Calling window.show() un-minimizes the window on cocoa.
+    show_unminimizes_window = True
+    supports_visibility_events = True
 
     def __init__(self, app, window):
         super().__init__()

core/src/toga/window.py

@@ -106,6 +106,58 @@ 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.
+
+        This event will be triggered when a window is first displayed, and when the
+        window is restored from a minimized or hidden state. On mobile platforms, it is
+        also triggered when an app is made the currently active app.
+
+        :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 stops being visible.
+
+        This event will be triggered when a window moves to a minimized or hidden state.
+        On mobile platforms, it is also triggered when an app is moved to the background
+        and is no longer the currently active app.
+
+        :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 +193,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 +249,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 +591,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/utils.py

@@ -24,3 +24,55 @@ def _create(self):
 
     def __repr__(self):
         return f"Widget(id={self.id!r})"
+
+
+def assert_window_gain_focus(window, trigger_expected=True):
+    on_gain_focus_handler = window.on_gain_focus._raw
+    on_lose_focus_handler = window.on_lose_focus._raw
+    if trigger_expected:
+        on_gain_focus_handler.assert_called_once_with(window)
+    else:
+        on_gain_focus_handler.assert_not_called()
+    on_lose_focus_handler.assert_not_called()
+
+    on_gain_focus_handler.reset_mock()
+    on_lose_focus_handler.reset_mock()
+
+
+def assert_window_lose_focus(window, trigger_expected=True):
+    on_gain_focus_handler = window.on_gain_focus._raw
+    on_lose_focus_handler = window.on_lose_focus._raw
+    if trigger_expected:
+        on_lose_focus_handler.assert_called_once_with(window)
+    else:
+        on_lose_focus_handler.assert_not_called()
+    on_gain_focus_handler.assert_not_called()
+
+    on_gain_focus_handler.reset_mock()
+    on_lose_focus_handler.reset_mock()
+
+
+def assert_window_on_show(window, trigger_expected=True):
+    on_show_handler = window.on_show._raw
+    on_hide_handler = window.on_hide._raw
+    if trigger_expected:
+        on_show_handler.assert_called_once_with(window)
+    else:
+        on_show_handler.assert_not_called()
+    on_hide_handler.assert_not_called()
+
+    on_show_handler.reset_mock()
+    on_hide_handler.reset_mock()
+
+
+def assert_window_on_hide(window, trigger_expected=True):
+    on_show_handler = window.on_show._raw
+    on_hide_handler = window.on_hide._raw
+    if trigger_expected:
+        on_hide_handler.assert_called_once_with(window)
+    else:
+        on_hide_handler.assert_not_called()
+    on_show_handler.assert_not_called()
+
+    on_show_handler.reset_mock()
+    on_hide_handler.reset_mock()