[prev in list] [next in list] [prev in thread] [next in thread] 

List:       freedesktop-xdg
Subject:    Re: systray specification...
From:       Carsten Haitzler (The Rasterman) <raster () rasterman ! com>
Date:       2006-02-08 2:47:40
Message-ID: 20060208114740.056464a5.raster () rasterman ! com
[Download RAW message or body]

On Fri, 3 Feb 2006 07:19:31 -0700 "Aaron J. Seigo" <aseigo@kde.org> babbled:

> On Friday 03 February 2006 03:32, Carsten Haitzler wrote:
> > OK - for now i've dropped the menu stuff. i've attached a much mroe
> > detailed description of spec additions in the new_systray.txt. please read
> > it over and throw in suggestions on improvements. we should still discuss
> > the way of delivering icons i believe as there is no consensus yet. i
> > personally stand on the side of "stick clear of requiring extra extansions
> > to define the icons". (so re-use existing properties).
> 
> one of the nice things is we get multiple icons sizes for the tray along the 
> way. we may wish to recommend 16, 22 and 32px icons be provided for all 
> systray entries as that will encourage developers to provide enough variety 
> that the icons won't look like crap due to being scaled.

sure. though it's a trecommendation. in reality i see at most 2 sizes happening
and in future likely only 1 and peole will just live with a scaled down image
(the larger one just needs to refrain from too much detail) :) i've added the
note to an updated draf (attached).

> instead of using _NET_WM_ICON_NAME for the tooltip/popup text, could we 
> perhaps use _NET_WM_VISIBLE_NAME instead for clarity's sake? i think having 
> "SYSTEM_TRAY_ICON_NAME" being a name of an icon and "ICON_NAME" being text 
> shown for the icon to be more than a little confusing, and were i reading it 
> for the first time as an outsider i'd think "boy, they sure have trouble 
> naming things clearly." ;)

i'm pretty agnostic here - but visible name is fine by me :)

> as for _NET_WM_NAME, i'm not sure if its enough for accessibility needs the 
> way it's written: "This property should be used to identify the application 
> name that owns this tray icon so it is easy to know where it came from." this 
> may be interesting for systray implementations to use to connect the tray 
> item with, say, taskbar entries .... but we probably want something more than 
> "amarok", "kmail", "klaptopdaemon", etc... for screenreaders. if this is 
> combined with the WM_ICON_NAME atom we'd get things like: "klaptopdaemon: 25% 
> charged". we want something more like: "laptop battery monitor: 25% charged". 
> while we could use NET_WM_NAME for this, we then lose the nice app<->tray 
> entry mapping that would be useful elsewhere. 

well i wasn't aiming at a specific name. i was aiming to stop bad examples like:

"idle with no connections"

what is that? maybe:
"not connected to instant messenger service. currently idle"

for an instant messenger systray icon. at least you know what it is "oh thats
my instant messenger app" - but if it doesnt even hint at what it may be -
that's bad. WM_CLASS can be used to identify the application explicitly i
think. anyway i've atttached an updated draft. comments of course are very much
welcome/desired etc.

> i'm on the fence as to whether we should use yet another atom here or rejig 
> the definition of one of the ones already used in your draft spec here. but 
> then, it's only 07:20 here so i don't expect non-fuzzy thinking yet ;)
>  
> -- 
> Aaron J. Seigo
> GPG Fingerprint: 8B8B 2209 0C6F 7C47 B1EA  EE75 D6B7 2EB1 A7F1 DB43
> 
> Full time KDE developer sponsored by Trolltech (http://www.trolltech.com)
> 


-- 
------------- Codito, ergo sum - "I code, therefore I am" --------------
The Rasterman (Carsten Haitzler)    raster@rasterman.com
裸好多
Tokyo, Japan (東京 日本)

["new_systray.txt" (text/plain)]

A proposal for a new SYSTRAY specification that fixes some real nasty
problems in the existing one.

It is assumed the reader has read the entire existing specification v 0.2 here:
  http://www.freedesktop.org/wiki/Standards_2fsystemtray_2dspec
and is familiar with both the ICCCM and NEWTM extensions specification here:
  http://www.freedesktop.org/wiki/Standards_2fwm_2dspec

This makes the following CHANGES to the specification

1. the system tray no longer re-parents or maps the tray icon. the tray icon's
window is left alone as far as this is concerned and is used merely as a
communications port (where in the future this communication may be moved or
duplicated in another IPC mechanism possibly).

2. it is backwards-compatible with older system tray icons. if the tray icons do not \
provide the new properties they are considered "old style" and may either be ignored \
by the system tray as "legacy" or handled in the old way.

a systray icon conforming to the newer scheme will have either an property of the \
atom _NET_SYSTEM_TRAY_ICON_ID and type ATOM, and format 32 or a property of the atom \
_NET_SYSTEM_TRAY_ICON_NAME and type UTF8_STRING on the tray icon window.

the following are new properties:

----
_NET_SYSTEM_TRAY_ICON_ID, ATOM

This property holds the atom value of the current icon to display. in the event this \
property changes, or the first time the tray icon is "managed", the property value is \
to be fetched. the value of this property is an ATOM id that indicates which icon to \
display. the system tray then must fetch the icon from the tray icon window of the \
property atom id provided. the format of this icon is the same as that of the \
_NET_WM_ICON property (please see the netwm icccm extensions specification). the \
system tray then should display this icon in the location(s) where the system tray \
icon will be displayed. the system tray is free to choose any of the icon sizes \
provided based on which is most appropriate.

a note to implementors: the system tray is free to cache already read pixel data for \
icons and avoid re-reading it IF there has been no propertychangenotify events for \
the cached icon properties since the last read. if the currently displayed icon's \
property receives a propertychangenotify event, then the system tray must re-read the \
property and re-display it accordingly. it is suggested that the atom NAME of each \
icon follow a general standard to avoid an atom id explosion. it is suggested to use \
a naming convention of _NET_SYSTEM_TRAY_ICON_n where n is an integer number starting \
at 0 and increasing monotonically for each unique item a systray icon may store on \
its tray icon. it should also be noted that the _NET_WM_ICON property does allow for \
multiple sizes of an icon to be provided, so it would be a good idea to provide \
multiple "custom drawn" icons in multiple sizes. if one size is merely an \
algorithmically scaled down version of a larger icon, the application may want to \
refrain from providing it as the system tray will likely be able to do the scaling \
itself with much grater precision (i.e. scaling to the EXACT size needed). common \
sizes used for icons would be 16, 22, 32 and 48 pixels in both x and y dimensions.

----
_NET_SYSTEM_TRAY_ICON_NAME, UTF8_STRING[]

this property contains a utf8 encoded string naming an icon from the current icon \
theme. this property may be used alongside the _NET_SYSTEM_TRAY_ICON_ID, and the \
system tray may choose whichever it prefers at any time. if both are implemented by \
the tray icon, it must realize this and make sure it updates both as the system tray \
may choose to only handle one and ignore the other. for details on the icon naming \
specification please see:

http://www.freedesktop.org/wiki/Standards_2ficon_2dnaming_2dspec

the following client messages are added to the specification:

----
_NET_WM_VISIBLE_NAME, UTF8_STRING[]

this property describes the contents of an information popup that may be displayed as \
a tooltip popup or anywhere else the system tray desires indicating current status of \
the system tray icon (busy, downloading 25%, incoming call, waiting for response \
etc.). it is a string intended to hold textual details of the current icon status. it \
should not be long and not be required to be visible, but provide extra information \
to a user when they need it.

----
type = _NET_SYSTEM_TRAY_STATUS
format = 32

this message is sent by the tray icon to the system tray window. the format of the \
data payload is as follows:

data.l[0] = x timestamp for when the state changed (or 0 for "current time")
data.l[1] = status op-code (see below)
data.l[2] = unused
data.l[3] = unused
data.l[4] = unused

op-codes can be:
0 = normal state (the default state)
1 = inactive (the tray icon has gone inactive because the reason for it being there \
has temporarily gone away) 2 = active (the thing the tray icon is monitoring is now \
actively working) 3 = urgent (some urgent information can be gained by activating the \
tray icon by clicking on it or something)

The system tray is free to modify the display of tray icons to indicate the above \
states (by fading them out, making them pulsate, glow, blink or something else).

----
type = _NET_SYSTEM_TRAY_ACTION
format = 32

this message is send by the system tray to the tray icon window when some user \
interaction takes place on the system tray icon. the data payload is as follows:

data.l[0] = x timestamp for when the action happened (or 0 for "current time")
data.l[1] = (action opcode (see below)) | (mouse button triggered << 16)
data.l[2] = (mouse x co-ord relative to systray << 16) | (mouse y)
data.l[3] = (tray icon x co-ord relative to root << 16) (y co-ord)
data.l[4] = (tray icon width << 16) | (tray height)

not all co-ordinates are in pixels, relative to the top-left origin and are signed 16 \
bit integer values. the mouse button value of 0 == no button caused this event.

action op-codes can be:

0 = selected (the item has been selected - likely a left mouse click)
1 = activated (the item has been activated - should be rarely used, but for example a \
double click - policy dependent) 2 = hover_in (the mouse may be hovering over the \
systray icon) 3 = hover_out (the mouse stopped hovering over the systray icon)
4 = show_controls (generally a right click on the icon which would display a menu)
5 = quit (the user has indicated they want the system tray icon gone and any process \
required to maintain the icon to exit)

.......................

clarifications on existing system tray specifications:

_NET_WM_NAME, UTF8_STRING

This property should be used to identify the application name that owns this tray \
icon so it is easy to know where it came from.

Balloon messages

All balloon messages are encoded as UTF8 strings.



[prev in list] [next in list] [prev in thread] [next in thread]