1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
---------------------------------------------------------------------
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: <Client ID>
In response to: <Message ID>
Message ID: <the status tray's message ID>
Socket: <Where to embed the icon>
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, <Max colour>] sRGB 3-tuple
Conditionally optional header: Foreground
Single blank space-separated [0, <Max colour>] 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`
---------------------------------------------------------------------
|
