systray specification...

[Carsten Haitzler (The Rasterman)]

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

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

:) agreements are good - it's less to have to compromise on :)

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

true. the other suggestion here is to use xrender pictures. it is a point. did
think about it, but then decidced against for 2 reasons.

1. it allows the spec to be implemented on ANY XSERVER - even that ancient
labtam monochrome 1bit terminal sitting on a 10mbit coax network. it will work.
2. it is consistent with an existing netwm spec that many apps implement
(recycling identical mechanisms and thus code). 3. is "necessary and
sufficient" as no systray item really want to implement a full gui (and the HIG
suggestions are pretty much that it does no such thing - that systray icon
avoid becoming miniature ui's). and so works within existing suggested
guidelines.

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

yeah - just 1 or more atoms (of any name) on the window will do as long as the
tray manager knows which one to use and when.

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

just a desire to clarify some things - glad you agree :)

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

yes - that was an assumption of mine too. "well of course it's utf8" - but
nowhere does it STATE this in the systray spec - so it'd be nice to make that
explicit :)

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

well i was thinking more along the lines that it wouldnt matter what button.
the systray manager woudl enforce some policy - ie single click == select,
middle click or double = activate, 3 fingered salute = something else etc. the
systray manager would implement such policy and so there is no need for as
strict a HIG on systray icons as the tray manager enforces the HIG for a
particulay environment. the applications merely provide the most basic data
needed.

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

i think this can be done both ways. the syystray can just choose to hide
systray icons that have not doen anything interesting in a while TOO - it can
ALSO take "dormant" as an explicit hint that the icon owner knows it is going
to sleep for a while and the systray doesnthave to wait for a timeout to hide
that icon. rememebr i am thinking of these as "hints" not as explicit
instructions :) the systray manager still has the final say here based on its
configuration policy 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).

i am assuming so too. the application can display its main window or a popup
window with a silder etc. as long as it knows the geometry of the systray
icons' location and/or the mouse - this should be workable. no?

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

agreed. thouhg if its activated by a keystroke there are no co-ordinates so i
was for now thinking this might be extra unneeded info - but we can throw it in
i guess.

> > 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 again we can let the systray apps do the mensu too- this makes the systray
manager simpler, but it does (based on other mailes) requrie the systray app
actuially use a toolkit then to display menus. also we have grab issues with
the mouse - if the mouse is still implicitly grabbed by the systray, it's hard
ot do working menus well... that was one of the reasons for providing menus as
metadata.

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

well i was thinking that if the contents of a menu change - the systray client
changes properties. but otherwise when a menu is shown is up to the systray
manager. it may be on right mouse clikc, on alt+left click, middle click -
maybe an extra menu button placed above/below systray icons - etc. the systray
manager determines such policy and thus the policy is consistent between all
systray icons. it also allows the client  to be VERY simple - it can be a
daemon process who only connects to x for IPC purposes of providing a systray
control point. the systray manager's policies decide what a left mouse click on
an icon means, or a double click, or a middle click, right click, keyboard
navigation etc. etc. etc. the messages sent are "action information" and no
assumption should be made as to what physical event actually triggered them.

does this sound ok?

> -- 
> 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 (東京 日本)