Page MenuHomePhabricator

E Systray Spec
Updated 2,363 Days AgoPublic


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, and is familiar with both the ICCCM and NEWTM extensions specification here.

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.

New specifications


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.


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 the naming spec.

New icon naming

The following client messages are added to the specification:


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)

Existing specification changes


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.

Imported from
1 mcalamelli 2009-01-30 01:45:16

Last Author
Last Edited
Sep 5 2013, 2:14 PM