Add Wayland/GNOME support

[juljimm]

Add full Wayland support for GNOME Shell using the Window Calls extension.

Features:

• Window management via D-Bus (move, resize, maximize, minimize)
• Cycle through window sizes (left, right, corners, etc.)
• Vertical and horizontal maximize with toggle support
• State persistence between invocations
• GNOME custom keybindings integration (since Wayland blocks global hotkeys)

New files:

• quicktile/wayland_wm.py: Wayland window manager backend
• quicktile/wayland_keybinder.py: Wayland keybinding support
• setup-wayland-keybindings.sh: GNOME keybindings configurator
• install-wayland.sh: One-line installer for Wayland
• run-quicktile.sh: Wrapper script for running QuickTile
• WAYLAND.md: Detailed Wayland documentation
• tests/test_wayland_wm.py: Unit tests for Wayland backend

Requirements:

• GNOME Shell
• Window Calls extension (https://extensions.gnome.org/extension/4724/window-calls/)

[ssokolow]

Thanks. :)

Is there a particular distro you'd recommend I pull off https://www.osboxes.org/ for testing this?

(I'm very much a KDE user and don't want to gamble on apt-geting GNOME mucking up something in which implementation of some system service gets run.)

[juljimm]

Thanks. :)

Is there a particular distro you'd recommend I pull off https://www.osboxes.org/ for testing this?

(I'm very much a KDE user and don't want to gamble on apt-geting GNOME mucking up something in which implementation of some system service gets run.)

Hi! Ubuntu would be a good choice since that's what I use for development. Any recent LTS version (22.04 or 24.04) should work fine — they come with GNOME by default.

[ssokolow]

Thanks. :)
Is there a particular distro you'd recommend I pull off https://www.osboxes.org/ for testing this?
(I'm very much a KDE user and don't want to gamble on apt-geting GNOME mucking up something in which implementation of some system service gets run.)

Hi! Ubuntu would be a good choice since that's what I use for development. Any recent LTS version (22.04 or 24.04) should work fine — they come with GNOME by default.

Funny thing about that. I'm on Kubuntu 24.04 LTS right now (granted, with snapd ripped out and blacklisted and replaced with flatpaks), so it really is just "I don't want to risk a GNOME installation messing with which providers get started for which D-Bus services.)

...so yeah. Shouldn't be a problem. I'll try to fit it in for some time over the next few days. If it turns out GNOME is still as bad at running at a usable speed in VirtualBox as I remember, maybe I'll pull out one of the hand-me-down laptops I was planning to use to test out the KDE Wayland session without risking my daily driver desktop.

[ssokolow]

Sorry for the delay. I forgot I had some stuff running in KVM that I normally don't need to leave running for an extended period of time and that VirtualBox's AMD-V support doesn't work at the same time as KVM's.

I'd rather not futz around with adding a new KVM-based VM but I'll try to get that wound down as quickly as possible so I can spin up the Ubuntu VM.

[ssokolow]

OK, the VM is too sluggish. While I wait for the ISO to download to put Ubuntu 24.04 on one of my spare laptops, here's what I've noted that one of us will need to do from just reading through it: (I'm not using GitHub's code review since a lot of these aren't tied to a specific line of code)

1. The placeholder you're using in __author__ will need to change. Given the information already baked into your commit headers, I'd suggest Julio Jiménez (juljimm) for yourself for anything where the only thing you copied from existing code was the shape of the API.
2. The winman argument on QuickTileApp.__init__ needs a new type annotation.
3. The logging.critical code you copied only outputs exclusively to the terminal because it's reporting inability to connect to the X server. If GTK can connect to Wayland but the Window Calls extension is missing, the error should also be displayed in a form that doesn't require a terminal to be open to minimize the odds users will miss it and wind up on my GitHub issue tracker. (In other programs, I've typically mirrored the error between the console and a Gtk.MessageDialog as the most fool-proof way to get the message in front of the user.)
4. I'll need to refresh my memory, but I remember there being a ready-made GTK function which does what your # Build GNOME Shell format accelerator block is doing.
5. parse_accel on the Wayland side is vestigial. Nothing calls it, and it's just renaming a GTK function.
6. As a KDE user who won't be on X11 forever, I'm definitely going to have to restructure it so it doesn't conflate Wayland with "this specific GNOME shell extension". (Among other things, I have plans to switch from libwnck to libxfce4windowing, which intends to support Wayland to varying degrees depending on which compositor is in use.)
7. I'll want to rework QuickTileApp.__init__'s arguments so nonsensical combinations of winman and use_wayland are impossible. (eg. Passing an X11 WindowManager and use_wayland = True or vice-versa.)
8. __main__.py is starting to get messy, so i'll probably move a lot of it into the x11 and gnome_shell modules I'm imagining and clean it up so it only cares about "which backend".
9. Some of your if not use_wayland conditionals look like they might break non-keybinder (ie. CLI invocation or D-Bus invocation) users on Wayland, so I'll be sure to test those as soon as I've got the laptop set up.
10. The layout.py changes for lines 210 through 212 look wrong. My first impulse is that users should be free to configure whatever crazy tiling sequence they want and, if that's fixing a problem with the earlier code's output, then the earlier code is where the fix should go. (eg. I find it very frustrating that, at some point, the Geeqie image viewer started refusing to allow images to be added to collections more than once, despite them just being lists of paths under the hood.) I'll take a closer look at it later.
11. I'll probably want to use this as an opportunity to check off "Migrate the D-Bus backend to GDBus" on my TODO list since you're already depending on it for the GNOME Shell stuff.
12. I'm going to need a little more time to familiarize myself with quicktile/wayland_wm.py before I've got a full idea of how to make it maximally maintainable. (Mostly refreshing my memory of my own code so I can identify bits which only exist for consistency with the rest of QuickTile and can be YAGNI'd away with the aid of patches elsewhere... but I do also want to think on an approach to feed those "not available" statuses back up in a machine-readable format so the other layers of QuickTile can do things like marking which actions are unavailable.)
13. I'll probably want to deduplicate a bunch of that X11 vs. GNOME Shell WindowManager stuff with a parent class. (eg. The logic of _geometry_matches should be the same either way.)
14. Archwiki says that XDG_RUNTIME_DIR is not required to have a default value, so the code for persisting state should handle that case, and also handle it existing but not containing a tmp subdirectory. (Since I'd prefer not to play tech support for people who just want QuickTile to work when I can anticipate and prevent it.)
15. Archwiki also says that XDG_RUNTIME_DIR may be subject to periodic cleanup, and that files should either be modified every six hours or have their sticky bit set if persistence is desired. (In the latter case, I'll want to implement manual cleanup on QuickTile shut down)
16. Re: install-wayland.sh, I'd prefer not to encourage piping random downloaded .sh files into bash. In fact, one of the things I wanted to get around to was reworking QuickTile to have Flatpak as the official distribution mechanism.
17. Re: the README, I'd prefer to explicitly state that Wayland support is for GNOME Shell, is in beta, and is done on a best-effort basis. (Since I still run X11, GNOME Shell doesn't like to run in a VM which makes it a hassle to QA test, and I will continue to run KDE Plasma when I switch to Wayland.)
18. Why did you add a run-quicktile.sh which duplicates quicktile.sh except with the edge-case handling stripped out?
19. setup-wayland-keybindings hard-codes home/leone/apps instead of using something like $(dirname "$0")
20. Your approach to keybindings in GNOME is more complicated than I'd like... especially when I'm half-way to releasing a GUI for editing them which should allow X11 users to update them without restarting QuickTile. If setup-wayland-keybindings.sh means they need to be edited in gsettings, maybe it'd be better to just unconditionally use https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.GlobalShortcuts.html like I was planning to use with anything that libxfce4windowing has sufficient support for.
21. Please also add yourself to docs/authors/index.rst and run docs/update_authors.sh to update the AUTHORS file.

All in all, mostly a bunch of tiny nitpicks mixed with some restructuring that'll have to be something I take responsibility for.