[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-03 10:32:22
Message-ID: 20060203193222.2f7b45f9.raster () rasterman ! com
[Download RAW message or body]

On Thu, 2 Feb 2006 16:56:29 +0900 Carsten Haitzler (The Rasterman)
<raster@rasterman.com> babbled:

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). again - let the flames begin :)

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

----
_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_ICON_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]