systray specification...

[Bradley T Hughes]

Carsten Haitzler (The Rasterman) wrote:
> 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.

Glad you agree :)

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

indeed... how we transport the data is uninteresting... avoiding
unnecessary transfers is, though ;)

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

yup, sounds just like what I was thinking... I had considered making the
icon data an array of _NET_WM_ICONs, but that means the system tray
would be required to fetch all icons again if only one of them changed.

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

Indeed...

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

I would think so yes. All of the strings in the EWMH are UTF-8 encoded,
so it would seem natural for them to be UTF-8 here as well.

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

For Button1 only, or would it make sense to give select/activate
for each button?

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

Looks good to me.

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

Perhaps DORMANT should be left up to the systray? That way,it can decide
which to hide and which not, depending on what the user configures (i.e.
hide icons unused/unchanged for 1 day, etc.)

>>> 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:
[snip]

Sounds sufficient to me... anything more advanced will have to be
handled by the application (as you describe below).

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

That sounds acceptable to me. We could even put the x/y coordinate of
the button event in l[4] if we decide it's needed and/or useful.

> 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: 
[snip]

This sounds good to me. This should cover most, if not all, of the needs
for menus in the systray.

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

Yes, you did :) The only thing I'm unclear about is how the systray
decides whether to show a menu, or to send the action. Should we always
send the activate, and the client has to respond with an "open menu"
type of message? Or should we "select" for what should happen in
response to various button presses?

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