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
xclient.data.l contains the timeout in
thousandths of a second or zero for infinite timeout,
xclient.data.l contains the length
of the message string in bytes, not including any nul bytes, and
xclient.data.l 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.)
op code, the tray icon should send a series of client messages
_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.
contains 20 bytes of the message string, up to the length given
If the message string is zero-length, then no messages need be
sent beyond the
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 set to the ID number of the message