Atlas - xdg-toplevel-icon-v1.xml
Home / ext / SDL / wayland-protocols Lines: 1 | Size: 9379 bytes [Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)][FILE BEGIN]1<?xml version="1.0" encoding="UTF-8"?> 2<protocol name="xdg_toplevel_icon_v1"> 3 4 <copyright> 5 Copyright © 2023-2024 Matthias Klumpp 6 Copyright © 2024 David Edmundson 7 8 Permission is hereby granted, free of charge, to any person obtaining a 9 copy of this software and associated documentation files (the "Software"), 10 to deal in the Software without restriction, including without limitation 11 the rights to use, copy, modify, merge, publish, distribute, sublicense, 12 and/or sell copies of the Software, and to permit persons to whom the 13 Software is furnished to do so, subject to the following conditions: 14 15 The above copyright notice and this permission notice (including the next 16 paragraph) shall be included in all copies or substantial portions of the 17 Software. 18 19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 20 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 21 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 22 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 23 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 24 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 25 DEALINGS IN THE SOFTWARE. 26 </copyright> 27 28 <description summary="protocol to assign icons to toplevels"> 29 This protocol allows clients to set icons for their toplevel surfaces 30 either via the XDG icon stock (using an icon name), or from pixel data. 31 32 A toplevel icon represents the individual toplevel (unlike the application 33 or launcher icon, which represents the application as a whole), and may be 34 shown in window switchers, window overviews and taskbars that list 35 individual windows. 36 37 This document adheres to RFC 2119 when using words like "must", 38 "should", "may", etc. 39 40 Warning! The protocol described in this file is currently in the testing 41 phase. Backward compatible changes may be added together with the 42 corresponding interface version bump. Backward incompatible changes can 43 only be done by creating a new major version of the extension. 44 </description> 45 46 <interface name="xdg_toplevel_icon_manager_v1" version="1"> 47 <description summary="interface to manage toplevel icons"> 48 This interface allows clients to create toplevel window icons and set 49 them on toplevel windows to be displayed to the user. 50 </description> 51 52 <request name="destroy" type="destructor"> 53 <description summary="destroy the toplevel icon manager"> 54 Destroy the toplevel icon manager. 55 This does not destroy objects created with the manager. 56 </description> 57 </request> 58 59 <request name="create_icon"> 60 <description summary="create a new icon instance"> 61 Creates a new icon object. This icon can then be attached to a 62 xdg_toplevel via the 'set_icon' request. 63 </description> 64 <arg name="id" type="new_id" interface="xdg_toplevel_icon_v1"/> 65 </request> 66 67 <request name="set_icon"> 68 <description summary="set an icon on a toplevel window"> 69 This request assigns the icon 'icon' to 'toplevel', or clears the 70 toplevel icon if 'icon' was null. 71 This state is double-buffered and is applied on the next 72 wl_surface.commit of the toplevel. 73 74 After making this call, the xdg_toplevel_icon_v1 provided as 'icon' 75 can be destroyed by the client without 'toplevel' losing its icon. 76 The xdg_toplevel_icon_v1 is immutable from this point, and any 77 future attempts to change it must raise the 78 'xdg_toplevel_icon_v1.immutable' protocol error. 79 80 The compositor must set the toplevel icon from either the pixel data 81 the icon provides, or by loading a stock icon using the icon name. 82 See the description of 'xdg_toplevel_icon_v1' for details. 83 84 If 'icon' is set to null, the icon of the respective toplevel is reset 85 to its default icon (usually the icon of the application, derived from 86 its desktop-entry file, or a placeholder icon). 87 If this request is passed an icon with no pixel buffers or icon name 88 assigned, the icon must be reset just like if 'icon' was null. 89 </description> 90 <arg name="toplevel" type="object" interface="xdg_toplevel" summary="the toplevel to act on"/> 91 <arg name="icon" type="object" interface="xdg_toplevel_icon_v1" allow-null="true"/> 92 </request> 93 94 <event name="icon_size"> 95 <description summary="describes a supported & preferred icon size"> 96 This event indicates an icon size the compositor prefers to be 97 available if the client has scalable icons and can render to any size. 98 99 When the 'xdg_toplevel_icon_manager_v1' object is created, the 100 compositor may send one or more 'icon_size' events to describe the list 101 of preferred icon sizes. If the compositor has no size preference, it 102 may not send any 'icon_size' event, and it is up to the client to 103 decide a suitable icon size. 104 105 A sequence of 'icon_size' events must be finished with a 'done' event. 106 If the compositor has no size preferences, it must still send the 107 'done' event, without any preceding 'icon_size' events. 108 </description> 109 <arg name="size" type="int" 110 summary="the edge size of the square icon in surface-local coordinates, e.g. 64"/> 111 </event> 112 113 <event name="done"> 114 <description summary="all information has been sent"> 115 This event is sent after all 'icon_size' events have been sent. 116 </description> 117 </event> 118 </interface> 119 120 <interface name="xdg_toplevel_icon_v1" version="1"> 121 <description summary="a toplevel window icon"> 122 This interface defines a toplevel icon. 123 An icon can have a name, and multiple buffers. 124 In order to be applied, the icon must have either a name, or at least 125 one buffer assigned. Applying an empty icon (with no buffer or name) to 126 a toplevel should reset its icon to the default icon. 127 128 It is up to compositor policy whether to prefer using a buffer or loading 129 an icon via its name. See 'set_name' and 'add_buffer' for details. 130 </description> 131 132 <enum name="error"> 133 <entry name="invalid_buffer" 134 summary="the provided buffer does not satisfy requirements" 135 value="1"/> 136 <entry name="immutable" 137 summary="the icon has already been assigned to a toplevel and must not be changed" 138 value="2"/> 139 <entry name="no_buffer" 140 summary="the provided buffer has been destroyed before the toplevel icon" 141 value="3"/> 142 </enum> 143 144 <request name="destroy" type="destructor"> 145 <description summary="destroy the icon object"> 146 Destroys the 'xdg_toplevel_icon_v1' object. 147 The icon must still remain set on every toplevel it was assigned to, 148 until the toplevel icon is reset explicitly. 149 </description> 150 </request> 151 152 <request name="set_name"> 153 <description summary="set an icon name"> 154 This request assigns an icon name to this icon. 155 Any previously set name is overridden. 156 157 The compositor must resolve 'icon_name' according to the lookup rules 158 described in the XDG icon theme specification[1] using the 159 environment's current icon theme. 160 161 If the compositor does not support icon names or cannot resolve 162 'icon_name' according to the XDG icon theme specification it must 163 fall back to using pixel buffer data instead. 164 165 If this request is made after the icon has been assigned to a toplevel 166 via 'set_icon', a 'immutable' error must be raised. 167 168 [1]: https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html 169 </description> 170 <arg name="icon_name" type="string"/> 171 </request> 172 173 <request name="add_buffer"> 174 <description summary="add icon data from a pixel buffer"> 175 This request adds pixel data supplied as wl_buffer to the icon. 176 177 The client should add pixel data for all icon sizes and scales that 178 it can provide, or which are explicitly requested by the compositor 179 via 'icon_size' events on xdg_toplevel_icon_manager_v1. 180 181 The wl_buffer supplying pixel data as 'buffer' must be backed by wl_shm 182 and must be a square (width and height being equal). 183 If any of these buffer requirements are not fulfilled, a 'invalid_buffer' 184 error must be raised. 185 186 If this icon instance already has a buffer of the same size and scale 187 from a previous 'add_buffer' request, data from the last request 188 overrides the preexisting pixel data. 189 190 The wl_buffer must be kept alive for as long as the xdg_toplevel_icon 191 it is associated with is not destroyed, otherwise a 'no_buffer' error 192 is raised. The buffer contents must not be modified after it was 193 assigned to the icon. 194 195 If this request is made after the icon has been assigned to a toplevel 196 via 'set_icon', a 'immutable' error must be raised. 197 </description> 198 <arg name="buffer" type="object" interface="wl_buffer"/> 199 <arg name="scale" type="int" 200 summary="the scaling factor of the icon, e.g. 1"/> 201 </request> 202 </interface> 203</protocol> 204[FILE END](C) 2025 0x4248 (C) 2025 4248 Media and 4248 Systems, All part of 0x4248 See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.