--------------------------------------------------------------------- Command: add-tray-icon Add a status icons to the status icon tray The client should keep in mind that there can be any number of trays available on the system: zero, one, two or three, ..., and that it will get a response once from every tray Required header: Client ID Your ID, provided by `ID assignment` in response to `Command: assign-id` Required header: Package The name of the package to which the program announced the icon belongs Required header: Icon ID An ID of the icon that can be used identify the icon, icon ID:s are not unique, but the combination of a package and a icon ID should be unque and can be used to ignore already added icons and hide icons that the user has been configured to be hidden Required header: Title A title describing the icon for the user, used to configured when icons should be hidden and shown among other configuration Required header: Icon The name or pathname of an icon to use together with the title Response: To: In response to: Message ID: Socket: Will send update: <`yes` if this message will be followed by `Command: tray-update`, otherwise `no`> Purpose: Enable clients to add a small icon that displays the status of programs, particularly minimised programs and services Compulsivity: optional --------------------------------------------------------------------- Command: update-tray-icon Change the status of a status icon Required header: Status hide) Hide the icon show) Show the icon active) The icon is active inactive) The icon is inactive Purpose: Enable status trays to automatically hide inactive icons Purpose: Hide icons without actually removing them Compulsivity: required if supporting `Command: add-tray-icon`, only `Status: hide` and `Status show` is required --------------------------------------------------------------------- Command: tray-update Send updates about the status tray to the status icon Required header: Socket Where the icon is embedded, used to identify the affected tray Conditionally required header: Max colour Required if: `Colour`-header is used Required if: `Foreground`-header is used Required if: `Alpha`-header is used The maximum colour component value, for example, if using 24-bit colour, which component will be 8-bit and the maximum value will be 255, this also applies to the alpha component Conditionally required header: Size Required if, otherwise optional: `Length`-header is used The width and height, in pixels, the icon should have Conditionally required header: Has alpha Required if: `Length`-header is used yes) The message contains an alpha channel no) The message does not contain an alpha channel Conditionally required header: Bytes Required if: `Length`-header is used The number of bytes the subpixels used, for example, 24-bit colours will have this set to 1 because each subpixel has 8 bits, 48-bit colours will have this set to 2 because each subpixel has 16 bits Allowed values are: 1, 2, 4 and 8. These values are used used so that CPU:s with any endianness can be trivially used as the words sizes are guaranteed to be supported in C, and mixed/middle-endiannes gets complicated if we go outside this. Conditionally optional/required header: Colour Available and optional if: `Length`-header is not used Required if: `Foreground`-header but not `Length`-header is used Single blank space-separated [0, ] sRGB 3-tuple Conditionally optional header: Foreground Single blank space-separated [0, ] sRGB 3-tuple Optional header: Alpha The opacity of the tray Optional header: Length Length of the message Optional header: Use urgency yes) The icon tray may blink no) The icon tray may not blink Message: Raw binary encoding of the background image, bytes are orders: row, pixel, channel (alpha, red, green, blue), subpixel value (native CPU encoding). The Alpha channel should be included but ignored if `Has alpha: no`, in such as it is best to set it to full. Example image (with `Bytes: 2`, `Has alpha: no` and `Size: 3`): sRGB(x0102, 0, 0), sRGB(0, x0304, 0), sRGB(0, 0, x0506) sRGB(x0708, 0, 0), sRGB(0, x090A, 0), sRGB(0, 0, x0B0C) sRGB(x0D0E, 0, 0), sRGB(0, x0F10, 0), sRGB(0, 0, x1112) Encoding of example image (hexadecimal): FFFF 0102 0000 0000 FFFF 0000 0304 0000 FFFF 0000 0000 0506 FFFF 0708 0000 0000 FFFF 0000 090A 0000 FFFF 0000 0000 0B0C FFFF 0D0E 0000 0000 FFFF 0000 0F10 0000 FFFF 0000 0000 1112 Note that on a big-endian system this would be: FF FF 02 01 00 00 00 00 FF FF 00 00 04 03 00 00 FF FF 00 00 00 00 06 05 FF FF 08 07 00 00 00 00 FF FF 00 00 0A 09 00 00 FF FF 00 00 00 00 0C 0B FF FF 0E 0D 00 00 00 00 FF FF 00 00 10 0F 00 00 FF FF 00 00 00 00 12 11 (x86_64 computers are big-endian) It is up to the networking servers to translate the encoding between machines. (The host translates to big-endian unless they can confirm that they have the same endianness.) Purpose: Enable clients to be aware of the appearance of the tray, such as colours, transparency and background image Purpose: Enable clients to be aware of how the user wants status icons to behave Compulsivity: optional --------------------------------------------------------------------- Command: new-tray Announce the existence of a new status icon trays Purpose: Allow clients to add their status icons to status icon trays that have been added to the display after those programs have started and attempted to add their icons Compulsivity: required if supporting `Command: add-tray-icon` ---------------------------------------------------------------------