Warning, /plasma/layer-shell-qt/src/wlr-layer-shell-unstable-v1.xml is written in an unsupported language. File is not indexed.
0001 <?xml version="1.0" encoding="UTF-8"?> 0002 <protocol name="wlr_layer_shell_unstable_v1"> 0003 <copyright> 0004 Copyright © 2017 Drew DeVault 0005 0006 Permission to use, copy, modify, distribute, and sell this 0007 software and its documentation for any purpose is hereby granted 0008 without fee, provided that the above copyright notice appear in 0009 all copies and that both that copyright notice and this permission 0010 notice appear in supporting documentation, and that the name of 0011 the copyright holders not be used in advertising or publicity 0012 pertaining to distribution of the software without specific, 0013 written prior permission. The copyright holders make no 0014 representations about the suitability of this software for any 0015 purpose. It is provided "as is" without express or implied 0016 warranty. 0017 0018 THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS 0019 SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND 0020 FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY 0021 SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 0022 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN 0023 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, 0024 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF 0025 THIS SOFTWARE. 0026 </copyright> 0027 0028 <interface name="zwlr_layer_shell_v1" version="4"> 0029 <description summary="create surfaces that are layers of the desktop"> 0030 Clients can use this interface to assign the surface_layer role to 0031 wl_surfaces. Such surfaces are assigned to a "layer" of the output and 0032 rendered with a defined z-depth respective to each other. They may also be 0033 anchored to the edges and corners of a screen and specify input handling 0034 semantics. This interface should be suitable for the implementation of 0035 many desktop shell components, and a broad number of other applications 0036 that interact with the desktop. 0037 </description> 0038 0039 <request name="get_layer_surface"> 0040 <description summary="create a layer_surface from a surface"> 0041 Create a layer surface for an existing surface. This assigns the role of 0042 layer_surface, or raises a protocol error if another role is already 0043 assigned. 0044 0045 Creating a layer surface from a wl_surface which has a buffer attached 0046 or committed is a client error, and any attempts by a client to attach 0047 or manipulate a buffer prior to the first layer_surface.configure call 0048 must also be treated as errors. 0049 0050 After creating a layer_surface object and setting it up, the client 0051 must perform an initial commit without any buffer attached. 0052 The compositor will reply with a layer_surface.configure event. 0053 The client must acknowledge it and is then allowed to attach a buffer 0054 to map the surface. 0055 0056 You may pass NULL for output to allow the compositor to decide which 0057 output to use. Generally this will be the one that the user most 0058 recently interacted with. 0059 0060 Clients can specify a namespace that defines the purpose of the layer 0061 surface. 0062 </description> 0063 <arg name="id" type="new_id" interface="zwlr_layer_surface_v1"/> 0064 <arg name="surface" type="object" interface="wl_surface"/> 0065 <arg name="output" type="object" interface="wl_output" allow-null="true"/> 0066 <arg name="layer" type="uint" enum="layer" summary="layer to add this surface to"/> 0067 <arg name="scope" type="string" summary="namespace for the layer surface"/> 0068 </request> 0069 0070 <enum name="error"> 0071 <entry name="role" value="0" summary="wl_surface has another role"/> 0072 <entry name="invalid_layer" value="1" summary="layer value is invalid"/> 0073 <entry name="already_constructed" value="2" summary="wl_surface has a buffer attached or committed"/> 0074 </enum> 0075 0076 <enum name="layer"> 0077 <description summary="available layers for surfaces"> 0078 These values indicate which layers a surface can be rendered in. They 0079 are ordered by z depth, bottom-most first. Traditional shell surfaces 0080 will typically be rendered between the bottom and top layers. 0081 Fullscreen shell surfaces are typically rendered at the top layer. 0082 Multiple surfaces can share a single layer, and ordering within a 0083 single layer is undefined. 0084 </description> 0085 0086 <entry name="background" value="0"/> 0087 <entry name="bottom" value="1"/> 0088 <entry name="top" value="2"/> 0089 <entry name="overlay" value="3"/> 0090 </enum> 0091 0092 <!-- Version 3 additions --> 0093 0094 <request name="destroy" type="destructor" since="3"> 0095 <description summary="destroy the layer_shell object"> 0096 This request indicates that the client will not use the layer_shell 0097 object any more. Objects that have been created through this instance 0098 are not affected. 0099 </description> 0100 </request> 0101 </interface> 0102 0103 <interface name="zwlr_layer_surface_v1" version="4"> 0104 <description summary="layer metadata interface"> 0105 An interface that may be implemented by a wl_surface, for surfaces that 0106 are designed to be rendered as a layer of a stacked desktop-like 0107 environment. 0108 0109 Layer surface state (layer, size, anchor, exclusive zone, 0110 margin, interactivity) is double-buffered, and will be applied at the 0111 time wl_surface.commit of the corresponding wl_surface is called. 0112 0113 Attaching a null buffer to a layer surface unmaps it. 0114 0115 Unmapping a layer_surface means that the surface cannot be shown by the 0116 compositor until it is explicitly mapped again. The layer_surface 0117 returns to the state it had right after layer_shell.get_layer_surface. 0118 The client can re-map the surface by performing a commit without any 0119 buffer attached, waiting for a configure event and handling it as usual. 0120 </description> 0121 0122 <request name="set_size"> 0123 <description summary="sets the size of the surface"> 0124 Sets the size of the surface in surface-local coordinates. The 0125 compositor will display the surface centered with respect to its 0126 anchors. 0127 0128 If you pass 0 for either value, the compositor will assign it and 0129 inform you of the assignment in the configure event. You must set your 0130 anchor to opposite edges in the dimensions you omit; not doing so is a 0131 protocol error. Both values are 0 by default. 0132 0133 Size is double-buffered, see wl_surface.commit. 0134 </description> 0135 <arg name="width" type="uint"/> 0136 <arg name="height" type="uint"/> 0137 </request> 0138 0139 <request name="set_anchor"> 0140 <description summary="configures the anchor point of the surface"> 0141 Requests that the compositor anchor the surface to the specified edges 0142 and corners. If two orthogonal edges are specified (e.g. 'top' and 0143 'left'), then the anchor point will be the intersection of the edges 0144 (e.g. the top left corner of the output); otherwise the anchor point 0145 will be centered on that edge, or in the center if none is specified. 0146 0147 Anchor is double-buffered, see wl_surface.commit. 0148 </description> 0149 <arg name="anchor" type="uint" enum="anchor"/> 0150 </request> 0151 0152 <request name="set_exclusive_zone"> 0153 <description summary="configures the exclusive geometry of this surface"> 0154 Requests that the compositor avoids occluding an area with other 0155 surfaces. The compositor's use of this information is 0156 implementation-dependent - do not assume that this region will not 0157 actually be occluded. 0158 0159 A positive value is only meaningful if the surface is anchored to one 0160 edge or an edge and both perpendicular edges. If the surface is not 0161 anchored, anchored to only two perpendicular edges (a corner), anchored 0162 to only two parallel edges or anchored to all edges, a positive value 0163 will be treated the same as zero. 0164 0165 A positive zone is the distance from the edge in surface-local 0166 coordinates to consider exclusive. 0167 0168 Surfaces that do not wish to have an exclusive zone may instead specify 0169 how they should interact with surfaces that do. If set to zero, the 0170 surface indicates that it would like to be moved to avoid occluding 0171 surfaces with a positive exclusive zone. If set to -1, the surface 0172 indicates that it would not like to be moved to accommodate for other 0173 surfaces, and the compositor should extend it all the way to the edges 0174 it is anchored to. 0175 0176 For example, a panel might set its exclusive zone to 10, so that 0177 maximized shell surfaces are not shown on top of it. A notification 0178 might set its exclusive zone to 0, so that it is moved to avoid 0179 occluding the panel, but shell surfaces are shown underneath it. A 0180 wallpaper or lock screen might set their exclusive zone to -1, so that 0181 they stretch below or over the panel. 0182 0183 The default value is 0. 0184 0185 Exclusive zone is double-buffered, see wl_surface.commit. 0186 </description> 0187 <arg name="zone" type="int"/> 0188 </request> 0189 0190 <request name="set_margin"> 0191 <description summary="sets a margin from the anchor point"> 0192 Requests that the surface be placed some distance away from the anchor 0193 point on the output, in surface-local coordinates. Setting this value 0194 for edges you are not anchored to has no effect. 0195 0196 The exclusive zone includes the margin. 0197 0198 Margin is double-buffered, see wl_surface.commit. 0199 </description> 0200 <arg name="top" type="int"/> 0201 <arg name="right" type="int"/> 0202 <arg name="bottom" type="int"/> 0203 <arg name="left" type="int"/> 0204 </request> 0205 0206 <enum name="keyboard_interactivity"> 0207 <description summary="types of keyboard interaction possible for a layer shell surface"> 0208 Types of keyboard interaction possible for layer shell surfaces. The 0209 rationale for this is twofold: (1) some applications are not interested 0210 in keyboard events and not allowing them to be focused can improve the 0211 desktop experience; (2) some applications will want to take exclusive 0212 keyboard focus. 0213 </description> 0214 0215 <entry name="none" value="0"> 0216 <description summary="no keyboard focus is possible"> 0217 This value indicates that this surface is not interested in keyboard 0218 events and the compositor should never assign it the keyboard focus. 0219 0220 This is the default value, set for newly created layer shell surfaces. 0221 0222 This is useful for e.g. desktop widgets that display information or 0223 only have interaction with non-keyboard input devices. 0224 </description> 0225 </entry> 0226 <entry name="exclusive" value="1"> 0227 <description summary="request exclusive keyboard focus"> 0228 Request exclusive keyboard focus if this surface is above the shell surface layer. 0229 0230 For the top and overlay layers, the seat will always give 0231 exclusive keyboard focus to the top-most layer which has keyboard 0232 interactivity set to exclusive. If this layer contains multiple 0233 surfaces with keyboard interactivity set to exclusive, the compositor 0234 determines the one receiving keyboard events in an implementation- 0235 defined manner. In this case, no guarantee is made when this surface 0236 will receive keyboard focus (if ever). 0237 0238 For the bottom and background layers, the compositor is allowed to use 0239 normal focus semantics. 0240 0241 This setting is mainly intended for applications that need to ensure 0242 they receive all keyboard events, such as a lock screen or a password 0243 prompt. 0244 </description> 0245 </entry> 0246 <entry name="on_demand" value="2" since="4"> 0247 <description summary="request regular keyboard focus semantics"> 0248 This requests the compositor to allow this surface to be focused and 0249 unfocused by the user in an implementation-defined manner. The user 0250 should be able to unfocus this surface even regardless of the layer 0251 it is on. 0252 0253 Typically, the compositor will want to use its normal mechanism to 0254 manage keyboard focus between layer shell surfaces with this setting 0255 and regular toplevels on the desktop layer (e.g. click to focus). 0256 Nevertheless, it is possible for a compositor to require a special 0257 interaction to focus or unfocus layer shell surfaces (e.g. requiring 0258 a click even if focus follows the mouse normally, or providing a 0259 keybinding to switch focus between layers). 0260 0261 This setting is mainly intended for desktop shell components (e.g. 0262 panels) that allow keyboard interaction. Using this option can allow 0263 implementing a desktop shell that can be fully usable without the 0264 mouse. 0265 </description> 0266 </entry> 0267 </enum> 0268 0269 <request name="set_keyboard_interactivity"> 0270 <description summary="requests keyboard events"> 0271 Set how keyboard events are delivered to this surface. By default, 0272 layer shell surfaces do not receive keyboard events; this request can 0273 be used to change this. 0274 0275 This setting is inherited by child surfaces set by the get_popup 0276 request. 0277 0278 Layer surfaces receive pointer, touch, and tablet events normally. If 0279 you do not want to receive them, set the input region on your surface 0280 to an empty region. 0281 0282 Keyboard interactivity is double-buffered, see wl_surface.commit. 0283 </description> 0284 <arg name="keyboard_interactivity" type="uint" enum="keyboard_interactivity"/> 0285 </request> 0286 0287 <request name="get_popup"> 0288 <description summary="assign this layer_surface as an xdg_popup parent"> 0289 This assigns an xdg_popup's parent to this layer_surface. This popup 0290 should have been created via xdg_surface::get_popup with the parent set 0291 to NULL, and this request must be invoked before committing the popup's 0292 initial state. 0293 0294 See the documentation of xdg_popup for more details about what an 0295 xdg_popup is and how it is used. 0296 </description> 0297 <arg name="popup" type="object" interface="xdg_popup"/> 0298 </request> 0299 0300 <request name="ack_configure"> 0301 <description summary="ack a configure event"> 0302 When a configure event is received, if a client commits the 0303 surface in response to the configure event, then the client 0304 must make an ack_configure request sometime before the commit 0305 request, passing along the serial of the configure event. 0306 0307 If the client receives multiple configure events before it 0308 can respond to one, it only has to ack the last configure event. 0309 0310 A client is not required to commit immediately after sending 0311 an ack_configure request - it may even ack_configure several times 0312 before its next surface commit. 0313 0314 A client may send multiple ack_configure requests before committing, but 0315 only the last request sent before a commit indicates which configure 0316 event the client really is responding to. 0317 </description> 0318 <arg name="serial" type="uint" summary="the serial from the configure event"/> 0319 </request> 0320 0321 <request name="destroy" type="destructor"> 0322 <description summary="destroy the layer_surface"> 0323 This request destroys the layer surface. 0324 </description> 0325 </request> 0326 0327 <event name="configure"> 0328 <description summary="suggest a surface change"> 0329 The configure event asks the client to resize its surface. 0330 0331 Clients should arrange their surface for the new states, and then send 0332 an ack_configure request with the serial sent in this configure event at 0333 some point before committing the new surface. 0334 0335 The client is free to dismiss all but the last configure event it 0336 received. 0337 0338 The width and height arguments specify the size of the window in 0339 surface-local coordinates. 0340 0341 The size is a hint, in the sense that the client is free to ignore it if 0342 it doesn't resize, pick a smaller size (to satisfy aspect ratio or 0343 resize in steps of NxM pixels). If the client picks a smaller size and 0344 is anchored to two opposite anchors (e.g. 'top' and 'bottom'), the 0345 surface will be centered on this axis. 0346 0347 If the width or height arguments are zero, it means the client should 0348 decide its own window dimension. 0349 </description> 0350 <arg name="serial" type="uint"/> 0351 <arg name="width" type="uint"/> 0352 <arg name="height" type="uint"/> 0353 </event> 0354 0355 <event name="closed"> 0356 <description summary="surface should be closed"> 0357 The closed event is sent by the compositor when the surface will no 0358 longer be shown. The output may have been destroyed or the user may 0359 have asked for it to be removed. Further changes to the surface will be 0360 ignored. The client should destroy the resource after receiving this 0361 event, and create a new surface if they so choose. 0362 </description> 0363 </event> 0364 0365 <enum name="error"> 0366 <entry name="invalid_surface_state" value="0" summary="provided surface state is invalid"/> 0367 <entry name="invalid_size" value="1" summary="size is invalid"/> 0368 <entry name="invalid_anchor" value="2" summary="anchor bitfield is invalid"/> 0369 <entry name="invalid_keyboard_interactivity" value="3" summary="keyboard interactivity is invalid"/> 0370 </enum> 0371 0372 <enum name="anchor" bitfield="true"> 0373 <entry name="top" value="1" summary="the top edge of the anchor rectangle"/> 0374 <entry name="bottom" value="2" summary="the bottom edge of the anchor rectangle"/> 0375 <entry name="left" value="4" summary="the left edge of the anchor rectangle"/> 0376 <entry name="right" value="8" summary="the right edge of the anchor rectangle"/> 0377 </enum> 0378 0379 <!-- Version 2 additions --> 0380 0381 <request name="set_layer" since="2"> 0382 <description summary="change the layer of the surface"> 0383 Change the layer that the surface is rendered on. 0384 0385 Layer is double-buffered, see wl_surface.commit. 0386 </description> 0387 <arg name="layer" type="uint" enum="zwlr_layer_shell_v1.layer" summary="layer to move this surface to"/> 0388 </request> 0389 </interface> 0390 </protocol>