Balloon messages
Prev |  | Next

## 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.

Prev |  | Next
Tray manager hints | Home | A. Change history