xdg-activation: guidance needed on intended usage

While trying to determine why the "draw attention to window" feature of the Signal desktop doesn't work on native Wayland (on Sway), I found that everything is terrible Gtk and Qt don't fully agree on how xdg-activation is supposed to be used.

xdg_activation_v1_activate documentation currently says: "It's up to the compositor to display this information as desired, for example by placing the surface above the rest." This leaves a lot of room for interpretation where applications/toolkits can't be sure what compositor behaviors are possible and which aren't:

• Sway only sets an urgency hint in the window decoration and taskbar by default to prevent focus stealing
• Do any other compositors actually change focus or raise the surface?

---

Some background on what the current implementations do, as far as I could figure it out:

• On Qt6, a QWindow has requestActivate() and alert() methods

  • On Wayland (with the xdg-shell integration plugin):
    • requestActivate() calls xdg_activation_v1_activate, either based on the XDG_ACTIVATION_TOKEN env var, or doing the whole set_surface/app_id/serial/commit dance
    • alert() also uses xdg_activation_v1_activate, always requesting a new token while omitting the set_serial call
  • On X11:
    • requestActivate() sends _NET_ACTIVE_WINDOW to the WM
    • alert() sets the _NET_WM_STATE_DEMANDS_ATTENTION state

  Is not setting the serial supposed to make the big difference on Wayland, to distinguish between a focus request and an alert that should not change focus?

• On Gtk3, there's gdk_window_focus() and gdk_window_set_urgency_hint()

  • On Wayland:
    • gdk_window_focus() matches Qt6's request_activate()
    • gdk_window_set_urgency_hint() does nothing (this is what break's Electrons flash_frame() and thus Signal's "draw attention to window"
  • On X11:
    • gdk_window_focus() sends _NET_ACTIVE_WINDOW to the WM
    • gdk_window_set_urgency_hint() sets the XUrgencyHint WM hint

• On Gtk4

  • gdk_toplevel_focus() matches Gtk3's gdk_window_focus() and Qt6's request_activate()
  • gdk_window_set_urgency_hint() has been pushed down to become a backend-specific method (gdk_x11_surface_set_urgency_hint(), gdk_win32_surface_set_urgency_hint()), which is unimplemented on Wayland (arguably better than having a function that just does nothing on Wayland...)

---

Is the behavior of Qt6 the "correct" one here, and creating a token without set_serial is a valid way to draw attention to a window without having the compositor raise or focus it (if the compositor supports such a thing as an "urgency" state)? If this is indeed the case, I can send an MR to clarify this in the protocol documentation and will try to get Gtk's implementation to follow.