Yes, I agree with you. This should not be merged currently. I will need some time to write the implementation for other backends. Like #1930, I will wait until the audits are merged, and will write the tests thereafter.

As for additional design for tablet modes, I agree with you. I will research more about it and will discuss with you while implementing for mobile platforms.

@mhsmith I need your guidance on android side. According to: https://developer.android.com/guide/components/activities/intro-activities#onpause

The system calls onPause() when the activity loses focus and enters a Paused state. This state occurs when, for example, the user taps the Back or Recents button.

On the Emulator(Android 12):

When starting the app, the following events are triggered: onCreate()->onStart()->onResume() . But, when I press either the Back or Recents button, onPause() event is not triggered. No other events are triggered.

When I select the app by pressing the Recents button, only onStart()->onResume() are triggered. onRestart() is not triggered.

D/MainActivity: onStart() start
I/python.stdout: Toga app: onStart
D/MainActivity: onStart() complete
D/MainActivity: onResume() start
I/python.stdout: Toga app: onResume
D/MainActivity: onResume() complete
I/OpenGLRenderer: Davey! duration=18074ms; Flags=1, FrameTimelineVsyncId=10773, IntendedVsync=2419137327998, Vsync=2419137327998, InputEventId=0, HandleInputStart=2419139817470, AnimationStart=2419139847710, PerformTraversalsStart=2419139888290, DrawStart=2419223580770, FrameDeadline=2419170661330, FrameInterval=2419139788630, FrameStartTime=16666666, SyncQueued=2419225272400, SyncStart=2419226783620, IssueDrawCommandsStart=2419227470230, SwapBuffers=2419249275450, FrameCompleted=2437213784760, DequeueBufferDuration=21300, QueueBufferDuration=360800, GpuCompleted=2437213784760, SwapBuffersCompleted=2419251729810, DisplayPresentTime=0,

When I press the home button, neither onPause() or onStop() events are triggered. No other events are triggered.

On a Physical Device(Android 13):

When starting the app, the following events are triggered: onCreate()->onStart()->onResume() . But, when I press either the Back or Recents button, onPause() event is not triggered. Instead the following events are triggered:

D/VRI[MainActivity]: onFocusEvent false
D/VRI[MainActivity]: dispatchAppVisibility visible:false
D/BufferQueueProducer: [VRI[MainActivity]#0(BLAST Consumer)0](id:55c400000000,api:1,p:21956,c:21956) disconnect: api 1
D/BufferQueueConsumer: [VRI[MainActivity]#0(BLAST Consumer)0](id:55c400000000,api:0,p:-1,c:21956) disconnect
D/VRI[MainActivity]: setWindowStopped stopped:true
D/ActivityThread: do gfx trim 40 success

When I select the app by pressing the Recents button, only onStart()->onResume() are triggered. onRestart() is not triggered. Instead the following events are triggered:

D/VRI[MainActivity]: dispatchAppVisibility visible:true
D/VRI[MainActivity]: setWindowStopped stopped:false
D/MainActivity: onStart() start
I/python.stdout: Toga app: onStart
D/MainActivity: onStart() complete
D/MainActivity: onResume() start
I/python.stdout: Toga app: onResume
D/MainActivity: onResume() complete
I/Quality : Skipped: false 0 cost 5.253646 refreshRate 8332212 bit true processName com.example.helloworld
D/BufferQueueConsumer: [](id:55c400000001,api:0,p:-1,c:21956) connect: controlledByApp=false
E/IPCThreadState: attemptIncStrongHandle(57): Not supported
D/BufferQueueProducer: [VRI[MainActivity]#1(BLAST Consumer)1](id:55c400000001,api:1,p:21956,c:21956) connect: api=1 producerControlledByApp=true
D/VRI[MainActivity]: registerCallbacksForSync syncBuffer=false
D/VRI[MainActivity]: Received frameCommittedCallback lastAttemptedDrawFrameNum=1 didProduceBuffer=true syncBuffer=false
D/VRI[MainActivity]: draw finished.
D/VRI[MainActivity]: onFocusEvent true

When I press the home button, neither onPause() or onStop() events are triggered. But, the following events are triggered:

D/VRI[MainActivity]: onFocusEvent false
D/VRI[MainActivity]: dispatchAppVisibility visible:false
D/BufferQueueProducer: [VRI[MainActivity]#0(BLAST Consumer)0](id:55c400000000,api:1,p:21956,c:21956) disconnect: api 1
D/BufferQueueConsumer: [VRI[MainActivity]#0(BLAST Consumer)0](id:55c400000000,api:0,p:-1,c:21956) disconnect
D/VRI[MainActivity]: setWindowStopped stopped:true
D/ActivityThread: do gfx trim 40 success

As, you can see, onFocusEvent, dispatchAppVisibility visible and setWindowStopped stopped show consistent behaviors.

Why are the documented Activity lifecycle events not being triggered as per the documentation?

Regarding the gain/lose focus on mobile platforms like android:

From my testing, the app will lose focus when either the Home or Recent App List buttons are pressed. On pressing the back button, the app also loses focus and sends the user to the home screen.

In split screen mode (like dual app mode), suppose there are two apps A and B. App A will gain focus when the user touches the A app's screen. The focus is lost when the user touches B app's screen or interacts with the system launcher or presses the Home or Recent App List Button.

In floating window mode, the app will gain focus when the user touches the app's screen. The focus is lost when the user touches anything outside the app, like interacting with the system launcher or another app.

In iOS like the cocoa, there exists UIApplicationDelegate, which has methods like: applicationDidBecomeActive and applicationWillResignActive

But, there needs to be another handler to differentiate between the states when (the app is not visible to the user & is not receiving inputs) and (when the app is visible to the user & is receiving inputs).

Hence, I would like to propose other additional handlers, on_background/foreground to call the handler when the app is in background/foreground and not visible/ visible to the user.

What do you guys think?

Also, without confirmation from @mhsmith regarding the Activity life events triggering behavior, I cannot proceed with the android implementation. Hence, I was thinking about working on the iOS implementation first.

When I press the home button, neither onPause() or onStop() events are triggered.

That's because those methods aren't included in the Android template, either in IPythonApp or in MainActivity. They should be added to both places, but ideally with an emptydefault implementation in order not to break any third-party implementations of IPythonApp. And all the existing methods should become default as well.

In split screen mode (like dual app mode), suppose there are two apps A and B.

See this page for how this is notified on Android.

But, there needs to be another handler to differentiate between the states when (the app is not visible to the user & is not receiving inputs) and (when the app is visible to the user & is receiving inputs).

Every API has a maintenance and testing cost, so I'd prefer not to add additional events unless there's a clear need for them, especially if they're only applicable to certain platforms.

Thank you for helping. I will add default implementations for the remaining methods in the Android template and will submit a PR there after getting a stable behavior.

I agree with you that additional events will incur more maintenance. I feel that the on_background and on_foreground events are mostly needed for mobile platforms. But there is a need for distinction between [not visible state] and [visible but not receiving inputs state] of an app.

For example, the app should be put to a sleep mode(not updating the layout or text) when it is in background or [not visible state].
But when it is in a [visible but not receiving inputs state](like in a multi app screen mode), the app should update the layout or text, so that the user can get the latest updated information.

What do you think?

I have tested android implementation both on a physical device and on the emulator.

I have submitted a PR at beeware/briefcase-android-gradle-template#69 so that the app focus event can be detected.

Completed implementations of all the platforms and also added a test in the window example app.

I will write the tests after the audits are merged. But I think this PR is ready for a review.

Also, the CI android testbed is failing on its own for some reason.

Researching some more on the topic, it seems like we need 3 categories of events:

• Input Focus -> [Receiving Inputs] or [Not Receiving Inputs]
• Visibility -----> [Visible to User] or [Not Visible to User]
• Hover

The following are the states associated with the event categories mentioned above and their implications for other event categories:

Input Focus ---> [Receiving Inputs]
  |                               | ->[Visible to User]
  |
  |---------------> [Not Receiving Inputs]
                                 | ->[Visible to User] or
                                 | ->[Not Visible to User]

Visiblity -> [Visible to User]
  |                      | ->[Receiving Inputs] or
  |                      | ->[Not Receiving Inputs]
  |
  |---------> [Not Visible to User]
                         | ->[Not Receiving Inputs]

Hover ->[Interacting with a Pointing Device or Mouse] & [Visible to User] & [Not Receiving Inputs]

Use Cases:

• The use case for Input Focus might be to show a highlight effect indicating to the user that it is receiving input.

• The use case for Visibility might be to:

  • Put the app to a sleep mode(not updating the layout or text) when it is [Not Visible to User].
  • Update the layout or text when it is [Visible to User], so that the user can get the latest information.

• So far, I am not sure what the use case for Hover might be. Maybe showing effects that would imply to the user, clicking on it, will make it to receive input focus.

Who should have which event categories:

• Toga.Window should have:
  • Input Focus: Since, multiple windows may be present, hence each window should trigger Input Focus event when they receive/lose input focus.
  • Visibility: Same reason as above
  • Hover: Same reason as above
• Toga.App doesn't really need any of the event categories since it can just iterate through the Toga.App.windows list and add handler methods to the event handlers of the windows. But, we can add them if it would make intuitive sense for the user.

APIs are not much of a problem as the available platform APIs can be properly mapped onto the above described event categories.

Apologies - the close was a stray mouse click.

I've had a quick look at some of the implementations as well; I've flagged a couple of things that stood out, but the biggest issue that occurred to me is the interaction of MINIMIZED and HIDE. What happens if a MINIMIZED window is HIDDEN, then restored to normal? It should still be HIDDEN... but AFAICT it will trigger an on_show event in most of these implementations.

Currently on the main branch, we are ignoring window state requests on hidden windows, as changing state of hidden window causes glitches on some platforms:

So, the following cannot be done:
WindowState.MINIMIZED -> window.hide() -> WindowState.NORMAL
However, the following is valid, and works correctly:
WindowState.MINIMIZED -> window.hide() -> window.show() -> WindowState.NORMAL

EDIT: To confirm that the valid pathway in the above works correctly, I have added a new test. This has helped me catch the cases where the events were getting double triggered.

On testing, I have found that on gtk, when Gtk.Window.hide() or Gtk.Window.show() is called then gtk decides to trigger window-state-event multiple times, and that too with the wrong window_state_flags, causing the visibility events(on_show and on_hide) to be triggered at wrong times.

Also, when Gtk.Window.hide() is called, then afterwards the window state cannot be determined correctly, so we need to cache the previous state before Gtk.Window.hide() is called.

Furthermore, it turns out that Gtk.Window.hide() and Gtk.Window.show() are non-blocking events, so we need to wait for appropriate request completion callbacks, before asserting cases on the testbed.

Since, we need to accomodate all of these cases, the implementation on gtk will take some time. Therefore, can I do the gtk implementation on a separate PR, and skip it here? As the implementation is working correctly on all platforms except on gtk, so skipping the gtk implementation on this PR should not be an issue.

Since, we need to accomodate all of these cases, the implementation on gtk will take some time. Therefore, can I do the gtk implementation on a separate PR, and skip it here? As the implementation is working correctly on all platforms except on gtk, so skipping the gtk implementation on this PR should not be an issue.

Sure - an implementation that works on not-all platforms is fine - in fact, if there's an underlying issue with the state change tests, then we should definitely resolve those first.

As long as the tests pass reliably on all platforms (and are skipped on platforms where the implementation doesn't exist/doesn't work reliably), and it's clear in the review request what does (and doesn't) work, I'm fine with reviewing and merging. All the usual guidelines about skips apply (i.e, avoid referencing GTK specifically in the test - try to raise the skip in the probe).

Ok, I have removed the gtk's visibility events(i.e., on_show() and on_hide()) triggering implementations from this PR, and have updated the tests accordingly.

So, both the focus events i.e., on_gain_focus & on_lose_focus are implemented and tested on all platforms(includiing gtk). However, both the visibility events i.e., on_show and on_hide are implemented and tested on all the platforms, except on gtk(I will implement them in a separate PR for gtk).

Also, another issue is testing of the events on mobile platforms, where the app cannot be sent to background and brought forward, switch between apps, or switch to the "App switcher" screen. All of these are required to automate the testing of focus and visibility events on the mobile platforms. Since, these automated tests are currently not possible, hence I have manually tested them on a physical Android 14 device, on the Android emulator and on the iOS simulator.

f we're going to make the behavior consistent, I'd argue the Cocoa behavior is the better interpretation - if someone is calling "show()", they're indicating they want the window to be visible, not just minimized. But I suspect the "show/hide is an error if minimized" approach might be better as it's more explicit about intent.

The inconsistency is that on macOS, calling window.show() unhides the window and also deminiaturizes it. This is different from the behavior of other platforms, where calling window.show() on a MINIMIZED window only unhides it(i.e., only shows the window icon in taskbar or app tray, and doesn't deminiaturize it).

But this inconsistency is only in the calling of window.show() on a previously MINIMIZED and hidden window, not on calling of window.hide() on a previously MINIMIZED window.

Since, hiding a MINIMIZED window is supported by every platfform, so disabling show/hide on a MINIMIZED window, seems like a bit too restrictive. So, I think the best approach would be to produce the Cocoa's interpretation of window.show() as the default behavior on all platforms. This would help to eliminate the inconsistency in the test suite that you have described.

Since, hiding a MINIMIZED window is supported by every platfform, so disabling show/hide on a MINIMIZED window, seems like a bit too restrictive. So, I think the best approach would be to produce the Cocoa's interpretation of window.show() as the default behavior on all platforms. This would help to eliminate the inconsistency in the test suite that you have described.

I can't argue it wouldn't be restrictive to disable show/hide on MINIMIZED. The question is whether that's a better option than the alternative - whether implementing macOS's behavior on GTK and Windows is problematic.

The major argument again using macOS's behaviour is that it couples two otherwise unrelated features "show/hide" and state are now closely related features. I guess there's an argument that they already are, in that you can't change the state of a hidden window; but implementing macOS's behavior doubles down on that relationship in a way that I'm not sure is helpful.

Another argument against macOS's behavior is a question I raised in my previous comment - what about other window states? What does it mean to hide a window in presentation mode? In fullscreen mode? We already restrict changing window state on non-visible windows; do we need to restrict changing visibility on some window states? This will require some more experimentation to determine what is even possible.

Another complication that came up this morning in a conversation with @mhsmith - macOS has an app-level concept of "Hide all windows". It's not completely clear how this would interact with window-level hide - but it clearly needs to.

One last thing that might be worth exploring - are we sure that makeKeyAndOrderFront is the right API for the macOS implementation of show() (or, at least, for show() on any window that has previously been displayed)? The name of the API itself hints that it's a combination API - it's making the window the key window and ordering the window to the front. It wouldn't surprise me if making the window the key window is what is triggering the unminimize action. It's possible that orderFrontRegardless might be a better match for show() on a window that already exists, or a minimized window.