Added `on_resize` handler on `toga.Window`

[proneon267]

Toga Windows now supports calling user functions on resize events using on_resize handler on all platforms.

Fixes #2304

PR Checklist:

• [x] All new features have been tested
• [x] All new features have been documented
• [x] I have read the CONTRIBUTING.md file
• [x] I will abide by the code of conduct

[proneon267]

Quick question, there are actually 2 events that can be interpreted as on_resize:

• on_resizing - Triggers during each step of the window resizing.
• on_resized - Triggers after the window is resized

So, which one should we implement for on_resize?

[mhsmith]

I think we should deliver the event if and only if the new size is actually available for rendering the window content. Whether this happens continuously during the resize, or only at the end, may vary between platforms.

[proneon267]

I am not sure, if I understood what you meant.

There are 2 ways to resize a window:

• From the User's side => By dragging the edges of the window => The user can only drag as far as the actual boundary of the screen => new size is guaranteed to be valid.
• From the API side => Through window.size => If a value higher than the available screen size is passed:
  • If only a single screen is present => the system caps the size within the available screen space => new size will be valid.
  • If multiple screens are available and positioned accordingly => new size will be within available space within the screens => new size will be valid

So, in all cases the new size will be valid, as the new window size is obtained from the platform itself. So, what should we be validating here?

As per the current implementation, the behavior is that the on_resize event is triggered continuously and multiple times, when the user drags the edges of the window to resize. Which is following the on_resizing interpretation.

But I am not sure if this is the behavior that the user expects. Do you think the on_resized interpretation would be more appropriate?

[freakboy3742]

I am not sure, if I understood what you meant.

There are 2 ways to resize a window:

The mechanism for changing the window size isn't the issue. Depending on the platform, it's possible for the window system to generate window sizes that are invalid - consider the case of resizing a window to be smaller than the size that would be allowed by the content layout rules. Toga then internally rejects or adjusts those window sizes as necessary. In this case, you may get a system notification of a window size that isn't legal, because it's smaller than Toga will allow for content. This would be the window size that a "pre-resize" event (on_resizing, by your naming scheme) would generate.

However, I'd argue there's no practical purpose to such an event in Toga. It would only be useful if there was a mechanism to reject the proposed size, and that won't be the case here. On that basis, I'd argue the "on_resized" interpretation is the only one that makes sense for Toga's public API purposes.

This event may be generated multiple times as a window is dragged; however, that's a platform implementation detail. When the user-space event is triggered, it should reflect the fact that a new window size (however transient it may be) is available and in effect; and the last on_resize event that is received should be sent when the final window size has been confirmed (i.e., evaluating window.size inside on_resize() should give you the actual final window size).