From 08a2710777fe71967c05363dd442b8483e8dbd2c Mon Sep 17 00:00:00 2001 From: outfoxxed Date: Tue, 20 May 2025 01:46:23 -0700 Subject: [PATCH] toplvl-icon: add foreign-toplevel-icon protocol --- protocols/shell-foreign-toplevel-icon-v1.xml | 271 +++++++++++++++++++ 1 file changed, 271 insertions(+) create mode 100644 protocols/shell-foreign-toplevel-icon-v1.xml diff --git a/protocols/shell-foreign-toplevel-icon-v1.xml b/protocols/shell-foreign-toplevel-icon-v1.xml new file mode 100644 index 0000000..416d961 --- /dev/null +++ b/protocols/shell-foreign-toplevel-icon-v1.xml @@ -0,0 +1,271 @@ + + + + Copyright © 2025 outfoxxed + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + the copyright holders not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. The copyright holders make no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + + THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN + AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + + + + This protocol allows clients to discover icons set for foreign toplevel + windows from client provided pixel buffers or XDG icons. + + A toplevel icon represents the individual toplevel (unlike the application + or launcher icon, which represents the application as a whole), and may be + shown in window switchers, window overviews and taskbars that list + individual windows. + + The key words "must", "must not", "required", "shall", "shall not", + "should", "should not", "recommended", "may", and "optional" in this + document are to be interpreted as described in IETF RFC 2119. + + Warning! The protocol described in this file is intended as a stopgap + and is expected to be superseded by a solution in wayland-protocols. + Clients should not assume this protocol will continue to exist in the + future. + + + + + This interface allows clients to discover icons set for foreign toplevels. + + + + + + + + + + Destroy the manager. It is an error to destroy the manager without + destroying all icon handles created by it. + + + + + + Commit the client's icon size preferences. + + May be sent multiple times. Each commit creates a new list, + discarding preferred_size requests from the prior commit. + + + + + + Indicates an icon size that the client would prefer to have available. + The compositor should pass this request on to foreign clients, but + this preference may be ignored. + + A sequence of preferred_size events must be finished with a 'done' + event. If the client has no size preferences, it must still send + the 'commit' request. + + The client may revise its size preferences at any time by sending + a new preferred size list followed by another commit. + + + + + + + + Creates a new icon handle for the given toplevel. + + This request must not be made before the first commit request. + + + + + + + + + This event is emitted when an icon that the client does not have + a reference to is required to send the + shell_foreign_toplevel_icon_handle_v1.icon event. + + Multiple toplevel icon handles may refer to the same icon + simultaneously. + + + + + + + + + A handle tracking the current icon of a foreign toplevel. + + + + + This request destroys the icon handle and instructs the compositor + to stop sending 'icon' events for icons it would receive. + + Any icons for which this toplevel is the only user will receive + a 'finished' event, including new icons sent before the + compositor has processed this request. + + + + + + Sent when a new icon is set for this toplevel. + + A null icon indicates that the toplevel's icon has been unset and + the client should fall back on a different strategy such as + desktop entries for the toplevel's icon. + + Upon object creation, an icon event must be sent, with either an icon + object or null if the toplevel has not set an icon. + + + + + + + An icon used by one or more foreign toplevels. + + + + + + + + + + This request destroys the icon object. Destroying the icon + prior to receiving a 'finished' event is a protocol error. + + + + + + This event indicates that this icon will not be used in further + 'shell_foreign_toplevel_icon_handle_v1.icon' events and is safe + to destroy. + + This event may be sent in response to a release request or + when no toplevel icon handles refer to this icon anymore. + + + + + + This request indicates that the client would like to destroy + the icon object. + + The compositor must respond by either sending a + 'shell_foreign_toplevel_icon_handle_v1.icon' event referencing + this icon, or sending the 'finished' event to this object. + + + + + + Copy an icon listed by 'buffer' into a client provided buffer. + + The provided size and format must have been listed by 'buffer' + in the last icon option group. + + + + + + + + + + This event is sent after all 'add_buffer' events and optionally + an 'icon_name' event have been sent. + + + + + + This event assigns an icon name to this icon. It must not be + sent more than once, and must not be sent after 'done'. + + The icon refered to by the provided name should be resolved + according to the XDG icon theme specification[1] using the + environment's current icon theme. + + [1]: https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html + + + + + + + + This event exposes an available pixel buffer representing the icon. + Multiple add_buffer events may be sent at different sizes, scales, + and buffer formats. The event must not be sent after 'done'. + + The buffer must be backed by wl_shm and must be square. + + + + + + + + + + This request asks the compositor to copy one of the icon's available + pixel buffers to the provided client buffer. + + The selected buffer will be determined based on the format and width + of the provided client buffer, as well as the provided scale. If the + provided buffer and scale do not match a buffer associated with the icon, + the 'missing_buffer' error will be raised. + + The 'buffer_copied' event will be sent once the compositor has finished + copying the image to the client buffer. The wl_buffer.release event is unused. + + + + + + + + + This event is sent once the compositor has finished copying pixel + data into a provided client buffer. + + If multiple 'copy_buffer' requests were made, the received events + must refer to buffers in the same order the requests were made. + + + +