Tray icons may ask the system tray to display a balloon message to the user. The system tray coordinates balloon messages to ensure that they have a consistent look-and-feel, and to avoid displaying multiple balloon messages at once.
A balloon message is a short text message to be displayed to the user. The message may have a timeout; if so, the message will be taken down after the timeout expires. Messages are displayed in a queue, as only one can appear at a time; if a message has a timeout, the timer begins when the message is first displayed. Users may be allowed to close messages at any time, and may be allowed to disable all message display.
System trays may display balloon messages in any way they see fit; for example, instead of popping up a balloon, they could choose to put a special indicator around icons with pending messages, and display the message on mouseover.
Balloon messages are sent from the tray icon to the system tray
selection owner window as a series of client messages. The first
client message is an opcode message, and contains the usual timestamp,
and the op code SYSTEM_TRAY_BEGIN_MESSAGE
.
xclient.data.l[2]
contains the timeout in
thousandths of a second or zero for infinite timeout,
xclient.data.l[3]
contains the length
of the message string in bytes, not including any nul bytes, and
xclient.data.l[4]
contains an ID number
for the message. This ID number should never be reused by
the same tray icon. (The simplest way to generate the ID number
is to increment it with each message sent.)
Following the SYSTEM_TRAY_BEGIN_MESSAGE
op code, the tray icon should send a series of client messages
with a message_type
of
_NET_SYSTEM_TRAY_MESSAGE_DATA
. These client
messages must have their window
field set
to the window ID of the tray icon, and have a
format
of 8.
Each _NET_SYSTEM_TRAY_MESSAGE_DATA
message
contains 20 bytes of the message string, up to the length given
in the SYSTEM_TRAY_BEGIN_MESSAGE
opcode.
If the message string is zero-length, then no messages need be
sent beyond the SYSTEM_TRAY_BEGIN_MESSAGE
.
A terminating nul byte should never be sent.
System trays may receive portions of messages from several tray icons at once, so are required to reassemble the messages based on the window ID of the tray icon.
The tray icon may wish to cancel a previously-sent balloon
message. To do so, it sends a
SYSTEM_TRAY_CANCEL_MESSAGE
opcode with
data.l[2]
set to the ID number of the message
to cancel.