diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/info/mds.texinfo | 263 | ||||
| -rw-r--r-- | doc/protocols | 161 |
2 files changed, 263 insertions, 161 deletions
diff --git a/doc/info/mds.texinfo b/doc/info/mds.texinfo index f8f3ba9..6a25575 100644 --- a/doc/info/mds.texinfo +++ b/doc/info/mds.texinfo @@ -1723,6 +1723,7 @@ simple, reference implementation of a, status icon tray. * Virtual Terminal Protocols:: Virtual terminal protocols. * Keyboard Protocols:: Keyboard protocols. * Clipboard Protocols:: Clipboard protocols. +* Status Icon Protocols:: Status icon protocols. * Miscellaneous Protocols:: Miscellaneous protocols. @end menu @@ -2796,6 +2797,268 @@ Optional add-on to the clipboard's functionallity. +@node Status Icon Protocols +@section Status Icon Protocols + +@menu +* add-tray-icon:: Add a status icons to the status icon tray. +* update-tray-icon:: Change the status of a status icon. +* tray-update:: Send updates about the status tray to the status icon. +* new-tray:: Announce the existence of a new status icon trays. +@end menu + + + +@node add-tray-icon +@subsection add-tray-icon + +@table @asis +@item Identifying header: +@command{Command: add-tray-icon} + +@item Action: +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. + +@item Required header: @code{Client ID} +Your ID, provided by the @code{ID assignment} header +in response to a @code{Command: assign-id} header. + +@item Required header: @code{Package} +The name of the package to which the program announced the icon +belongs. + +@item Required header: @code{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. + +@item Required header: @code{Title} +A title describing the icon for the user, used to configured +when icons should be hidden and shown among other configuration. + +@item Required header: @code{Icon} +The name or pathname of an icon to use together with the title. + +@item Response: +Recipients will respond with a message containing the headers: +@table @code +@item To +Will contain the value of the @code{Client ID} from the +message that triggered this response. +@item In response to +Will contain the value of the @code{Message ID} from the +message that triggered this response. +@item Message ID +Will contain a value as described in @ref{Message Passing}. +@item Socket +Will contain an ID to where the icon should be embeded. +@item Will send update +The value of this header will be @code{yes} if this +message will be followed by a @code{Command: tray-update} +message. Otherwise the value will be @code{no}. +@end table + +@item Purpose: +Enable clients to add a small icon that displays the status +of programs, particularly minimised programs and services. + +@item Compulsivity: +Optional. +@end table + + + +@node update-tray-icon +@subsection update-tray-icon + +@table @asis +@item Identifying header: +@command{Command: update-tray-icon} + +@item Action: +Change the status of a status icon. + +@item Required header: @code{Status} +@table @code +@item hide +Hide the icon if the value of the +@code{Status} header is @code{hide}. +@item show +Show the icon if the value of the +@code{Status} header is @code{show}. +@item active +The icon is active if the value of +the @code{Status} header is @code{active}. +@item inactive +The icon is inactive if the value of +the @code{Status} header is @code{inactive}. +@end table + +@item Purpose: +Enable status trays to automatically hide inactive icons. + +@item Purpose: +Hide icons without actually removing them. + +@item Compulsivity: +Required if supporting @code{Command: add-tray-icon}, +only @code{Status: hide} and @code{Status show} is required. +@end table + + + +@node tray-update +@subsection tray-update + +@table @asis +@item Identifying header: +@command{Command: tray-update} + +@item Action: +Send updates about the status tray to the status icon. + +@item Required header: @code{Socket} +Where the icon is embedded, used to identify the +affected tray. + +@item Conditionally required header: @code{Max colour} +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. +Required if either for the @code{Colour}-, @code{Foreground}- +or @code{Alpha}-header are used. + +@item Conditionally required header: @code{Size} +The width and height, in pixels, the icon should have. +Required if the @code{Length}-header is used, +otherwise this header is optional. + +@item Conditionally required header: @code{Has alpha} +@table @code +@item yes +The message contains an alpha channel if the +value of the @code{Has alpha} header is @code{yes}. +@item no +The message does not contain an alpha channel if the +value of the @code{Has alpha} header is @code{no}. +@end table +Required if the @code{Length}-header is used. + +@item Conditionally required header: @code{Bytes} +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. +Required if the @code{Length}-header is used. + +@item Conditionally optional/required header: @code{Colour} +Single blank space-separated [0, @code{<Max colour>}] +sRGB 3-tuple. +Available and optional if the @code{Length}-header +is not used. +Required if the @code{Foreground}-header but not +@code{Length}-header is used. + +@item Conditionally optional header: @code{Foreground} +Single blank space-separated [0, @code{<Max colour>}] sRGB 3-tuple. + +@item Optional header: @code{Alpha} +The opacity of the tray. + +@item Optional header: @code{Length} +Length of the message. + +@item Optional header: @code{Use urgency} +@table @code +@item yes +The icon tray may blink if the value of the +@code{Use urgency} header is @code{yes}. +@item no +The icon tray may not blink if the value of +the @code{Use urgency} header is @code{no}. +@end table + +@item 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 +@code{Has alpha: no}, in such as it is best to set +it to full. + +Example image with @code{Bytes: 2}, +@code{Has alpha: no} and @code{Size: 3}: +@example +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) +@end example + +Encoding of example image in hexadecimal representation: +@example +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 +@end example + +Note that on a big-endian system this would be: +@footnote{x86_64 computers are big-endian.} +@example +FF FF 02 01 0 0 0 0 FF FF 0 0 04 03 0 0 FF FF 0 0 0 0 06 05 +FF FF 08 07 0 0 0 0 FF FF 0 0 0A 09 0 0 FF FF 0 0 0 0 0C 0B +FF FF 0E 0D 0 0 0 0 FF FF 0 0 10 0F 0 0 FF FF 0 0 0 0 12 11 +@end example + +It is up to the networking servers to translate +the encoding between machines.@footnote{The host +translates to big-endian unless they can confirm +that they have the same endianness.} + +@item Purpose: +Enable clients to be aware of the appearance of the tray, +such as colours, transparency and background image. + +@item Purpose: +Enable clients to be aware of how the user wants +status icons to behave. + +@item Compulsivity: +Optional. +@end table + + + +@node new-tray +@subsection new-tray + +@table @asis +@item Identifying header: +@command{Command: new-tray} + +@item Action: +Announce the existence of a new status icon trays. + +@item 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. + +@item Compulsivity: +Required if supporting @code{Command: add-tray-icon}. +@end table + + + @node Miscellaneous Protocols @section Miscellaneous Protocols diff --git a/doc/protocols b/doc/protocols deleted file mode 100644 index 52c61bf..0000000 --- a/doc/protocols +++ /dev/null @@ -1,161 +0,0 @@ ---------------------------------------------------------------------- - -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` - ---------------------------------------------------------------------- - |