Skip to content

staging: Add xdg-toplevel-icon to allow windows to set dedicated icons

Matthias Klumpp requested to merge mak/wayland-protocols:wip/ext-window-icons into main

Hi everyone!

Here is yet another controversial protocol, but I think it is a lot easier to discuss pros and cons if there is a concrete proposal to discuss. This MR is intended to fix feature-request #52 (closed): Adding icons to toplevel windows explicitly, rather than relying on them being pulled from desktop-entry files via the appId reference.

Rationale

Honestly, for the longest time I didn't think we needed this protocol, because I quite like the current Wayland design: Icons should come from the environment, which ensures a consistent experience with no surprises. For specialty apps, I assumed they could just create a hidden desktop-entry file and pull the icon from there, and everyone would be happy, no need to drag support for this into Wayland. Especially since the XDG icon theme spec already has robust support for multiple icon sizes, scaling etc, and re-implementing that seemed like a bad idea.

However, I do think we still need this protocol to satisfy a bunch of special applications and edge cases:

  • Multi-window apps, especially scientific apps, love to give windows separate icons so they are easily distinguishable from the main application window in a taskbar or window overview grid. I noticed that while working on !264 / !247 (closed). Unlike these MRs, which are essential to support these apps at all, the window icon thing is just cosmetic in nature, but it's one of these papercuts which would be nice to resolve to improve the overall experience using the apps.
  • Non multi-window apps (at least not strictly) sometimes have multiple processes and could benefit from being able to set icons, apparently LibrePCB is one such case:
    grafik
  • There are some apps which can not have a desktop-entry file installed, like Python scripts or Matplotlib windows in virtualenvs. Currently, most of this stuff runs in Xwayland, but just recently I had a bunch of yellow "W"s for many windows created by a scientific tool running in a venv. It would be nice if that usecase was better supported.
  • Some edge cases like AppImage bundles could benefit from this as well, and so might Wine in some cases (not every executable launched by Wine will have a desktop-entry file).

Implementation

I do not expect this protocol to be generally useful for all types of compositors, and it is also "just" a visual inconvenience and not a major functional issue for some apps, like the multi-window-placement issue is. Therefore, I preemptively put this into the ext-* namespace.

NOTE After some discussion, the initial protocol has been greatly simplified, and since especially the "primary window" requirement and icon change mitigation was removed (in discussions this mostly caused confusion and nobody could find a usecase where it was relevant). So the current protocol is rather straight forward:

  • All client windows get the app icon by default, if nothing else was specified
  • A client may call update_icon with a stock icon name from an XDG icon-theme location on the toplevel it wants to set the icon on (the icon-name is mandatory, but may be null)
  • If the icon name was null, or the compositor could not find any suitable icon in the current theme, it may decide to send toplevel_icon events to the client, requesting wl_surfaces with pixel icon data in various sizes required by the compositor and/or other desktop components that want an icon
  • The client replies to the events which it can render icons for with set_icon requests and the requested data
  • After sending the icons (or none, if the client/toolkit can not render them), the wl_surface.commit is called on the toplevel, signalling the changes should be applied.

This time, I did not preemptively reach out to other DEs, so this MR is intended to gauge the interest in having such a feature, as well as for figuring out how, if it happens, a Wayland implementation would look like. I think it's a minor issue in Wayland, all things considered, but it is often the minor things that make or break the experience for some users, in this case especially for ones with lots of Python venvs, Zenity users, LibreCAD users or AppImage users.

Cheers, Matthias

Requirements for merging

Edited by Matthias Klumpp

Merge request reports