New Backend - Qt

[johnzhou721]

WIP: Fixes #1142

PR Checklist:

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

[johnzhou721]

@freakboy3742 By now I have not added CI testing yet because the test skips have not yet convereged at 100%

This is rough, I need to go back and clean up comments (especially some random jokes I've made -- if you have spare time I give you permission to try to spot them) but a few things I need confirmation on:

• Is using linux_qt as the platform identification name okay with you? It detects this platform when TOGA_QT is set to 1 or if the application is running under KDE now.
• I've mentioned the PySide6 import hack before -- specifically doing this:

import site
import sys


def import_pyside6():
    """Temporarily break isolation to import system PySide6."""
    system_site = site.getsitepackages()
    print(system_site)
    old_path = sys.path.copy()
    sys.path.extend(system_site)
    import PySide6  # noqa

    sys.path = old_path


import_pyside6()

So if beeware/briefcase#2480 (which I've filed for a feature to replace installed PySide6 with system symlink when packaging an app) doesn't get resolved in the duration of this PR, should I still remove this hack such that the new backend will not be able to look native and access system themes?

• I've added a NativeIcon class to icons as seen at

  toga/core/src/toga/icons.py

  Lines 35 to 42 in 3028865

  	class NativeIcon:
  	"""
  	For internal use for Qt backend only
  	"""
  	def __init__(self, native): # pragma: no cover
  	self.factory = get_platform_factory()
  	self._impl = self.factory.NativeIcon(native)

  since native icons are needed for undo and redo actions in Qt -- see

  toga/qt/src/toga_qt/app.py

  Line 114 in 3028865

  icon=NativeIcon(QIcon.fromTheme("edit-undo")),

  (it demands an interfaced icon there). Is this acceptable, and if not, how should I deal with this situation?

Thank you!

[johnzhou721]

@freakboy3742 Could you please respond to those questions I've asked about above? Thank you!

[freakboy3742]

@freakboy3742 By now I have not added CI testing yet because the test skips have not yet convereged at 100%

This is rough, I need to go back and clean up comments (especially some random jokes I've made -- if you have spare time I give you permission to try to spot them) but a few things I need confirmation on:

• Is using linux_qt as the platform identification name okay with you? It detects this platform when TOGA_QT is set to 1 or if the application is running under KDE now.

No. Platform identification is only used because sys.platform isn't a reliable identifier on Android (and, a long time ago, wasn't a reliable identifier on web). Once Python 3.13 is the oldest supported release, toga.platform.current_platform should be deprecated.

You'll also note that the current GTK backend doesn't describe its platform as GTK - it's linux.

The approach used by Textual is the model to follow here. If you're on Linux, toga_qt is a candidate backend; if that's the only backend, it's used; if there's more than one candidate installed in the current environment, TOGA_BACKEND=toga_qt disambiguates.

• I've mentioned the PySide6 import hack before -- specifically doing this:
  ...
  So if beeware/briefcase#2480 (which I've filed for a feature to replace installed PySide6 with system symlink when packaging an app) doesn't get resolved in the duration of this PR, should I still remove this hack such that the new backend will not be able to look native and access system themes?

For now, I'd say yes. We can only cook with the ingredients we're given. If Qt doesn't work in virtual environments, that's a problem for Qt to resolve. It's not up to us to work around it - if only because there may be use cases for not adopting the global environment.

If there's a hack that could be installed, I'd argue the system_pyside6 approach I've described previously is the way to install that hack.

• I've added a NativeIcon class to icons as seen at

  toga/core/src/toga/icons.py

  Lines 35 to 42 in 3028865

  	class NativeIcon:
  	"""
  	For internal use for Qt backend only
  	"""
  	def __init__(self, native): # pragma: no cover
  	self.factory = get_platform_factory()
  	self._impl = self.factory.NativeIcon(native)

  
  since native icons are needed for undo and redo actions in Qt -- see

  toga/qt/src/toga_qt/app.py

  Line 114 in 3028865

  icon=NativeIcon(QIcon.fromTheme("edit-undo")),

  
  (it demands an interfaced icon there). Is this acceptable, and if not, how should I deal with this situation?

In core - No - or, at least, there's a much bigger concept that needs to be wrapped here. If the underlying question is about "system icons" - GTK has an analogous concept, which we don't currently handle. See #2441 for some initial thoughts about this (although it doesn't mention the GTK analog that exists).

[johnzhou721]

@freakboy3742 Thanks for the responses, there's much going on and I'm in the middle of a major comments cleanup (it's done through GitHub's review interface so expect a huge email next week with all the ntoes I made for myself, sorry about that)

Re to response 1: Then how the heck am I gonna get all the tests skipped by platform? Do I need a bunch of stub probes to just say "skip on Qt", sort of like GTK4?

Anyways if there's 1 platform only also for Briefcase how do we handle the testbed then? Right now I used tests_backend_qt for qt probes and hacks it at conftest.py: https://github.com/beeware/toga/pull/3769/files#diff-b845936988736dd9f884ab2aeb4175fa8ee7914217ed87d3c8aad18f803e74f0R24-R33 -- I can check the backend there [b]ut (EDITED TYPO) it just feels messy to have a hack like that at all.

Re to response 2: IMO system-pyside6 for symlinking system packages is not feasible. With all this wheel madness going on you simply don't know where the final system-pyside6 package even gets installed and you can't put symlinks in wheels either (it extracts as plain text when extracted by pip, which uses its own extraction logic). There's some options for "build destination" in setup.py but that's to like an intermediate location. Should I extract this sys.modules hackery into a system-pyside6 package that installs a shim PySide6.py to replace itself, then?

Re to response 3: Yeah, but it'd look really weird on Qt without like a native icon attached to the actions. KDE inserts extra space before an action with no icon to fill up for the icon space.

[johnzhou721]

@freakboy3742 Also do you think that beeware/briefcase#2480 is a candicate issue to be handled on Briefcase? Or are we like if PySide6 doesn't work it doesn't work and we're not going to have our packaging tool symlink a system copy?

[johnzhou721]

Welp... I've been told that I'd need a few hours between writing and posting a message... but then after I posted my last set of comments this morning, I came up with some other stuff that I needed to make note of... sorry about that.

[johnzhou721]

I've noted before that the sizes aren't round-tripping exactly on windows in Qt sometimes, however I've found that in all the cases I've found, a setMinimumSize directive will actually force the window size to round-trip exactly from what we gave Qt as the window size... so there's no concern of an infinite loop here.

[freakboy3742]

Does setMinimumSize() then prevent the window from becoming any smaller? I'd be concerned about a call to set_size() then forcing a new limit on the size of the window.

[johnzhou721]

Yes, it does prevent the window size from getting smaller. The set_size calls will force the exact same size as the setMinimumSize call forces the minimum to be.

[freakboy3742]

Ok - then that's not a fix for the problem. Setting a size sets the current size of the window, not the minimum size of the window.

[johnzhou721]

@freakboy3742 I apologize but I have slightly lost you here. Not a fix for which problem? You mean for like the window-size-does-not-round-trip-exactly problem? Or like a potential infinite loop on this function when it keeps trying to enforce the minimum window size but never does it because it didn't round trip?

[johnzhou721]

@freakboy3742 I think I understand what you are talking about now, and I apologize for some confusion here.

Right here is the code for container_refrehsed (it's content_refreshed in Cocoa/iOS, I'll push a rename later) which is the on_refresh handler of the Container object.

set_size doesn't use setMinimumSize as a workaround. If you specify a window to (300, 200) on X11 with 175% scaling it will give you (299, 200). So setMinimumSize is not used there. The docs say users should not make UI decisions based on window size or position anyways, since tiling window managers etc., so my understanding is that this is not that big of a concern.

container_refreshed here, on the other hand, is when we recompute our layout and impose a minimum size on the window. I am not very sure about if we use setMinimumSize here on the container directly if it'll work properly if the container is in a different size when I wrote this code at first; so I explicitly set the size of the window first, and then constrain Qt to the new minimum size. I think setting minimum size at container_refreshed is the correct solution because any thing that might change the minimum size would cause another container_refreshed and the minimum size will be updated.

The issue I was concerned about with this approach is that if size doesn't round-trip properly, the if branches will re-trigger because it's just 1 or 2 short of the correct width/height and pump another window resize event, which causes container to refresh again and trigger an infinite loop. I was saying that setMinimumSize has the side effect of stopping this kind of error, but that doesn't mean we're relying on it elsewhere than the function here.

That said, it seems like if setMinimumSize is invoked on children, the window will automatically expand to the correct size in Qt, so we don't have to worry about setting our window size manually, just the container's minimum layout size. So I'm removing L147-L149 on the line numbers on this comment.

@freakboy3742 If you disagree with anything here, please let me know, or if I've confused you again, I apologise. In all cases, let me know and I'll resolve this.

[johnzhou721]

@freakboy3742 I've resolved most of your comments and am waiting response on some of them, after which I would consider this PR ready for a final review.

However it seems that Briefcase sdisting is not parsing [optional extra groups] properly... any ideas on how to fix this? Should I just repeat system-pyside6 additionally in the testbed?

[freakboy3742]

I've given this another review pass; it's getting close to the point where it's mergeable (or, at least, it's good enough that merging means we have a manageable base for future work, rather than trying to review changes to a 130 file behemoth).

At this point, the only major concerns I have are:

1. The minimum size fix for size roundtripping.
2. The timer/callback based approach to window resizing. Having a mechanism in place that has potential to recursively cascade is definitely inadvisable
3. The additional fixes to the actions workflows to fully incorporate Qt into the release process.

[freakboy3742]

I'm surprised so many GTK/Gnome libraries are required here. Are you sure this is a minimal set?

[johnzhou721]

See https://doc.qt.io/qt-6/linux-requirements.html -- this is the list.

gnome-session-canberra is used for App.beep -- QApplication::beep does not work if pcspkr which is a very bad-noised module is enabled, and the proper way to do it in KDE is through KNotifications -- but then we'd have to bundle a .knotifyrc file which we currently does not support in Briefcase AFAICT, and that needs a meaningful event name. So we just use libcanberra here (canberra-gtk-play command line actaully) to play the freedesktop.org sound theme.

EDIT -- would it perhaps be more preferrable to use something like https://pypi.org/project/py-canberra/ for sounding the bell rather than calling it through the command line?

Wonder why it's called Canberra though... sounds weirdly nice.

[johnzhou721]

For the App.beep thing, the problem seems to be that QApplication.beep isn't implemented at all on Wayland... also KNotifications upon further research seems to be that each app can declare notification types and in System Settings you can tweak what sort of action you want these notifications to make... that leaves libcanberra being the only way we could possibly play a bell sound.

Integrating libcanberra from the python side is nontrivial... the way to play a sound from the correct theme seems to be using its gtk integration, which requires a gtk event loop, but we already run a Qt event loop in our applications. Else we can hardcode a sound theme, but I think the goal of Toga is to be native as much as possible, and users might customize sound themes... so that's why despite discouragement from doing so, I'm using canberra-gtk-play in a subprocess.Popen for playing App.beep. Sorry for commenting on unrelated thread.

EDIT -- clarification: it's using some asyncio internal utils, not subprocess.Popen for ResourceWarning to not happen.

[freakboy3742]

Do we need to test both X11 and Wayland? Given this is (a) a pre-alpha prototype, and (b) a new backend, it seems like just testing on Wayland is probably sufficient for now.

[johnzhou721]

Major concern for this is Window States handling. X11 has some quirks where you can't directly go through some window states, and Waylnad window state handling is completely different from X11. Given that I need a final go/no-go confirm from you to remove x11 tests.

[freakboy3742]

This document would be better split into two distinct halves - one for GTK, and one for Qt. The "GTK or Qt" references are a but cumbersome; and beyond high level "what options are available?" research, a user who is looking for information will only be looking for one or the other.

[freakboy3742]

It should also be clear that GTK is a mostly complete, fully supported backend; and Qt is a early alpha work in progress.

[freakboy3742]

Again - surprised at the amount of GTK stuff here.

[johnzhou721]

See my reply on Comment on lines +351 to +359

But also -- I'm installing all the x11 deps for Wayland as well (and the converse) because we don't list X11 and Wayand deps separately in the docs, so if the user just install all those packages and they happen to interact weirdly, we need to get those things caught in CI so we can resolve them.

[freakboy3742]

I've got this terrible feeling of deja vu... :-)

[johnzhou721]

@freakboy3742 Can you elaborate? Thanks.

[freakboy3742]

Re-read lines 23-26. Notice anything familiar?

[freakboy3742]

Does a "default icon" behave the same as "No icon"? i.e., setIcon(None) isn't an option here?

[johnzhou721]

@freakboy3742 No, it is not an option. QIcon() is the way to clear the icon: https://stackoverflow.com/questions/27108130/how-can-we-delete-icon-from-qpushbutton

[freakboy3742]

Ok - then that's not a fix for the problem. Setting a size sets the current size of the window, not the minimum size of the window.

[freakboy3742]

This is effectively a platform-specific test, as Qt is the only backend that enables the flag. At the very least, Cocoa has an Undo/Redo menu item; is there a reason that this test can't be extended for other platforms? Essentially I want to make sure that either (a) this is a behavior that is very specific to Qt, or (b) the test is written in a way that it could be implemented on other platforms.

[johnzhou721]

Behavior is specific to Qt. macOS has menus disabled automatically by the operating system when you Copy and Paste, so it does not make sense to invoke a disabled action to make sure it's a no-op. The native handler cut: does nothing on a readonly textfield, but it'd be a lot of effort to implement all the probes for Cocoa.

The behavior itself is specific to Qt because in Qt it's not easy to automatically have things like Edit > Cut disabled on a readonly widget automatically, so the Edit > Cut action is still enabled to the user. This is the part we want to test that it works properly -- even if it's enabled, it does nothing. In Cocoa it isn't even enabled.

[johnzhou721]

@freakboy3742 Most comments are replied to inline; thanks for working through this with me.

On

• The timer/callback based approach to window resizing. Having a mechanism in place that has potential to recursively cascade is definitely inadvisable

I'm not so sure on what else to do either... nasty things like automatically window's state being put back to normal will happen if we do window state transitions too fast... One thing I can do is terminate the chain early if the window state changed to the correct one already. However given the unstableness of all the stuff in Qt... I'd rather not really do that and wait a moment before we finalize the window state change. That'd make MINIMIZE putting into work because by the time the next extra WindowState==NORMAL change event emmitted whenever we put stuff into MINIMIZED. Would you like me to try that?

---

EDIT -- I am adapting that approach. Seems to work.

---

EDIT 2 -- Actually... it didn't. @freakboy3742 The problem is like this -- if you stuff in too many window state transitions too fast, weird things happens. So we need to delay the clearing of pending window state; that way we can achieve the effect of "no one do anything in the following 100ms". So the approach I suggested ultimately did not work out as intended.

I'll be attaching some diagrams here showing some stuff about this tomorrow.

[johnzhou721]

@freakboy3742 This is what the window state transitions look like when you reviewed. A few labels are in the diagram below -- the first timeline is the current state of this PR which is a fix I tried to prevent recursing MINIMIZED (look at the third diagram that the first approach catches the first MINIMIZED event), however it's flawed.

What I'm trying to get at here is that in the third diagram, we see that the cause of the recursion is that Qt under Wayland can't round-trip the correct window state a while later. MINIMIZED is sort of special here that it has this bug. But all the other window states would round-trip correctly under both X11 and Wayland. But then I'd argue that if reading the window state isn't even reliable, we'd just dissupport window states entirely. But reading the window state is reliable in non-minimized case. To summarize -- recursion only happens when you request a window state but it consistently does not roundtrip correctly, and if this happens in any other cases, they should be pretty rare and in my opinion it would be obvious what the issue is.

Comments on this?

[johnzhou721]

@freakboy3742 The CI is green and I have responded to almost all comments we have made and made modifiations for the rest accordingly. I need response on the things I'm asking you inline for, and another review from you. Thanks for working me through this!

P.S. Sorry for the repeated small commit pushes, my laptop is literally burning as I'm writing a draft for a book while I'm waiting for CI, I have a VM running that I just realized I forgot to close, so I did not run the testbed locally before pushes.