Balloon messages

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.