System Tray Protocol Specification

Havoc Pennington


Version 0.3

Table of Contents

Locating the system tray
Opcode messages
Docking a tray icon
Visual and background pixmap handling
Tray icon hints
Tray manager hints
Balloon messages
A. Change history


The "system tray" is an application running on a given X screen that can display small icons provided by running applications. Windows XP calls this feature the "notification area." [1] Inspired by KDE, this specification uses the term "system tray."

From a UI standpoint, the system tray is normally used for transient icons that indicate some special state, while full-blown "applets" are used for permanent dock/panel features. For example, a system tray icon might appear to tell the user that they have new mail, or have an incoming instant message, or something along those lines.

The basic idea is that creating an icon in the notification area is less annoying than popping up a dialog. However it's also harder to notice, so Windows XP adds a feature allowing tray icons to pop up small message balloons. (Users can disable these via a hidden registry setting.) This specification also supports the balloon feature.

[1] According to the MSDN documentation for the Shell_NotifyIcon() function, "The taskbar notification area is sometimes erroneously called the 'tray.'" So presumably "notification area" is the official term on Windows. Parts of the docs also call it the "status area."