Update StatusNotifierItem/systemtray spec

Neal Gompa is handling outreach to KDE ~~and Ubuntu~~ edit: and Allan is handling outreach to Ubuntu.

I will contact the ayatana indicators developers and point them to this issue so we can figure out whether they would be happy with a replacement spec.

I was originally planning to contact the xapp developers too, but looking at this issue, their goals for indicators conflict with ours quite fundamentally, and there is no way to reconcile that, so I think we should leave them be. They want client-side rendering of menus, which is for sure out of scope for us.

changed the description

This is very interesting. I have recently looked at the indicator-application package, which is pretty outdated and not much maintained anymore and I was trying to understand how its working. I wrote a blog post about Ubuntu's its architecture and covered some background on the StatusNotifierItem specification. Maybe its interesting in this context: https://medium.com/@lanoxx/status-notifiers-for-applications-52692d107db1

As @mcatanzaro confirmed, I'm looking into an interested party on the KDE side.

with major breaking changes

In particular, we should address the practical problems with existing indicator specs documented at https://blog.tingping.se/2019/09/07/how-to-design-a-modern-status-icon.html

It seems, the only problem is the name ownership, but this could be easily solved with a minor change: just don't own a name at all from the application/toolkit side. In fact, this is already done by most SNI implementations (KSNI, QDBusTrayIcon, libappindicator).

You are correct that is the only breaking change required.

However it is not safe to just allow talk access to org.kde.StatusNotifierWatcher from a sandbox. It allows arbitrary untrusted data, referencing arbitrary file paths, etc.

So at the very least this needs to be moved into xdg-desktop-portal where it can handle permissions, validate icon data, etc. So org.kde.StatusNotifierHost can in theory be unchanged but org.kde.StatusNotifierWatcher needs to be rewritten anyway.

Once we are at that point of rewrites... why not just fix the rest of the spec? It has a lot of features that don't make much sense, are clearly tied to X11, and could just be cleaned up.

You are correct that is the only breaking change required.

Well, this change is not a breaking one since nothing really checks whether application owns a name or not, changing the watcher name would be a way more breaking actually.

Once we are at that point of rewrites... why not just fix the rest of the spec? It has a lot of features that don't make much sense, are clearly tied to X11, and could just be cleaned up.

I'm not a fan of the Wayland's too secure approach, so that sounds to me more like breaking the spec and removing useful features rather than fixing it.

changing the watcher name would be a way more breaking actually.

Yes that is what I mean. It is necessary.

so StatusNotifierWatcher would become a org.freedesktop.portal.StatusNotifier service or something like that, right?

There's a lot of fat trimming from SNI, some of which is fine, some will be limiting.

I would suggest we start to follow: http://0pointer.de/blog/projects/versioning-dbus.html for anything new.

Icons

The portal only accepts serialized GThemedIcon and GBytesIcons.

We're going to need the wire format specified if it's to be a spec.

Ordering

We definitely want something that matches the following:

org.freedesktop.StatusNotifierItem.Category
org.freedesktop.StatusNotifierItem.Id

They are primarily used for sorting and saving user overrides. We have some a sort function that uses category first then Id. We want it presented logically to users but most importantly consistent between application/shell restarts.

You will almost certainly want to solve that same problem from Gnome too.

From a portal API POV Id could be inferred automatically from the applicationId rather than explicitly specified?

Status

org.freedesktop.StatusNotifierItem.Status

We (Plasma) do use this. It's nicer to do an animation client side that have the source constantly update an icon!

Title / Tooltip text

The supported markup needs specifying.

Activate

This isn't a regression from the current spec, but can we an argument for the activation token: See platform-data here: https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus

It also helps us to neaten X11 too.

Activate: Called when the icon received a primary (left) or middle click.

Why merge secondary activate? It's arguably niche but in KDE we have 6 apps using it. https://lxr.kde.org/ident?v=kf5-qt5&_i=secondaryActivateRequested&_remember=1

It can just be an arg to Activate that client can ignore. It's far easier to have metadata and not have to use it than the other way round.

Menus

    <!-- Menu: Exported org.gtk.Menus object
  
         See https://wiki.gnome.org/Projects/GLib/GApplication/DBusAPI#org.gtk.Menus
         TODO: This needs to have a good Qt story.
               Something exists here: https://github.com/KDE/plasma-workspace/tree/master/gmenu-dbusmenu-proxy
      -->

The menu will be by far the biggest blocker on all this.

The GTK menu has the text: These interfaces are currently considered private implementation details of GApplication and subject to change That doesn't work when we have things on potentially different versions in flatpak.

That proxy only helps solve half the problem. It won't help Qt apps on gnome. Pragmatically we either need:

The GTK menu standardised and Qt clients to support that
This object path in the spec to be agnostic to what's at the other end and gnome-shell to gain an equivalent proxy to support both.

We'd probably also want org.gtk.Actions, for menu item state and activation, which would also be nice re org.freedesktop.Application.ActivateAction where we have an undocument parameter which in practice (in GNOME) is the same as that in org.gtk.Actions.Activate (since GIO doesn't differentiate between "desktop actions" and "application actions")

Not just probably, we either need the actions interface (with a public, stable api), something like it, or add equivalent functionality to the menu interface because the org.gtk.Menu interface doesn't have any way to notify the server that a menu item was selected.

Copying my comment from the Fedora issue over here:

Things that are missing from Patricks draft:

An intro: There needs to be some text that explains what this spec is about, the scope and relevant parties. The initial comment is a good start.

UX and behavior guidelines:

What can users of the API expect from compositors implementing it? Does the icon have to be permanently visible on screen, or is it fine for the compositor to e,g, hide it away in some drawer?
How should menus be exposed ? Does it have to be right click on the icon?
What are the expectations for the client ? Is it ok to ignore the activate call, or should the app provide some clearly visible user feedback?
How is this icon overlaying supposed to work ? Are the icons the same size ? What if they aren't?

Lacking these is a big part of why the original spec isn't adequate.

Information about required and optional parts, and acceptable use of the api:

What happens if I leave the icon-name property empty?
Is it ok to change the icon-name after registering?
Can I add or remove menu items or submenus?
What does HIDDEN vs VISIBLE indicate, exactly? If the statusicons are packed into a drawer or submenu, does that count as HIDDEN until the drawer is opened?

Consistency with other specs, and internally:

For notifications, icons are generally sent as image data. Should that be done here too?
We already have dbus interfaces for activating actions - why does this spec need to add another?
What is the point of the unique ID? Why is the path not sufficient?
The Scroll handling seems inadequate. Scroll events come in different flavors. The may be discrete, or they may have x/y deltas

What are the expectations for the client ? Is it ok to ignore the activate call, or should the app provide some clearly visible user feedback? How is this icon overlaying supposed to work ? Are the icons the same size ? What if they aren't? Lacking these is a big part of why the original spec isn't adequate.

I'm not sure about it, I can see different desktops wanting to represent them in radically different ways, agreeing an api is hard enough, tough some requirements may be necessary, i agree... have to be careful to not pin it down too much to a particular representation tough

The menu will be by far the biggest blocker on all this.

The GTK menu has the text: These interfaces are currently considered private implementation details of > GApplication and subject to change That doesn't work when we have things on potentially different versions in flatpak.

Fwiw, that menu spec is overcomplicated for what we need here. It was designed to export menubars with submenus and sections, etc.

For status icon menus, a much simpler approach would be sufficient: just a flat list of names and actions (plus extra data that is needed to activate the action).

That would have the extra benefit of preventing abuse of status icons as main ui entry point.

A lot of cross-platform applications have tray icon as main ui entry point. Currently these apps work fine everywhere except of GNOME, having that standardized may kick them off from Linux at all (or prevent adoption of the standard by various DEs/programs).

Fwiw, that menu spec is overcomplicated for what we need here.

Qt's public facing API that works on Windows, OS X, Linux (xembed), Linux (SNI) support nested menus. Having it simplified in a sense makes our life much harder because we can't do a silent migration to this spec without potential client side breakages.

It wouldn't be potential, it would absolutely cause breakages. Is there a compelling reason to drop nested menus to make that breakage worth it?

I think it's worth bikeshedding about how exactly the menus should work in order to get as clean a spec as possible, but we can be flexible here. Cleaning up menus is a "nice to have" item, not essential. It's just not worth arguing about whether or not to support nested menus if apps are actually using them and if Qt wants to support them.

We don't need to support menu bar style menus, though, as there is no way for those to be useful in the context of a status indicator. I haven't looked into libdbusmenu myself, but I've heard enough negative opinions to suspect that it is overkill for this job.

IIRC, menubar menus are a separate standard (which Plasma uses for implementing the global menu feature), so I would think that's out of scope here?

Yes, menubars are out of scope

Fwiw, that menu spec is overcomplicated for what we need here. It was designed to export menubars with submenus and sections, etc.

However even AppIndicators may need sub-menus (many apps do it) and different kind of menus (checks, radios...), so having to re-create an API just for all the cases could cause the work needed for this API to explode a bit, so would it be too bad to just accept the more complexity of GMenuModel for this?

It's just not worth arguing about whether or not to support nested menus if apps are actually using them and if Qt wants to support them.

I will add an addendum to this. I think it would be useful to ensure apps understand that if they send a nested menu, it may or may not actually be displayed as nested. For example, if we give each app a status icon in the top bar of GNOME Shell (most likely), there's no problem with displaying nested menus. But if we instead show their app icon in the dash, then the menus would probably be displayed flattened. This would give desktops some flexibility to experiment with the UI.

if we give each app a status icon in the top bar of GNOME Shell (most likely)

After discussing the topic with the GNOME design team: Not the most likely, no ;-)

Fwiw, that menu spec is overcomplicated for what we need here. It was designed to export menubars with submenus and sections, etc.

That would have the extra benefit of preventing abuse of status icons as main ui entry point.

I know nm-applet uses a submenu for VPN connections (and perhaps other things that aren't shown on my system). I don't know what else uses that, and perhaps that's the sort of thing you're classifying as "abuse".

But in general the menu interface is definitely quite complicated when it's usually used for just a flat menu with a few items.

perhaps that's the sort of thing you're classifying as "abuse".

I'm should apologize for a poor choice of words here. Let me try again.

I believe the spec should to have clear wording as to the UX that it is meant to support.

My idea of that UX is: a single icon that can change over time to indicate application status, together with primary action that is triggered by activating the icon and a list of secondary actions that can will typically be presented as a menu that can be triggered from the icon. In almost all cases it should be a short, flat menu.

Do people generally agree with that as the scope for this spec?

My idea of that UX is: a single icon that can change over time to indicate application status, together with primary action that is triggered by activating the icon and a list of secondary actions that can will typically be presented as a menu that can be triggered from the icon. In almost all cases it should be a short, flat menu.

I agree with it as a design guideline/recommendation, however, with respect to existing applications, I'm not sure we should enforce the flatness in the menu in the protocol

nm-applet uses a submenu to list available wifi networks. Having those in a flat menu would clutter the interface and possibly make the menu too large, but being able to connect to a network from the context menu is also very convenient.

Tray indicators are bad UX. There shouldn’t be a new spec for them, instead apps should be encouraged to drop them, and the ones that continue to use them are not enough justification to create a new spec; what icons are there, mostly in a few proprietary apps, aren’t so essential that a new spec must be created to support them.

Outside of GNOME, tray icons considered a good UX, why can't those environments have an XDG-standardized spec?

Outside of GNOME, tray icons considered a good UX

Can you provide evidence of that? Every environment with tray icons got them from Windows 95 (which invented them). They were added so applications could put icons there temporarily to notify the user about an event or a new thing (and later also became used for operations in progress, for example print jobs). That’s why the part of the taskbar where they were shown in Windows 95 became called the “notification area” (GNOME 2 also called it that, for the same reasons). They weren’t meant for minimized windows or services running in the background. Their purpose as a notification area was defeated by the use for other purposes. It caused the notification area to become excessively cluttered. When you have more than a few icons in the notification area, you will not notice the notifications anymore. Defeating the point.

Quoth Raymond Chen in 2003:

A little while later, we added notification icons to the taskbar.

I think the reason people started calling it the “system tray” is that on Win95 there was a program called “systray.exe” that displayed some icons in the notification area: volume control, PCMCIA (as it was then called) status, battery meter. If you killed systray.exe, you lost those notification icons. So people thought, “Ah, systray must be the component that manages those icons, and I bet its name is ‘system tray’.” Thus began the misconception that we have been trying to eradicate for over eight years…

Quoth the Microsoft design guidelines for the notification area:

Is the icon displayed temporarily to show a change of status? If so, a notification area icon may be appropriate

Is the icon primarily to launch a program or access its features or settings quickly? If so, use the Start menu to launch programs instead. The notification area isn't intended for quick program or command access.

Quoth the GNOME Human Interface Guidelines 2.2.3:

The utility of the notification area decreases rapidly when more than about four icons are always present. For this reason, icons that appear only temporarily in response to events are preferable.

Only core GNOME programs may perpetually display an icon in the status area.

Use of the notification area by applications running in the background, by device drivers showing company logos, by application quickstarters (running in the background to launch faster, as OpenOffice did) made the notification area hard to use for its intended purpose.

This happened in all environments that supported tray icons. On KDE you had KGet, Akregator, KsCD, KWallet, KMail, KGPG, Kaffeine, Noatun, many others staying in the tray when closed, making it hard to use for notifications as well as for accessing the apps.

Environments that support a notification area also support better system integration features (notifications, media controls with MPRIS, the Background portal). Tray icons are not well suited for these purposes, they have been misused everywhere they have been supported, and they are small and hard to interact with. Hence they are not good UX. Because this isn’t something that will change, they must go.

There are a few applications that still use tray icons, but this is often not useful and it’s not that essential to support them. Desktops (tray icons are pretty much a desktop-only thing) can continue supporting them if they want but a new spec for tray icons is a huge amount of complexity and work, might fail, risks encouraging continued use of tray icons where they otherwise would be replaced by better alternatives, and is not worth it. So it shouldn’t be done.

I think having a standard to perform something in a proper way, doesn't say that people should use it as the only way to design an application. Given that people is already using them a lot. So we should at least try to ensure that this is happening in a proper way.

Indicators are part of most desktops, and there's no reason not to have a standard for. In order to give guidance and try to put some order.

It's also relevant for me to underline in the standard, that icons MAY or MAY NOT be shown by the current implementation, so depending on that they should react.

I don't think what notification area was invented for is relevant after 20 years. The fact is it got wide adoption, a lot of applications (that is, a lot, you saying "a few", but that's false, a lot of applications implementing tray icon in reality) are using it and no DE except of GNOME/Pantheon removed tray support nor discouraged from using it. That's the evidence.

Environments that support a notification area also support better system integration features (notifications, media controls with MPRIS, the Background portal).

There are applications whose the main function to be an indicator of something, that might be an indicator of synchronization process (like e.g. Dropbox) or that might be a custom vendor-made application for a modem wiling to provide an icon with signal strength. There's just no other cross-DE way to implement that.

but a new spec for tray icons is a huge amount of complexity and work

Well, I guess no one forces you to do that work, so the others who want can do the work

might fail

This is an argument against anything new

risks encouraging continued use of tray icons where they otherwise would be replaced by better alternatives

In my opinion encouraging continued use of tray icons is good. The alternatives aren't always better.

and is not worth it.

Let do the work for those who think it worth the effort ¯_(ツ)_/¯

From the draft:

Status was removed. Either the application wants a status icon or it removes it.

In my opinion, that's a nice feature. It allows the application to suggest whether the application has something to say (e.g. there's a non-null counter of new messages) or it can go to a drop-down list with other icons not requiring attention.

Category has been removed. In practice these were not used in a meaningful way?

From my experience, this is heavy used by DEs to sort built-in indicators (network, volume, etc) exported as tray icons: Plasma, MATE (maybe Deepin?). So at least 3/4 (except of Communications) categories have sense.

First of all, I'm very happy to see this coming...

Would be the case to have this in a (WIP?) MR to be able to comment on it?

Probably the new API is even too much inspired on previous one, we could maybe even try to clean it up even further, but I also see the point of try to preserve what's possible.

From a quick read on the spec there are few things I'd like to underline:

StatusIcon.Activation needs context information
- Main relevant bit that the apps should receive is the timestamp, but I feel would be better to go wild and support a a{sv} parameter for activation so that the application can receive the relevant environment data, ensuring in the standard what elements to include (such as desktop, workspace and simiar bits).
We should try to find to define something alternative to the IconThemePath, to make apps to provide a pool of icons at startup:
- While this can be avoided by just passing the whole GIcon from dbus when needed, various appindicators used to change icons very often and IMHO trying to avoid all this frequent icons encoding/decoding (that can be very slow) should be avoided.
Provide a property that the application should use to know whether the icon is visible or not; in fact an icon may be hidden by the desktop because of various reasons:
- The shell is currently hiding all the icons (as in lockscreen)
- The application is disallowed both by portal or by system settings
- The appicon is currently running and handled by the shell but hidden (we may provide a way to hide less-used icons in a drop-down menu)
While something could be handled by unregistering the app from the shell side, I think it's better to expose the two different cases explicitly.
StatusIconService.RegisterStatusIcon must require an application id
- So that can be used to block an app to show icons for example. We should disallow anything that is not related to an app-id, and probably we should figure out a way to ensure that the requesting proc is part of that app.
Removal of SecondaryActivation isn't something I like too much:
- It was used to perform actions on middle-click, what was relevant (at least in appindicators implementation) was that all the "hidden" actions had a related menu item, so we could instead ensure in the API that is mapped to a menu-item-id (thus to become a property).
Attention mode could have a reason to be there, indeed could be replicated otherwise.
StatusIconService.IconPreferences: While this could be relevant to send stuff like whether a dark theme is used or not, IMHO, we should disallow anything that isn't a symbolic icon.
StatusIcon.ToolTip: I'd be for dropping tooltips here. In case they can be replaced with status menu icons (like the first element of the menu may show relevant information)
StatusIcon.Title: Do we need anything else than the app name?
- While we should provide a11y infos.
StatusIcon.ItemIsMenu: IMHO we should just assume that all the icons must have a menu. Mixing indicators without entries and with entries would just lead to a bad and inconsistent experience.
a11y information providing details that can be alternative to the status icon

Here's just few comments I had, but I may come up with further ideas once I'll be fully back on the appindicators g-s extension. ;-)

IMHO, we should disallow anything that isn't a symbolic icon

Wow, that would create troubles for a lot of applications that generate the icon on demand (to add a counter or something else). Currently they can just draw, but with such a change they would need to find a library that can modify SVGs. Not to say about applications that lost their designer a lot of time ago and don't have an SVG icon.

Well, we're providing a new standard after all... They can just provide better icons. Or be prepared that the desktop may display them wrongly.

I personally would prefer that desktops/users can declare their preference for full color or symbolic (monochrome) icons. GNOME, Plasma, and macOS use symbolic/monochrome styles now; while Cinnamon, LXQt, Xfce, MATE, and Windows use full color ones.

Rendering emblems is a fairly common thing in apps (see Dropbox and VPN clients as examples), and I think it makes sense to capture that in the spec.

Well, we're providing a new standard after all... They can just provide better icons.

Well, what's the point for them to consume the new standard if the reason of why they're displaying a tray were these overlays and now they can't add overlays? Or if they can't provide better icons at all...

Or be prepared that the desktop may display them wrongly.

you meant only SVGs or rasterized monochrome icons, too?

Yeah, I'm quite sure upstream GNOME shell wouldn't ever show indicators with full color icons, so if the icon isn't respecting that, it should be probably rasterized.

I mean do you propose the icons to be only SVG or raster monochrome icons are ok, too?

About icons every possible approach may work up to a point..

using just the icon theme name ensures that the shell will use the proper theme, (and at that point being symbolic or not can even be a theme decision) tough, that name should be known by both the app and the workspace theme, which may not always be the case and the app could really need to have some quite custom icon
using the serialized icon graphic then makes it possible for the app to send whatever it wants, but that's the con as well as it may look completely out of place

I'm not sure there is a better solution than supporting both with the preference for the themed name.. (perhaps with the seralized pixmap always there as a fallback in case the shell doesn't know that icon name)

Could be a possible sending an svg (in some particular format so if is symbolic is easy to recolor via stylesheet) may look not great as even symbolic icons may have radically different syles and svgs aren't "that" scalable as at small size to have something that really looks good needs lines to be well aligned to the pixel grid, so may need multiple size dependent files even in the case of svg

I don't think themed names make sense. Themed icons have a habit of changing or disappearing, and they're different on different platforms. It really only makes sense if the app installs its own themed icons, but then that fails hard for containerized applications where the icon is not installed on the host system at all. So I would force apps to always serialize their icons.

And the spec should warn that the desktop might modify the icon if it is not monochrome. E.g. if you try to display a counter in a blue circle, it will probably look pretty bad when rendered in monochrome.

If the serialized icon is a pixmap and is just converted to monochrome (on whatever colorscheme used by the shell) i see it kinda limiting, i kinda feel symbolic icons may be too much of a design trend rather than something here to stay indefinitely (I don't know if they are but not something one should do an assumption over) so much that we see some desktops that are expressing preference for colorful icons..

If the serialized data is an svg then one could do css tricks for shapes that mark themselves explicitly "i want to be the foreground color", tough when an app decides to send a colorful svg then colorful it is even if the shell doesn't like it. Another advantage tough the svg could have named colors for things like warning, hightlight and so on (so an error icon can have a red piece, but a theme-defined red)

Both Plasma and Gnome have mechanisms for that, unfortunately is a slightly different way, there were talks about standardising it but didn't really go anywhere

Having a dedicated badge/overlay feature would be useful, imho most of the time the reason for an app providing its custom pixmap is to add some sort of overlay (e.g. presence indicator or unread count in chat or mail app).

Sending pixmaps over has its own fair share of problems with e.g. high-dpi, the client doesn't know what size or representation the host expects. We need something better than just sending a single pixmap. (I guess that's what the IconPreferences this is for :)

Yeah, I do agree with you @kbroulik, however, I'm not sure if we're going out of scope. I'd say no, but others should agree.

All it depends if we leave the freedom to the UI to implement such API by just reusing docks to present the app "indicator" menu just as a dynamic menu, and in such case having an "Emblem" API would be good.

In fact exposing a Counter (for example) emblem could be used both if indicators are shown in the "classic way" or if the shell's dock icon will integrate them.

I'm not sure if we're going out of scope. I'd say no, but others should agree.

I don't have an opinion on that.

But if there's an emblem API, then it either has to be mandatory, or we need a mechanism that exposes support to apps.

The "throw stuff at the wall and hope something sticks" approach is one of the fundamental flaws in status notifiers.

Whilst some sort of emblem extension to o.f.A is probably overdue, I'm not entirely sure it isn't tangential to the current status-icon idea.

So far as I can tell push behind doing this is to work around the various (often proprietary) apps that assume a Windows-style notification area exists, and thus end up semi-broken on GNOME, along the incompatibilities of the approaches used in KDE et al with the modern world.

Thus it seems to me, as much as we may want various design styles, that our primary target here is essentially electron's tray API - and Qt's equivalent - so such apps Just Work™ when on updated toolkits. As much as it would be nice to have a minimal "dynamic actions" or such, I doubt we'll ever get the relevant developers to support an entirely different system on top of a system common to macOS and Windows — if nothing else they haven't so far — so doesn't really solve the problem that brought us here.

So, either:

We accept that we need buttons with potentially complex menus, which is potentially something more-KDE people want anyway
We give up on "tray icons" and accept the status quo regarding that class of app

Whichever we go for, it would good to consider a separate "o.f.A2" extension with things like "busy" and "count" properties, and potentially dynamic actions, for decorating entries.

As a final thought we seem to be getting further caught up in this whole "running-in-the-background" thing. Similarly I wonder if that's really directly related to tray icons. It seems to me tray icons are there to provide quick interaction with an app — which feels at odds with the draft shell designs featuring a semi-hidden second dock of static app icons. Yet I'll agree that would be a neat way to show apps running in the background.

along the incompatibilities of the approaches used in KDE et al with the modern world

What are you referring to with 'modern world'?

Essentially see: How to design a status icon library in 2019

But tl;dr:

Don't work on Wayland (i.e. dependant on X11)
Don't work sandboxed/contained/etc (i.e. want globally unique PIDs, or use unfortunate talk names)

It's perhaps unfair that I mentioned KDE specifically, since theirs is fairly elegant and agnostic, but org.kde.StatusNotifierItem-PID-ID is a tad problematic

Modern SNI implementations don't own a dbus name actually, you can try any Qt application from flatpak that uses the KDE 5.15 platform and has the permission to talk with the watcher, it should work. appindicator doesn't own, too, though.

Modern SNI implementations don't own a dbus name actually

I'd like to avoid further tangenting here, but I assume KNotifications is ‘modern’ and it still does and given items are to be registered with the "watcher" by bus name I'm rather unclear how that's supposed to work with a name that only exists inside the sandbox.

See, this variable is used only as an internal connection identifier with Qt API
https://invent.kde.org/frameworks/knotifications/-/blob/master/src/kstatusnotifieritemdbus_p.cpp#L135-137
https://doc.qt.io/QT-5/qdbusconnection.html#QDBusConnection
https://doc.qt.io/QT-5/qdbusconnection.html#connectToBus-1

Let me try and help you two stop talking past each other:

The spec says you have to have a specially named service and the client library follows that. As you say it's very silly.

However - the watcher/host side supports another workflow which ilya is referring to

RegisterStatusNotifierItem on our side supports two methods of working. Passing a service name (as per spec) or passing a path (the service can be inferred from the caller). We can split based on whether it starts with a '/'

https://invent.kde.org/plasma/plasma-workspace/-/blob/master/statusnotifierwatcher/statusnotifierwatcher.cpp#L42

Some clients (including QSystemTrayIcon with the relevant plugin) will use this.

The spec says you have to have a specially named service and the client library follows that.

https://invent.kde.org/frameworks/knotifications/-/commit/2b0b904ee0e986ea0a96a8f54e1522e492885ffe

Then I guess I misunderstood :/ Also multiple DBus connections is somewhat horrific. Definitely a sign that we need to update this spec.

I was about to say about SecondaryActivate, but @3v1n0 was faster. I was searching for an issue with usecase that uses not just middle click, but various combinations with mouse buttons and keyboard modifiers. It's here: https://github.com/AyatanaIndicators/libayatana-appindicator/issues/4. So maybe it's a good idea to expose pressed modifiers when clicking on the icon, too.

So maybe it's a good idea to expose pressed modifiers when clicking on the icon, too.

I really dislike this, I think it would be an accessibility and discoverability nightmare.

From my experience, this is heavy used by DEs to sort built-in indicators (network, volume, etc) exported as tray icons: Plasma, MATE (maybe Deepin?). So at least 3/4 (except of Communications) categories have sense.

This is a thing we should discuss wrt to the scope of the spec, imo.

I think this should be a spec for app indicators, not a spec for desktop plumbing (what you call built-in indicators).

The thing is some DEs use tray for everything. The built-in indicators are just applications implementing SNI or XEmbed. Third-party applications implementing some hardware monitoring would also benefit from categories (they could be sorted along with system hardware indicators if any)

The thing is some DEs use tray for everything.

It all comes back to outlining the UX we expect to support with this spec. I can't envision a useful spec that supports an 'everything is a tray icon' approach, while also being useful for normal desktops.

That being said, a category hint is easily ignored and doesn't do much harm (in terms of complicating the spec).

Yeah, I don't think would be a big problem having it... Can be just considered an hint.

However, if instead we consider the application-ID, imho, we could just rely on that and on its category.

While this can be avoided by just passing the whole GIcon from dbus when needed, various appindicators used to change icons very often and IMHO trying to avoid all this frequent icons encoding/decoding (that can be very slow) should be avoided.

I don't think that is serious performance concern worth the hassle of figuring out how to communicate file paths for icons across sandbox boundaries.

Well, in the current implementation (at least in GNOME shell, where JS may create a limit for that), this may lead to frame drops, higher CPU usage and so on.

So, while the implementation can be improved, IMHO we should try to avoid such issues.

As per this, I agree that communicating file paths could be annoying, I'd be just happy with a UpdateIconSet(av) where you can pass an array of GIcon's and the shell will then pick the cached one by ID instead of having to pass the icons all the time.

File paths do not work for sandboxed apps.

Indeed, that's why I'm saying that we should allow an app to send to the shell the whole icon set (with limits) that is going to use, referenced by an ID, and then just send leave the app to send an ID of the icon to be presented.

I.e.:

UpdateIconsSet({1: .GBytesIcon foo-bar, 2: .GdkPixbuf bar}, 3: .GThemedIcon bazz)}) The shell will cache the icons (so we need to set constraints)

Then the app will be able to just change it without having to pass all the times the same stuff. Can be an optional API, but convenient to avoid filling the bus of stuff that it's not really needed, and avoiding to serialize/deserialize the very same icons multiple times.

Oh, OK, sure.

Another possibility is that the desktop might display the menu, but not the icon. E.g. the desktop might want to display the app's usual app icon instead of the icon that it provides with its menu.

Indeed, could also be used just as a remote menu in quicklist, however I'd say that we should in such case allow some kind of "embleming" (as the count numbers)...

Not sure that would take things outside of the initial goal here, though.

Could you allow sending a handle like xdg-desktop-portal uses for OpenFile already?

https://flatpak.github.io/xdg-desktop-portal/#gdbus-method-org-freedesktop-portal-OpenURI.OpenFile

Just questions about apps changing their status icons:

Is this the app changing its menu and/or just its icon to indicate a specific status?
If the purpose is just to indicate a specific status, what does that mean for a UI that doesn't want to change the icon?
If it is both, can a status change and associated menu (actions) be displayed as a notification?

Hey, thanks for getting the ball rolling.

Overall I'm pretty happy with the draft; in particular it addresses all the ancient criticisms of status notifiers as far as I can see.

I do have a couple of suggestions, but none that I'd consider blocking. The overall gist is that I'd prefer to draw from the existing org.freedesktop.Application interface as much as possible instead of replicating parts of it in the new interface. Also on the GNOME side, a strong association with a valid app ID would be good, because it'd give us the option to tie in better with existing components.

<!--
    IconPreferences: This property is gathered from the host to express
    preferences for sent icons.
    It contains:
    - integer: Preferred size of icons in pixels assuming equal height and width, e.g. 24
    - integer: DPI scale e.g. 2
    - bool: If symbolic icons are preferred
    The expected size of icons are typically 24px, 32px, or 48px.
-->
<property name="IconPreferences" type="iib" access="read"/>

I'd make this a{sv} and document the current options (size, dpi-scale, style). I cannot think of other entries right now, but if something pops up eventually, then it's easier to extend a vararg than a fixed tuple.

<!--
    StatusIconRegistrationChanged:
    @app_id: App id of the application
    @path: the path of the exported status icon
    @registered: The current state of the status icon on the host
    Send to the application when the status icon becomes registered
    with the host or when registration is lost/removed.
    This is the point where applications can make assumptions that this
    status icon is visible and should be used.
-->
<signal name="StatusIconRegistrationChanged">
  <arg type="s" name="app_id"/>
  <arg type="o" name="path"/>
  <arg type="b" name="registered"/>
</signal>

I don't see the purpose of the "app_id" parameter. I would expect the signal to be emitted exclusively to the icon owner, not broadcasted to all listeners. Unless the intention is to allow a single service to implement icons of multiple applications, which doesn't sound very compelling to me.

That said, an application ID that links the icon to a .desktop file would be extremely welcome, it's just that I'd expect that as parameter to RegisterStatusIcon(). I guess it's currently not there because a portal can figure out the correct ID of sandboxed apps; still, it would be very helpful to have it for non-sandboxed apps as well.

<!--
    ActionInvoked:
    @app_id: App id of the application
    @id: the application-provided ID for the status icon
    @action: the name of the action
    @parameter: array which will contain the target parameter
      for the action, if one was specified
    Send to the application when a non-exported action is
    activated.
-->
<signal name="ActionInvoked">
  <arg type="s" name="app_id"/>
  <arg type="s" name="id"/>
  <arg type="s" name="action"/>
  <arg type="av" name="parameter"/>
</signal>

I assume "non-exported action" means an action that is not provided through the org.freedesktop.Application interface? Would it be possible to scrap that support and mandate that applications must implement both interfaces?

<!--
    Activate: Called when the icon received a primary (left) or middle click.
-->
<method name="Activate"/>

Likewise, I'd prefer to mandate org.freedesktop.Application instead of a similar-but-different method. Applications can optionally provide a DefaultAction string property to use org.freedesktop.Application.ActivateAction (with an optional parameter of DefaultActionTarget), otherwise org.freedesktop.Application.Activate is called.

<!--
    Scroll: Called on mouse scroll while over the icon.

    Delta will be `-1` when a scroll down event happens
    and `+1` for a scroll up event.
-->
<method name="Scroll">
    <arg name="delta" type="i" direction="in"/>
</method>

Is this used by anything but sound volume indicators (which IMHO should be out of scope for an application portal)?

<!-- Item has a valid Menu property -->
<property name="ItemIsMenu" type="b" access="read"/>

Is this really useful? Isn't setting Menu to a non-empty string good enough?

<!--
    org.freedesktop.StatusIcon:
    @short_description: Interface for application exposed status icons
 -->
<interface name="org.freedesktop.StatusIcon">
  <!-- Descriptive title for the application, this MAY be shown by the host -->
  <property name="Title" type="s" access="read"/>
  <!-- Tooltip text to show on hover, this MAY be shown by the host -->
  <property name="ToolTip" type="s" access="read"/>

A more radical approach would be to define a single vardict property and document the supported entries plus their fallbacks if not specified:

title: the Name field from the .desktop file
tooltip: the Comment field from the .desktop file
icon: the Icon field from the .desktop file

If we want to make the menu mandatory, then it would remain a separate property, otherwise it can go into the vardict as well.

Yeah, as already said I strongly agree we should couple more the indicators with the app-id. This was a big issue with previous implementation and we've to fill that gap.

I'm very much in favour of building off o.f.A and desktop entries as much as possible rather than having more disjointed ways to do the same thing.

However I'm not sure ActivateAction alone is viable for handling menu items since GMenuModels (as we are suggesting for the menu) are somewhat tied to GActionGroup for visibility, sensitivity and radio/tick items.

So I think either we need to rethink how to represent menus (which would be a shame, especially when in the gtk world we've finally moved to it as the way to represent menus) or standardise at least some of org.gtk.Actions.

I guess it's currently not there because a portal can figure out the correct ID of sandboxed apps

Yes the app-id is known by the portal rather than reported by the app.

I'm not actually sure how this worked unsandboxed so we should probably make it explicit, the portal can yell at lying apps if needed.

I would suggest we start to follow: http://0pointer.de/blog/projects/versioning-dbus.html for anything new.

This seems like a good idea.

So the interface names would change to org.freedesktop.StatusIcon1 and org.freedesktop.portal.StatusIconService1.

Is node name="/" the root object path? I suppose we could call that /org/freedesktop/StatusIcon1, though that might be too confusing.

So the interface names would change to org.freedesktop.StatusIcon1 and org.freedesktop.portal.StatusIconService1.

That's right.

Is node name="/" the root object path?

It's not, that's just xml noise.

Paths are currently not mentioned in the interface definition anywhere here. Which is a good point. We don't need to specify a path for the StatusIcon1 as clients specify it themselves when they register, but we'll need to say what the service name and path for the StatusIconService1 live at.

Currently xdg-desktop-portal does not version interfaces like this and instead has a version property on interfaces. The benefit to this is a promise of long term API stability which can mostly be additive. This is very important to the goal of flatpak being a stable target.

Update StatusNotifierItem/systemtray spec

Designs

Child items ...

Activity

Icons

Ordering

Status

Title / Tooltip text

Activate

Activate: Called when the icon received a primary (left) or middle click.

Menus

Admin message

Admin message

Update StatusNotifierItem/systemtray spec

Activity

Icons

Ordering

Status

Title / Tooltip text

Activate

Activate: Called when the icon received a primary (left) or middle click.

Menus