systray specification...

[Carsten Haitzler (The Rasterman)]

On Thu, 02 Feb 2006 10:23:10 +0100 Bradley T Hughes <bhughes at trolltech.com>
babbled:

> Carsten Haitzler (The Rasterman) wrote:
> > I likely will get shot down here, but I think these 2 things above need
> > fixing. It's still a draft spec, so let's discuss possibly better ways.
> > 
> > I would suggest that instead of reparenting the window, the systray can have
> > the option of reading ARGB pixel data just like the NETWM_ICON property
> > data. The systray icon owner can modify this property any time and then the
> > systray can update the display accordinly. This allows for the systray to
> > create a more consistent look and feel, not sacrificing display ability for
> > the application.
> 
> I like :)
> 
> However, even though the sizes of these icons tends to be small, the 
> overhead of pushing/fetching the image data from the X server isn't 
> something we should ignore (I'm thinking mostly about applets that 
> animate their icons at regular intervals). Perhaps we could also have 
> the option of simply specifying the name of an icon (which can be taken 
> from the current icon theme)? Or a way of pushing all icons to the 
> systray and a simply property/message to display a different image.

good point. very good point. the icon NAME is useful too - especialyl to help
enforce a more consistent look so the tray manager willl figure out what icon
to use by its name. as for uploads - good point too. i dont's ee we need to
worry too much that we aren't using shm transport to send the data, as it
should not be so much, but you have a very good point of being able to save
data/bandwidth/memory by specifyin a name and also being able to upload multilp
icons and attach them to a window then select which one to use.

so let's clarify this. a systray icon window may have a property of
_NET_SYSTEM_TRAY_ICON_ID which is of type ATOM and the value is the atom of the
icon property already set on the window to currently display in the systray.
this allows a client to attach more than 1 icon to its window and speciy which
one is displayed at any one time. if a property change notify event for the
_NET_SYSTEM_TRAY_ICON_ID atom is recieved, the tray must change icons. it is
free to cache previously-read icon data UNLESS it gets a property change event
for the atom for any of thosed previously read and cached icons. it must
re-read if there has been a change since it cached the result.

if the systray icon window application is happy to have a default icon from the
icon theme, it can set the _NET_SYSTEM_TRAY_ICON_NAME property which is of the
type UTF8_STRING and is a string name of the icon to display. if thsi property
changes, the tray manager should re-read it and then use that icon from the
icon theme as it sees fit.

also i'd like to clarify a point int he systray spec. IMHO the value of
_NET_WM_NAME shoudl be intended for the contents of any tooltip to display
around the icon, and should allow a user to identify exactly what it is easily
(name of application and/or description of what is happening).

also the ballon messages do not indicate encoding - i would suggest we clarify
thnigs to indicate the encoding is utf8 for the string?

> > As for handling events the systray can send back events such as "selected"
> > "activated" "disabled" etc. when a user might click on a systray icon, via
> > client messages and the systray icon owner can respond bu modifying the icon
> > data or doing something. 
> 
> Like++
> 
> Since there are very few actions that the user tends to do with systray 
> icons, the events would be very simple and few in number.

indeed - also the tray manager can standardise interaction. double-click ==
activae. single-click = select. mouse enter = hilight, mouse leave = unhilight
etc. (or whatever it sees is appropriate - but consistent between all systray
icons). this way a user now KNOWS of a set of interactions within their
enviornment that always work the same. they change it 1 place and it all
changes consistently. there are only a few things we need to handle here. what
information to send? well lets specify this a bit better

a client message with atom _NET_SYSTEM_TRAY_ACTION, fotmat 32 is sent TO the
tray icon window by the tray manager. the data payload is as followers l[0] = x
timestamp (or 0 if none is available) l[1] = action type (see below)
l[2] = 0
l[3] = 0
l[4] = 0

action types:
0 = SELECT (eg: a single click or press spacebar)
1 = ACTIVATE (eg: a double click or press enter)
2 = HOVER_IN (eg: mouse enters the icon or focus is tabbed into the icon)
3 = HOVER_OUT (eg: mouse exits the icon or focus is tabbed away from the icon)

i also think that the application owning the systray icon shoudl be able to
send "meta" events back. instead of every app blinking its own icon for example
- the systray will do it FOR the app (blink may mean pulsate for the systray,
or glow, or go from faded out to in and not animate at all - whatever the tray
manager and its configuration deeems is appropriate to notify a user of some
urgency). so if the tray icon wants to send events back it should send a client
message to the tray owners selection window of the atom _NET_SYSTEM_TRAY_ACTION
of the format 32 and the data payload being: l[0] = x timestamp (or 0 if none
is available) l[1] = window id of tray icon l[2] = action type (see below) l[3]
= 0 l[4] = 0

action types:
0 = NORMAL (display things as normal)
1 = INTERESTING (something interesting happend but its not that important)
2 = URGENT (something urgently needs attention right now)
3 = DORMANT (the systray owner is now dormant and shoudl be ignored)

> > As for menu popups you see often when right-clickign a systray icon - why
> > not have the systray do this as it's doing bubbles too? At least the menus
> > popping up will be consistent with eachother on systray items. Menus could
> > be described via properties (limiting their scope of content to maybe icon
> > + label + optional radio/check item, separators and submenus, and results
> > of user actions with the menus sent back as client messages)? This would
> > allow the desktop environment to make all the systray metadata be
> > consistent in terms of function, look and versatility.
> 
> Like++
> 
> Also, in cases where the applet wants to do more "advanced" things (like 
> a mixer showing a volume slider), the application has to do it. We'll 
> just have to provide a way of telling the systray what to do, e.g. 
> telling the icon that button 3 should either send a message or open a 
> named menu.

indeed - volume sliders and soon complicate things. i was trying to cover what
currently seems an almost 100% case for all systray icons - they all have right
click menus. we need a way to describe these menus in a simple way that
involves very simple decoding on the tray end so the menu can be easily built.
let's agree on what one may want in a menu.

1. a list of menus
2. a list of menu items per menu
each menu item may be either:
3. a separator
4. a item with a label (utf8 string - may be empty) and/or an icon property ID
5. the above items (not separators) may also have a link to another menu (ie
its submenu), OR they may have a toggle value (on/off) and radio group number
(with group #0 == its a check item). both 4 & 5 shoudl have some action ID
numebr that when selected is sent back to the systray icon window in a client
message as the resultant action.

as for thnigs like sliders - it may be possible to cover this too - if there
are no other "sane" uses we are likely to see (i would argue looking at the
gnome HIG bug thread even this is an abuse of the systray/notification area)
maybe we can cover it too.. if not the only opther thgn we need to do is
indicate the geometry of the icon that was activated/clicked on screen relative
to the root window. if there are multiple copies of it - then this needs to be
piggybacked on the action messages above. i might suggest using 16.16 encoding
-ie l[2] MSW = x, LSW = y, and l[3] MSW = width, LSW = height of the action
message the tray manager sends to tray clients?

as for encoding a menu structure (given the above is sufficient), i am thinking
make it a property atom _NET_SYSTEM_TRAY_MENU of type ATOM and format 32. it is
an array of atoms (also used as cardinals).each [] bracket set is a 32bit atom
value. [menu id][number of menu items] <- menu header

then a list of items as follows:
separator: [menu item type = 0]
normal item: [menu item type = 1][icon atom id][label atom id][action id]
check/radio item: [menu itep type = 2][icon atom id][label atom id][radio group
number (0 = check item)][toggle value][action id] submenu item: [menu item type
= 3][icon atom id][label atom id][submenu id]

then any following menu definitions repeated as above.

the icon atom id is an x atom that indicates a property on the systray icon
window to read for that icon ARGB data just like the _NEWTM_ICON property. the
label atom id similarly is an atom on the systray icon window that contains an
utf8 string for the label

... i hope i got the idea across anyway.

> > Let the flames begin.
> 
> -- 
> Bradley T. Hughes - bhughes at trolltech.com
> Trolltech AS - Sandakervn. 116, P.O. Box 4332 Nydalen, 0402 Oslo, Norway
> 


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