Design of window state API

[proneon267]

As per our discussion until now, here is what I think the window state API should look like:

Window by Window Basis'

# As a getter:
print(window.state)           
# Returns the current window state in the form of a WindowState Enum Class Value

# As a setter:
window.state = WindowState.MAXIMIZED | WindowState.MINIMIZED | WindowState.FULLSCREEN | WindowState.NORMAL
# Sets the current window state no matter what the previous window state was.

App wide Basis:

# As a getter:
print(app.window_state)
# Returns a dictionary of the app's windows as values and WindowState Enum Class values as keys.
# the user can do: 
# windows = app.window_state 
# print(windows[WindowState.MAXIMIZED])

# As a setter:
app.window_state = WindowState.MAXIMIZED | WindowState.MINIMIZED | WindowState.FULLSCREEN | WindowState.NORMAL
# Sets all windows of the app to the specified window state.

I am not too keen about the app wide property.

An app is made up of windows. A window has a state, i.e., Maximimized, Minimized, Full Screened, etc. But an app doesn't have such a state. An app state can be Running, Sleeping, Paused, etc., which is totally different from window state.

Besides, if a user wants to set all the windows of an app to a particular window state then they can do it themselves:

for window in app.windows:
    window.state = WindowState.MAXIMIZED | WindowState.MINIMIZED | WindowState.FULLSCREEN | WindowState.NORMAL

Hence, I think an app wide exposure of window state API is not logical nor good. The only reason why I had implemented it app-wide is because the previous API, i.e., set_full_screen() and exit_full_screen() were exposed at the app level. But I think this is fundamentally wrong. Apps contain Windows. Apps are not Windows. Doing Window state operations on them doesn't make any sense. So, if we could remove the app wide property then it would become much more logical and clear.

Questions about the cocoa implementation:
From the code of cocoa implementation of set_full_screen(), I think, it is setting the given windows full screen on the different screens according to the order in which they are passed into the method.

From looking at the podium source code, the above seems to be true. In the source code, you are changing the order in which the windows are passed to set_full_screen() to set the windows full screen on a particular display among the available displays.

If the above is true, then I think setting a windows to a particular display should be a separate API. This would allow more flexibility and bring clarity to the API as they do not need to juggle and pass windows to set the window on a particular display. So, we can have another registry like app.screens or app.displays which would be similar to app.windows and will hold a handle to all the available displays on the system on which the app is running.

@freakboy3742 Let me know how do you feel about this.

[freakboy3742]

I'm broadly in agreement that window state is a window API, and app-level state control is at least questionable. The two exceptions I can see to this are:

1. "Minimise all" and "unminimize all". This is mostly a convenience; any app-level implementation of this would be no more than for window in windows: window.minimize(). I don't see a good practical use for "maximise all"; the only reason to include this is for symmetry in the API. I wouldn't be heartbroken if this API didn't exist for minimize, because it's so easy to reproduce from window-specific methods.
2. Full screen. "full screen" isn't just "maximized" or "maximized without a titlebar". It's a very distinct mode that an app is in. It might be possible to represent this in a window specific API, but we need to be careful about that abstraction. A Slide presentation apps are the best exemplar of full screen mode (and is the reason full screen mode exists in Toga). "Start presentation" isn't something you do to 1 window. The app goes full screen, showing a slide deck on one screen, and speaker notes on a second screen. If you have more than 2 screens, the third screen has nothing on it. When the presentation is finished, the whole app goes out of full screen mode, and restores all the visibility of the windows of other apps your machine is running.

I'm definitely in favour of exposing better APIs for exposing screens/displays, and incorporating that representation into APIs that allow a window move to a different screen. Having this representation would definitely make the existing set_full_screen() mode a lot more flexible. There's a lot more detail needed in this, though - in particular, how do window positioning coordinate map and interact with display definitions.

The core window state API is less controversial - I agree window.state = MIN/MAX/NORMAL makes sense; I'd argue that window.minimized = True/False et al as an alternate spelling of the same core functionality would also make sense, and I think we should have both. The interaction with full screen mode is more complex, specifically because of the app-level aspect.

As with the cursor API discussion, we also have a question about the backend API - but we should sort out the public API first.

[proneon267]

If its easy to do then we can expose the window state API at window level only. This would provide a singular way to do a thing, which is good for bug fixing.

For screen/display API, we can have a registry like app.displays similar to app.windows that will hold the reference to all the available displays to the system.

The app.displays should have the following properties:

display.id
display.name
display.windows
display.resolution
display.size
display.refresh_rate

The usage of the API can be:

for display in app.displays:
    print(display.id)
    print(display.name)
    print(display.windows)
    print(display.resolution)
    print(display.size)
    print(display.refresh_rate)

    display.windows += window_1

What do you think about this?

[proneon267]

When proposing an API, it's helpful to describe what each API endpoint is. What's the difference between size and resolution? I presume size is physical size? If so... Why use size for physical size, when a window's size is size in pixels?

They can be used for determining the aspect ratio of a display, calculating the pixel density, etc. The use case would be choosing a display based on such a specific criteria.

Saying the proposed api usage is "print(x)"... doesn't tell me anything. Of course you can print it. It's a Python object. What are you trying to communicate here?

I meant to use that as a property getter.

Does every platform provide an ID, name and size for each display? Do any platforms provide all three? Why would anyone care about the refresh rate? What about the other properties - are they available on all platforms?

The API is specifically for multi display, so yes all the properties should be available on all platforms.

Why is an API needed to programmatically add a window to a display? Is that your proposed API to move a window from one display to another? Why not window.display = new_display?

Because doing window.display = new_display, would require the user to know every detail about the display, and would also require them to create a display object. Apps have references to all the displays of a system and can assign a specific window to a specific display.

And how does display interact with any other APIs? In particular, window.position and set_full_screen - the reason why display as an API came up in the first place?

set_full_screen should be deprecated in favour of the new window.state API. To keep backwards compatibility, we can the emulate the original behavior through a combination of window.state and app.displays APIs. window.position should return the position based the screen on which it is placed.

And in terms of other issues, you haven't responded to any of my comments about full screen being an App-specific API - you've just said we can restrict the window state API to be window only. Well... no we can't, if app-based full screen needs to be taken into account.

If an app developer wants an app-wide full screen, why can't they just do:

for window in app.windows:
   window.state = WindowState.FULLSCREEN

This would allow both an app developer who wants to control app-wide behaviour and an app developer who wants window basis behavior to keep their level of control on their app according to their preference.

[freakboy3742]

When proposing an API, it's helpful to describe what each API endpoint is. What's the difference between size and resolution? I presume size is physical size? If so... Why use size for physical size, when a window's size is size in pixels?

They can be used for determining the aspect ratio of a display, calculating the pixel density, etc. The use case would be choosing a display based on such a specific criteria.

I'm having difficulty imagining a use case where this would be useful in practice, outside of some very niche high-end graphics apps. And if you're in that space, I'd suggest you're probably not using Toga, because you're going to be caring about specific monitor color spaces, image compression, and lots of other properties that have a tangible impact on the rendering of images and video.

Saying the proposed api usage is "print(x)"... doesn't tell me anything. Of course you can print it. It's a Python object. What are you trying to communicate here?

I meant to use that as a property getter.

If something is a defined as a property, you can take it as given that you can get the property.

Does every platform provide an ID, name and size for each display? Do any platforms provide all three? Why would anyone care about the refresh rate? What about the other properties - are they available on all platforms?

The API is specifically for multi display, so yes all the properties should be available on all platforms.

That's the design you're proposing - what I'm asking is whether you've confirmed we'll be able to implement that API. There's no point adding a "refresh rate" property if we can't actually get that data on every platform we care about. At the very least, that means demonstrating there's a viable GTK, Cocoa and Winforms API for getting this data.

Why is an API needed to programmatically add a window to a display? Is that your proposed API to move a window from one display to another? Why not window.display = new_display?

Because doing window.display = new_display, would require the user to know every detail about the display, and would also require them to create a display object. Apps have references to all the displays of a system and can assign a specific window to a specific display.

No - it requires you to have a reference to the display object. The user won't be creating a display object, because you can't "Create" a display. Something like window.display = app.displays[3] would be the API in practice.

And how does display interact with any other APIs? In particular, window.position and set_full_screen - the reason why display as an API came up in the first place?

set_full_screen should be deprecated in favour of the new window.state API. To keep backwards compatibility, we can the emulate the original behavior through a combination of window.state and app.displays APIs. window.position should return the position based the screen on which it is placed.

I really need you to read the things I have written previously, and if you disagree with them, provide a critique or counterargument. I have already explained that Full Screen is not a simple window state.

As for window.position - The current implementation will accept a position of (-1000, 100) as putting the window on the screen to the left of the "main" display. How does that interact with the concept of "displays"? Is position always display relative? Is there any way that relative positioning can be preserved? Would (-1000, 100) be interpreted relative to the current display? (or, indeed - should this behavior be preserved)?

If an app developer wants an app-wide full screen, why can't they just do:

for window in app.windows:
   window.state = WindowState.FULLSCREEN

Again - read my previous comments on this subject.

[proneon267]

I want to clarify one thing at a time. So, first is the full screen behavior:

Full screen. "full screen" isn't just "maximized" or "maximized without a titlebar". It's a very distinct mode that an app is in. It might be possible to represent this in a window specific API, but we need to be careful about that abstraction. A Slide presentation apps are the best exemplar of full screen mode (and is the reason full screen mode exists in Toga). "Start presentation" isn't something you do to 1 window. The app goes full screen, showing a slide deck on one screen, and speaker notes on a second screen. If you have more than 2 screens, the third screen has nothing on it. When the presentation is finished, the whole app goes out of full screen mode, and restores all the visibility of the windows of other apps your machine is running.

Maybe I am not understanding properly. So, I will explain what I have understood until now and you tell me if I am correct or wrong somewhere:

So, if I do set_full_screen() on an app. It will first make all the windows that were passed as arguments to it in fullscreen mode and then assign the full screened windows to the available displays.

As you explained, if there are 3 displays on the system then only the first two displays will be used and the third will not have anything on it.

If the above are true, then my question is:
Could the same not be achieved with:

slide_deck_window.state = WindowState.FULLSCREEN
slide_deck_window.display = app.displays[0]

speaker_note_window.state = WindowState.FULLSCREEN
speaker_note_window.display = app.displays[1]

From the cocoa implementation of set_full_screen():

def enter_full_screen(self, windows):
  ...
  for window, screen in zip(windows, NSScreen.screens):
    window.content._impl.native.enterFullScreenMode(screen, withOptions=opts)
    ...
  ...

Here, if I pass 2 windows then it will be doing(in pseudo code):
window[0] = enterFullScreenModeOn(screen[0])
window[1] = enterFullScreenModeOn(screen[1])

• If I do set_full_screen(window1,window2) then it will assign window1 to the first display and window2 to the second display.
• Now, if I do set_full_screen(window2,window1) then it will assign window2 to the first display and window1 to the second display.

If I am correct in the above statements, then could the same not be achieved with:

def enter_presentation_mode(windows):
  for window, display in zip(windows,app.displays):
    window.state = WindowState.FULLSCREEN
    window.display = display

@freakboy3742 If I am wrong somewhere, please correct me. I really want to understand what is the behaviour of the API that you want to be implemented.

[freakboy3742]

Maybe I am not understanding properly. So, I will explain what I have understood until now and you tell me if I am correct or wrong somewhere:

Your analysis is mostly correct - but there's one very important detail that you've missed in this part of the code:

for window, screen in zip(windows, NSScreen.screens):
window.content._impl.native.enterFullScreenMode(screen, withOptions=opts)

In this call, opts is a dictionary; the Objective C syntax is odd, but in Python, it would be the equivalent of {"NSFullScreenModeAllScreens": True} - so - when one window moves to full screen mode, the entire machine moves into "full screen mode".

It's also very important to note that the switch is a single call. A window enters full screen mode on a specific screen - it's not "move to a screen then start full screen mode". And the screen that the app goes full screen on isn't necessarily the screen it is currently on. When you exit full screen, the original screen assignment is restored.

So - if you have 3 screens, and 2 windows on screen 3, and you enter full screen mode, screen 1 will get the first window, screen 2 will get the second window. When you exit full screen mode, the windows go back to their original location on the original screens.

If I am correct in the above statements, then could the same not be achieved with:

def enter_presentation_mode(windows):
  for window, display in zip(windows,app.displays):
    window.state = WindowState.FULLSCREEN
    window.display = display

Not really. Or, at least, it would yield very different behavior. Reversing the order of the state and display assignment would result in different behavior; and the restoration behavior when exiting presentation mode would be different.

[proneon267]

If we do:

def enter_presentation_mode(windows):
  for window, display in zip(windows,app.displays):
    window.display = display
    window.state = WindowState.FULLSCREEN
    

Then, it would make it full screen on the selected display but the problem would be when we exit the full screen mode. After exiting, the windows would not be in their original screen, am I right?

If the above is true then could we not save the original screens on which the windows were present and do:

for window in windows:
  window.display = original_displays[window]

In proposed PR, we have:

elif window_state == WindowState.FULLSCREEN:
            opts = NSMutableDictionary.alloc().init()
            opts.setObject(
                NSNumber.numberWithBool(True), forKey="NSFullScreenModeAllScreens"
            )

            # Find the screen on which the window is present
            window_screen = None
            for screen in NSScreen.screens:
                if CGRectContainsRect(screen.frame(), self.native.frame):
                    window_screen = screen

            # Set the window to full screen mode
            self.native.enterFullScreenMode(window_screen, withOptions=opts)

This will set the window full screen on the display on which it is present. So, after exiting the full screen mode, the window will be on the display to which it was assigned. So, to completely emulate the set_full_screen(), we can do:

def save_original_displays():
  original_displays = dict()
  for window in app.windows:
    original_displays[window] = window.display
  return original_displays

def enter_presentation_mode(*windows):
  for window, display in zip(windows,app.displays):
    window.display = display
    window.state = WindowState.FULLSCREEN

def exit_presentation_mode(original_displays):
  for window in app.windows:
    window.display = original_displays[window]
    window.state = WindowState.NORMAL

original_displays = save_original_displays()
enter_presentation_mode(slide_deck_window,speakers_note_window)

#and then later on
exit_presentation_mode(original_displays)

[freakboy3742]

There's two parts here.

Firstly: renaming set_full_screen/exit_full_screen to enter_presentation_mode/exit_presentation_mode. I'Il admit I prefer the parity of enter/exit over set, with the added bonus of removing the use of a "pseudo-setter". However, I'm not sure what we gain in using the name "presentation mode" when the window state that it corresponds to is "full screen". enter_full_screen()/exit_full_screen() seems a preferable set of names for this feature.

Secondly: Most of your commentary about the implementation seems to be working around the fact that you're setting window.state and window.display as part of the call to enter fullscreen mode. These only seem to be required because you're trying to implement full screen mode in the interface layer in terms of the other window API primitives. Given that the cocoa backend clearly indicates that isn't a good mapping - why not introduce a backend API for entering/exiting fullscreen mode, and allow backends to determine whether there's a need for a specific implementation, or whether it can be implemented in terms of window primitives.

Essentially, there shouldn't ever be any ambiguity about which display a window is on, or what state the window is in. Property getters should be using the native API as the source of truth - so no matter which state you're in, you should be able to ask for the windows current state, and the native API will tell you the current state of the window.

[proneon267]

Yes, both of the properties are directly available from the native objects, with the exception of gtk. But gtk provides the methods which can be used to derive the proposed properties.

display seems like a better fit for the name as they correspond to physical displays. Screen seems a little vague as in certain APIs screen can be a singular entity spanning multiple displays.

[freakboy3742]

We're building an abstraction API over three platforms, all of which call the feature "screen". That's a pretty good signal that the feature should be called "screen".

I also don't understand your comments about "all properties are directly available, except on GTK". What are the API calls on each platform that (a) give you the list of displays, (b) allow you to access the name of the display, and (c) is there anything else common on those APIs that might be of interest.

[proneon267]

If you insist, we can change the name.

a) For list of displays:

• On WinForms: Screen.AllScreens
• On cocoa: NSScreen.screens
• On gtk:

Gdk.Display.get_default()
display.get_n_screens()
display.get_screen()

b) For name of the display:

• On WinForms: screen.DeviceName
• On cocoa: screen.localizedName
• On gtk: screen.get_display_name()

c) Yes, we can have the resolution of the displays, but that doesn't seem to have much use case as screen resolution doesn't correspond to physical size. We can have the working area of the displays, but again what will be its use case?

[proneon267]

@freakboy3742 Should I start on implementing this or do you have any other concerns?

[freakboy3742]

I think we've arrived at a final design - but it would be helpful to confirm that we're both on the same page. Could you produce a final summary that covers all the design (including both frontend and backend APIs), rather than the many disparate pieces spread over multiple comments and threads.

[proneon267]

For the frontend:

At the app level: app.screens
screens will be a tuple of Screen classes.

• Screen class will have the following attributes:
• Screen.name - The name of the display
• Screen.native - The handle of the native API's screen object
• Example usage:

# print the names of the displays
for screen in app.screens:
    print(screen.name)

At the window level: window.state

• window.state getter returns a value of WindowState enum class representing the current window state.
• window.state setter takes a valid value of WindowState enum class and an optional screen value which should be one of the elements of app.screens tuple.
• Example usage:

# Make full screen on the second display
window1.state = WindowState.FULLSCREEN, app.screens[1]

# Make maximized on the first display
window2.state = WindowState.MAXIMIZED, app.screens[0]

# Make full screen on the current display on which the window is present
window3.state = WindowState.FULLSCREEN

For the backend:

At the app level: query_screens() methods - Sets the app.screens variable as a tuple of Screen classes
For this, we will use:

a) For list of displays:

• On WinForms: Screen.AllScreens
• On cocoa: NSScreen.screens
• On gtk:

Gdk.Display.get_default()
display.get_n_screens()
display.get_screen()

b) For name of the display:

On WinForms: screen.DeviceName
On cocoa: screen.localizedName
On gtk: screen.get_display_name()

At the window level:

• get_window_state() method - returns the current state of the window as a value of WindowState enum class
• set_window_state(state, screen=None) - Here the default None value indicates to not change the display

No shadow variables will be used for getting and setting window states.

@freakboy3742 Does this look good?

[proneon267]

@freakboy3742 would you also take a look at this, please.

[freakboy3742]

Is there any reason that the API can't be completely independent? (i.e., window.screen = app.screens[0] and window.state = MAXIMIZED? Why does changing the min/max state need to be coupled to changing the screen?

[proneon267]

They absolutely can be independent operations.
I agree it should be.

But what about screen tuples? I had choosen tuples to prevent users from modifying it. What should we use instead of tuples?

[freakboy3742]

What do you mean by "screen tuples"? I'm not clear what role tuples play in any design. If you're assigning to a screen, assign to a screen. If you're setting a window state, set a window state. Where are tuples involved?

[proneon267]

The use of "assigning a tuple" is novel, but in is almost entirely unintuitive - what about the "state" property would lead the user to think that assigning a tuple would be valid?

I had mistakenly thought you were referring to the app.screens tuple. But, maybe you were referring to window1.state = WindowState.FULLSCREEN, app.screens[1] type of API assigning a tuple.

I'll write another summary to confirm that we are on the same page.

[proneon267]

@freakboy3742 I have created a new PR: #1911 that implements: #1884 (comment) . If you need any changes, let me know.

[proneon267]

For the frontend:

At the app level: app.screens
screens will be a tuple of Screen classes.

• Screen class will have the following attributes:
• Screen.name - The name of the display
• Screen.native - The handle of the native API's screen object
• Example usage:

# print the names of the displays
for screen in app.screens:
    print(screen.name)

At the window level: window.state and window.screen

• window.state getter returns a value of WindowState enum class representing the current window state.

• window.state setter takes a valid value of WindowState enum class except WindowState.FULLSCREEN.

• window.screen getter returns the name of the display on which the window is currently present.

• window.screen setter takes a valid element of app.screens tuple.

• Example usage:

# Make maximized on the first display
window1.state = WindowState.MAXIMIZED
window1.screen = app.screens[0]

# Set window1 full screen
app.set_full_screen(window1)
print(window1.state)                 # prints "WindowState.FULLSCREEN"

# This will raise a value error exception
window1.state = WindowState.FULLSCREEN

For setting windows FullScreen, existing APIs: Toga.App.set_full_screen() and Toga.App.exit_full_screen() should be used.

For the backend:

At the app level: query_screens() methods - Sets the app.screens variable as a tuple of Screen classes
For this, we will use:

a) For list of displays:

• On WinForms: Screen.AllScreens
• On cocoa: NSScreen.screens
• On gtk:

Gdk.Display.get_default()
display.get_n_screens()
display.get_screen()

b) For name of the display:

On WinForms: screen.DeviceName
On cocoa: screen.localizedName
On gtk: screen.get_display_name()

At the window level:

• get_window_state() method - returns the current state of the window as a value of WindowState enum class
• set_window_state(state, screen=None) - Here the default None value indicates to not change the display

No shadow variables will be used for getting and setting window states.

@freakboy3742 Does this look good?

[freakboy3742]

For the frontend:

At the app level: app.screens screens will be a tuple of Screen classes.

No. It should be functionally returning a list, and documented as contractually returning an iterable. A tuple isn't an "immutable list". It's a data structure where items don't need to be homogeneous, and position in the structure conveys meaning, but iteration order isn't that meaning. For example, an (x,y,z) point is a tuple, because being in position 0 means the coordinate is the x coordinate, but there's no particular significance to the fact that the x coordinate comes before the y coordinate other than convention. The list of attached displays are homogeneous, and there's no inherent meaning to the position in the list.

• Screen class will have the following attributes:
• Screen.name - The name of the display
• Screen.native - The handle of the native API's screen object

This design misses the impl layer. The public interface provides an API, but it needs to be implemented on each backend. There shouldn't be a native object on the public API.

At the window level: window.state and window.screen

• window.state getter returns a value of WindowState enum class representing the current window state.
• window.state setter takes a valid value of WindowState enum class except WindowState.FULLSCREEN.
• window.screen getter returns the name of the display on which the window is currently present.

No - the name of a display isn't an inherently useful property (and isn't a property that can be used as a key with this API as proposed). It should be possible to say window1.screen = window2.screen to co-located two windows on the same screen.

• window.screen setter takes a valid element of app.screens tuple.

This is an incredibly confusing way of expressing the idea window.screen can be assigned a screen instance. You appear to be giving some special significance to the "tuple" that is the return value of the app.screens property. Is there a reason for this?

Set window1 full screen

app.set_full_screen(window1)
print(window1.state) # prints "WindowState.FULLSCREEN"

This isn't an especially helpful example, given that the primary use case is making multiple windows full screen.

The current API allows for app.set_full_screen(window1, window2); I'd argue it should also allow for app.set_full_screen({app.screen[0]: window1, app.screen[2]: window2}). This may require a backwards incompatible change so that the former example becomes app.set_full_screen([window1, window2]) - at the very least, all 3 forms should be permitted.

This will raise a value error exception

window1.state = WindowState.FULLSCREEN

For setting windows FullScreen, existing APIs: `Toga.App.set_full_screen()` and `Toga.App.exit_full_screen()` should be used.

# For the backend:
**At the app level**: `query_screens()` methods - Sets the `app.screens` variable as a tuple of `Screen` classes For this, we will use:

Not sure why you've gone with query_ rather than get_

At the window level:

• get_window_state() method - returns the current state of the window as a value of WindowState enum class
• set_window_state(state, screen=None) - Here the default None value indicates to not change the display

No shadow variables will be used for getting and setting window states.

... or for getting and setting current screen for a window.

It's worth noting that you'll likely need a shadow for the list of screen instances at the impl layer, unless you're going to come up with a novel way to make Screen instances hashable or comparable. That's not a shadow variable - it's an impl instance cache.

[proneon267]

No. It should be functionally returning a list, and documented as contractually returning an iterable. A tuple isn't an "immutable list". It's a data structure where items don't need to be homogeneous, and position in the structure conveys meaning, but iteration order isn't that meaning. For example, an (x,y,z) point is a tuple, because being in position 0 means the coordinate is the x coordinate, but there's no particular significance to the fact that the x coordinate comes before the y coordinate other than convention. The list of attached displays are homogeneous, and there's no inherent meaning to the position in the list.

I had choosen tuple to prevent users from modifying app.screens. How will I prevent it from being changed?

This design misses the impl layer. The public interface provides an API, but it needs to be implemented on each backend. There shouldn't be a native object on the public API.

I agree. I will modify the Screen object.

No - the name of a display isn't an inherently useful property (and isn't a property that can be used as a key with this API as proposed). It should be possible to say window1.screen = window2.screen to co-located two windows on the same screen.

So, it should just return the Screen object.

This is an incredibly confusing way of expressing the idea window.screen can be assigned a screen instance. You appear to be giving some special significance to the "tuple" that is the return value of the app.screens property. Is there a reason for this?

No particular reason. I had just mentioned it since it is the return type of app.screens.

The current API allows for app.set_full_screen(window1, window2); I'd argue it should also allow for app.set_full_screen({app.screen[0]: window1, app.screen[2]: window2}). This may require a backwards incompatible change so that the former example becomes app.set_full_screen([window1, window2]) - at the very least, all 3 forms should be permitted.

I agree, all 3 formats should be permitted.

Not sure why you've gone with query_ rather than get_

We can change the name, if you want.

... or for getting and setting current screen for a window.
It's worth noting that you'll likely need a shadow for the list of screen instances at the impl layer, unless you're going to come up with a novel way to make Screen instances hashable or comparable. That's not a shadow variable - it's an impl instance cache.

I'll research more and will update you with what I come up with.

[freakboy3742]

Why do you need to use get_platform_factory() at all? get_platform_factory() is used because we have a public interface, the user uses that interface to construct an interface object, and it needs to be backfilled with an impl. That's the exact opposite of the construction order for Screen.

[proneon267]

If I don't need get_platform_factory(), then can I directly use the backend Screen class's constructor for setting the _impl attribute of the frontend Screen class?

[freakboy3742]

I'm not sure I fully understand the question... if you're asking if you can pass in an _impl to the constructor of the interface-level Screen instance, then... yes.

[proneon267]

Thanks. That's what I was asking for :)

[proneon267]

@freakboy3742 I have implemented the API for the above and created #1930. Please check it out and let me know.

[proneon267]

Now that #1930 is completed, we need to discuss the design for window state API. Earlier, we had discussed about the possibility of a window.state on the public API:

• window.state getter returns a value(MAXIMIZED/MINIMIZED/NORMAL/FULLSCREEN) of WindowState enum class representing the current window state(including WindowState.FULLSCREEN).
• window.state setter takes a valid value of WindowState enum class(excluding WindowState.FULLSCREEN).

For setting in full screen mode:

• app.set_full_screen({app.screens[0]: window1, app.screens[2]: window2})
• app.set_full_screen([window1, window2])

On the backend:

• get_window_state() method: Returns the current state of the window as a value of WindowState enum class.
• set_window_state(state, screen=None): Sets the window state on a specified screen. Here the default None value indicates to not change the screen.

Do you think this is good or do we need any changes? Let me know.

[freakboy3742]

the behavior should be Window Full Screen but this is an archived document, and I am not sure about the current recommendations for macOS.

That document may be archived, but the behaviour it describes seems consistent with current macOS behavior. The green button on an app's window (the button that would be "maximise" on Windows/Linux) creates a new space that holds just that window, with the menubar and toolbar being visible. That's distinct from the "presentation mode" that you get with a slideshow app.

For other platforms the native behavior is Window Full Screen. So, which one should we choose or should they both be present?

I think it would be worth supporting both. Even if the underlying mechanism for implementing "full screen" on Windows and Linux is the same, there is a functional difference: whether the menu and toolbar is visible. The menu/toolbar for a window needs to be hidden when invoking from the App fullscreen API, but present in the Window fullscreen API.

It may also be worth renaming App level "full screen" to "presentation mode" or something similar, to make this distinction clear. Having 2 "full screen" APIs is conceptually confusing; using a distinct name would be preferable (although I'll note that the existing API is enter_full_screen, not set_full_screen; I'd lean to keeping the "enter" prefix, as it reflects the "computer wide" state that is being entered, not just "setting" a value).

Lastly, if we support both, there's the interaction between "presentation mode" and the window state to consider. Differentiating between the two would seem to suggest there's a need for a WindowState.PRESENTATION value, in addition to WindowState.FULLSCREEN.

[proneon267]

I agree, WindowState.PRESENTATION is what was missing from the API proposal. I think I can also implement something like that on windows and Linux backends.

[proneon267]

Should non-resizable windows be allowed to change window states? I mean, making a non-resizable window maximized or full screen would mean changing the size of the window, which would contradict the purpose of a non-resizable window.

Related bug on winforms: The current non-resizable behavior of a window(on winforms) is just to disable the maximize button, but the window can still be resized by the user by dragging the borders. This isn't the correct behavior and needs to be corrected(Maybe I'll include the fix in the PR).

[freakboy3742]

On macOS if a window is resizable=False, the "full screen" button is disabled, and the "double click on title bar" behavior that makes the window as big as the screen it is on is also disabled. I haven't tried putting the window into presentation mode; my guess is that it will technically be possible, because it's based on the content of the window, not the window itself - but this seems like an edge case of interpretation, rather than intended or desirable behavior.

On that basis, I'd argue that attempting to set the window state of a non-resizable window to MAXIMIZE/FULLSCREEN/PRESENTATION should raise an exception.

I can't reproduce the resize behaviour you're describing, though - if I make a window resizable=False, resizing by window handles is disabled. However, it's possible this is Win10 vs Win11 discrepancy; I'm on Win10.

[proneon267]

On further investigating, the bug was caused because I had commented out the line:

toga/winforms/src/toga_winforms/window.py

Line 42 in f9fae85

self.set_full_screen(self.interface.full_screen)

which unintuitively also sets the window border based on window.resizable. I have resolved it now. Btw, I am working on the new API on a separate branch on my fork of toga: https://github.com/proneon267/toga/tree/window_states. I haven't opened a PR to prevent wasting of CI resources before I have implemented the features. I'll open the PR once I am done.