comments on StatusNotifier spec

[Dan Winship]

(So rereading this, it comes across as kinda harsh, but it wasn't
supposed to be, so just add a ":-)" to the end of every line or
something. :-)

> This specification does not define what the aspect of the
> Noticication Items will be, this is strictly implementation specific.

What does "aspect" mean? (Also, typo: "Noticication". Also, "Freedestop"
on the previous line. Actually, the whole spec needs to be seriously
proofread, and by a native English speaker.)

> 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.
Maybe this is just because I write lots of networking code, but "host"
to me mostly means "a computer on a network".

> 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.

> org.freedesktop.StatusNotifierItem.Id
> org.freedesktop.StatusNotifierItem.Title

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

> 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.

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". Making it worse than useless.

> 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? 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.

Also, is OverlayIconName (as opposed to OverlayIconPixmap) actually
useful? It seems like you'd need to also specify *where* on the main
icon to overlay it.

> 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.

> org.freedesktop.StatusNotifierItem.AttentionMovieName

"Movie" is not standard terminology. Why not "AttentionAnimationName"?
"Movie" suggests that it should point to an MPEG or something.

> 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. Also, why does this property allow either a name or a path, but
all of the other ones only allow a path?

> org.freedesktop.StatusNotifierItem.ToolTip

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

> 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.

> 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).

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

> StatusNotifierWatcher

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

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. So the indirection through
StatusNotifierWatcher seems unnecessary.

> 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? Also, don't we need
"StatusNotifierHostUnregistered"?

> StatusNotifierHost

as with StatusNotifierIcon, there doesn't seem to be any reason for the
required naming convention

> 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

> Markup

> The markup is XML-based, and consists of a small subset of HTML.

s/HTML/XHTML/, as seen by the "/" in the <img> tag.

Need to talk about &lt; / &amp;. Are other entities allowed? Is it
really "XML-based" or is it just "XML-like"? (Eg, can you include a
CDATA section?).

> 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? Is the alt tag required,
or just allowed? Can it contain markup itself?

> 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? 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? What if
you want to provide an animation in multiple sizes?

-- Dan