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>