comments on StatusNotifier spec

[Aaron J. Seigo]

On January 18, 2010, Dan Winship wrote:
> > StatusNotifierHost
> 
> When I first saw this term in the spec I thought it was talking about
> having a status icon on one machine and a tray on a different machine.

for all that the status item cares, it could be.

> Maybe this is just because I write lots of networking code, but "host"
> to me mostly means "a computer on a network".

ok; i'm not sure that this matters at all, however.

> > Each application can register an arbitrary number of Status Notifier
> > Items by registering on the session bus the service
> > org.freedesktop.StatusNotifierItem-PID-ID, where PID is the process
> > id of the application and ID is an arbitrary numeric unique
> > identifier between different instances registered by the same
> > application.
> 
> This makes it awkward for two unrelated parts of a single process (eg,
> plugins) to each put up their own status icon, since they have to
> somehow coordinate unique IDs between themselves. And I can't see any
> reason why the spec needs to require that the notifier items have
> specific D-Bus names anyway. This should just go away; let people call
> their notifier items whatever they want.

this way we know we won't get naming collisions at runtime, which simplifies 
things a lot and increases the robustness. i don't know what would be gained 
by letting developers name notifier items whatever they want. this is a 
specification for a system running on a computer, not a celebration of human 
uniqueness ;)

> > org.freedesktop.StatusNotifierItem.Id
> > org.freedesktop.StatusNotifierItem.Title
> 
> I assume Title is supposed to be localized and Id is not, which you
> should indicate.

yes, good point; user visible strings in the spec should be marked as such.

> > org.freedesktop.StatusNotifierItem.WindowId
> > 
> > It's the windowing-system dependent identifier for a window
> 
> No, it's an X Window ID. A "windowing-system dependent identifier for a
> window" can't be expressed as a UINT32 on all windowing systems.

true enough; i suppose it's of interest to those who are creating windows 
shell replacements using plasma-desktop (to find a concrete use case). if we 
ignore symbian (where i don't know if such information would be remotely 
interesting anyways), it seems that all of our (qt's and kde's) targets can be 
handled with an unsigned long.

> Also, you need to give *some* indication of what this is for. Eg,
> currently it could mean anything from "Please raise the indicated window
> if the user clicks on the status item" to "Please hide the indicated
> window if the user clicks on the status item".

yes, that's up to the visualization. the point isn't to state what is done 
with the information, just to make that information reliably available.

> > org.freedesktop.StatusNotifierItem.OverlayIconName
> > 
> > This can be used by the visualization to indicate extra state
> > information, for instance as an overlay for the main icon.
> 
> "for instance"? So that's just one example of how OverlayIconName might
> be used?

correct.

> Either it is guaranteed to be overlaid over the main icon, or
> else it isn't. If it isn't, then no one will use this property, and
> they'll just change the main icon instead.

this assumes a "i want to control the visualization" mentality, which is 
broken and harmful. the status item (and it's human creator) should not care 
what the end visualization will be.
 
> Also, is OverlayIconName (as opposed to OverlayIconPixmap) actually
> useful?

yes, it's the name of the icon, not a pixmap.

> It seems like you'd need to also specify *where* on the main
> icon to overlay it.

that's dependent on the visualization more than the item. i can imagine cases 
where it would be nice to specify where to overlay it, but i can imagine more 
cases where this would simply break consistency and assume things about the 
visualization (e.g. size, position and even visibility of the icon)
 
> > org.freedesktop.StatusNotifierItem.AttentionIconName
> > 
> > this can be used by the visualization to indicate that the item is in
> > RequestingAttention state.
> 
> Again, "can"? Either it *is* used when the icon is in
> RequestingAttention state, or else the property is useless and people
> will just change the main icon instead.

i'm afraid that you are missing one of the primary points of this 
specification, which is that the visualization is in control of presentation. 
the visualization may instead play a sound, for instance; showing the 
attention icon in the case of an audio-only system (for sight impaired usage 
or for systems that simply don't have a visual output system) would be a bit 
silly, no?

so the application which the item belongs to presents as much useful 
information about the item itself and the visualization decides how to put it 
together.

this way we can account for multiple real-world use cases as well as future 
proof ourselves.
 
> > org.freedesktop.StatusNotifierItem.AttentionMovieName
> 
> "Movie" is not standard terminology. Why not "AttentionAnimationName"?
> "Movie" suggests that it should point to an MPEG or something.

Animation would probably be better; not sure it's worth changing at this 
point, but if it's considered truly egregious we could (and up the version on 
the spec)
 
> > An item can also specify an animation associated to the
> > RequestingAttention state. This should be either a Freedesktop-
> > compliant icon name or a full path. The visualization can chose
> > between the movie or AttentionIconPixmap (or using neither of those)
> > at its discretion.
> 
> Last I knew the freedesktop icon spec did not allow for animated images
> at all.

from http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-
latest.html :

Version 0.6, 07 December 2005, Rodney Dawes. 
    * Add the "Animations" and "Places" contexts 

> Also, why does this property allow either a name or a path, but
> all of the other ones only allow a path?

true; icon names could take a full path as well. the problem with doing so is 
that we then don't get a full range of sizes (important for varying the size 
of the item in the visualization, obviously :) which we do by requiring a 
themed name. animations are a bit more special in that regard, but we could, i 
suppose, allow full paths for IconName, etc. with warnings that this may 
provide very poor results. personally, i don't think this is necessary as it's 
really just better for the application to install their icons as per the icon 
theme standard so they are available to the visualizations.

> > org.freedesktop.StatusNotifierItem.ToolTip
> 
> Needs to specify whether the icon name overrides the data or vice versa.

that's up to the visualization.

> What should you specify for the name if you're including icon data (and
> vice versa) since the signature requires both to be present?

true; it should note that the icon data can be (and preferably is) empty. it's 
there to catch unresolvable edge cases we came upon, such as IM avatars.
 
> > ContextMenu
> > 
> > the x and y parameters are in screen coordinates and is to be
> > considered an hint to the item about where to show the context menu.
> 
> "a hint"? You need more than that.
> 
> In particular, if the status icon is displayed on the top of the screen,
> then you probably want the menu to appear underneath it, but if the
> status icon is on the bottom of the screen, then you want the menu to
> appear above it. Likewise, normally you probably want the menu to be
> left-aligned with the left edge of the icon, but if the icon is near the
> right edge of the screen, and the menu would extend off the edge, then
> you probably want to right-align the menu with the right edge of the icon.
> 
> So what you need to know is the x,y,width,height of the icon's
> visualization (including any padding introduced by the host). Either
> ContextMenu, Activate, and SecondaryActivate could include all 4 of
> these as parameters, or else they could be available as properties.

there is no guarantee whatsoever that the visualization shows an icon. please 
disabuse yourself of that notion. :) 

otherwise, i agree that it could be useful to have more information, such as 
the preferred direction, though probably not by much. the coordinates provided 
can be assumed to be the preferred "root" location of the menu (e.g. the top 
left) and if it doesn't fit, then make it the bottom left. just as we tend to 
do for any context menu. it's up to the visualization whether to decide to 
send the coordinates of a mouse click that triggers it or the top left of an 
icon bounding rect, etc. i don't think providing the bounding box would be 
very useful, however, as that will simply lead to items doing it differently 
and leading to inconsistency.

so at most perhaps a direction hint, though that would still need to be 
overridden at times by the item due to screen size and so i'm not sure if it 
would really be useful.

(and when we have this coupled with the menu xml spec, this will largely 
become a moot point)

> > Signals
> 
> (Sigh. We need a standard D-Bus property notification interface.)
> Anyway, this could be simplified by having a single "Changed" signal
> with an array-of-string parameter indicating the properties that have
> changed (since you will likely want to change a bunch of them at once).

yes, this is a nice idea for limiting the bus traffic. would require an 
incompatible change to the spec, but it is doable.

> (Also, it is weird that in the current signals NewStatus works
> differently from all the others.)

agreed
 
> > StatusNotifierWatcher
> 
> I'm not convinced this interface is really needed, but someone who knows
> D-Bus better than I do should think about it.

how do you suggest one implements multiple visualizations and ensures that 
visualizations may go away altogether (think: user removes a system tray 
widget, then adds a new one somewhere else) and the items retain a place to 
publish their data?
 
> Eg, right now, the spec says that the client needs to check if there's a
> StatusNotifierWatcher on the bus, and if so, then call
> IsStatusNotifierHostRegistered on it to see if there's a
> StatusNotifierHost, and if there's no StatusNotifierWatcher then just
> assume that there's no StatusNotifierHost either.
> 
> But the client could just as easily check directly if there's a
> StatusNotifierHost present.

since there can be multiple hosts, there is no set name for the host 
interface. they'd have to scan the entire bus to see if there are any 
instances of the interface published anywhere. not particularly efficient.

> > If no StatusNotifierHost are registered and running, all
> > StatusNotifierItem instances should fall back using the Freedesktop
> > System tray specification.
> 
> See below re: backward compatibility.
> 
> > ServiceRegistered
> > ServiceUnregistered
> > StatusNotifierHostRegistered
> 
> The naming inconsistency is weird. "ServiceRegistered" should be
> "StatusNotifierIconRegistered", shouldn't it?

would be more consistent, yes.

> Also, don't we need
> "StatusNotifierHostUnregistered"?

it's a bool, so no.
 
> > StatusNotifierHost
> 
> as with StatusNotifierIcon, there doesn't seem to be any reason for the
> required naming convention

not sure what you mean by this at all.
 
> > Backwards Compatibility
> 
> Assuming both the clients and the tray implement backward-compatibility,
> there is a race condition:
> 
>     - Application starts, but sees that there is no system tray
>       present. (IsStatusNotifierHostRegistered returns FALSE, and
>       there is no _NET_SYSTEM_TRAY_S0 manager selection present.)
> 
>     - The system tray starts
>         - registers itself as a StatusNotifierHost
>         - creates _NET_SYSTEM_TRAY_S0 manager selection
> 
>     - Application sees the ICCCM client message announcing
>       the legacy system tray, so creates an XEMBED-based
>       notification icon
> 
>     - System tray displays the legacy notification icon
> 
>     - StatusNotifierWatcher emits StatusNotifierHostRegistered
> 
>     - Application sees the StatusNotifierHostRegistered, destroys
>       its legacy icon, and creates a StatusNotifierItem
> 
>     - System tray removes the destroyed legacy icon
> 
>     - StatusNotifierWatcher emits ServiceRegistered
> 
>     - "Tray applet" displays the StatusNotifierIcon, possibly in
>       a different spot from the previous legacy icon

i don't see a "race condition" in this at all. i see an unwanted behaviour due 
to poor choice on the part of the host implementation and/or the desktop 
shell, but it's completely avoidable with a bit of common sense implementation 
on the part of whomever is writing the system tray widget in question. as a 
system to get us from where we are now (with xembed being the norm) to where 
we'd like to be (where we have this system in place everywhere), it really 
doesn't need to be watertight in the sense you are looking for it to be, 
either.

> > The tags specified above mark up the content in a way that allows
> > them to be stripped out on some implementations without impacting the
> > actual content.
> 
> Is it expected that implementations that can't display images will
> display the contents of the "alt" tag instead?

that's up to the implementation isn't it? :)

> Is the alt tag required, or just allowed? Can it contain markup itself?
 
good questions; probably preferred though not required and i don't think 
markup should be allowed.

> > Icons
> > 
> > All the icons can be transferred over the bus by a particular
> > serialization of their data, capabe of representing multiple
> > resolutions of the same image or a brief aimation of images of the
> > same size.
> 
> Animations? Do all methods that accept icons accept animations?

no.

> Is it
> assumed that if each element has the same width+height then it's an
> animation, but otherwise it's the same icon in multiple sizes?

no, that's up to the dbus method you are passing the icon data to (e.g. 
whether it defines itself as taking an icon or an animation)

> What if you want to provide an animation in multiple sizes?

this is indeed an unresolved problem, and why you probably want to define 
animations by theme name in the first place rather than pixmap data if at all 
possible.

-- 
Aaron J. Seigo
humru othro a kohnu se
GPG Fingerprint: 8B8B 2209 0C6F 7C47 B1EA  EE75 D6B7 2EB1 A7F1 DB43

KDE core developer sponsored by Qt Development Frameworks