| 1 |
<?xml version="1.0" encoding="UTF-8"?> |
| 2 |
<protocol name="xdg_decoration_unstable_v1"> |
| 3 |
<copyright> |
| 4 |
Copyright © 2018 Simon Ser |
| 5 |
|
| 6 |
Permission is hereby granted, free of charge, to any person obtaining a |
| 7 |
copy of this software and associated documentation files (the "Software"), |
| 8 |
to deal in the Software without restriction, including without limitation |
| 9 |
the rights to use, copy, modify, merge, publish, distribute, sublicense, |
| 10 |
and/or sell copies of the Software, and to permit persons to whom the |
| 11 |
Software is furnished to do so, subject to the following conditions: |
| 12 |
|
| 13 |
The above copyright notice and this permission notice (including the next |
| 14 |
paragraph) shall be included in all copies or substantial portions of the |
| 15 |
Software. |
| 16 |
|
| 17 |
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 18 |
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 19 |
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL |
| 20 |
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 21 |
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
| 22 |
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
| 23 |
DEALINGS IN THE SOFTWARE. |
| 24 |
</copyright> |
| 25 |
|
| 26 |
<interface name="zxdg_decoration_manager_v1" version="2"> |
| 27 |
<description summary="window decoration manager"> |
| 28 |
This interface allows a compositor to announce support for server-side |
| 29 |
decorations. |
| 30 |
|
| 31 |
A window decoration is a set of window controls as deemed appropriate by |
| 32 |
the party managing them, such as user interface components used to move, |
| 33 |
resize and change a window's state. |
| 34 |
|
| 35 |
A client can use this protocol to request being decorated by a supporting |
| 36 |
compositor. |
| 37 |
|
| 38 |
If compositor and client do not negotiate the use of a server-side |
| 39 |
decoration using this protocol, clients continue to self-decorate as they |
| 40 |
see fit. |
| 41 |
|
| 42 |
Warning! The protocol described in this file is experimental and |
| 43 |
backward incompatible changes may be made. Backward compatible changes |
| 44 |
may be added together with the corresponding interface version bump. |
| 45 |
Backward incompatible changes are done by bumping the version number in |
| 46 |
the protocol and interface names and resetting the interface version. |
| 47 |
Once the protocol is to be declared stable, the 'z' prefix and the |
| 48 |
version number in the protocol and interface names are removed and the |
| 49 |
interface version number is reset. |
| 50 |
</description> |
| 51 |
|
| 52 |
<request name="destroy" type="destructor"> |
| 53 |
<description summary="destroy the decoration manager object"> |
| 54 |
Destroy the decoration manager. This doesn't destroy objects created |
| 55 |
with the manager. |
| 56 |
</description> |
| 57 |
</request> |
| 58 |
|
| 59 |
<request name="get_toplevel_decoration"> |
| 60 |
<description summary="create a new toplevel decoration object"> |
| 61 |
Create a new decoration object associated with the given toplevel. |
| 62 |
|
| 63 |
For objects of version 1, creating an xdg_toplevel_decoration from an |
| 64 |
xdg_toplevel which has a buffer attached or committed is a client |
| 65 |
error, and any attempts by a client to attach or manipulate a buffer |
| 66 |
prior to the first xdg_toplevel_decoration.configure event must also be |
| 67 |
treated as errors. |
| 68 |
|
| 69 |
For objects of version 2 or newer, creating an xdg_toplevel_decoration |
| 70 |
from an xdg_toplevel which has a buffer attached or committed is |
| 71 |
allowed. The initial decoration mode of the surface if a buffer is |
| 72 |
already attached depends on whether a xdg_toplevel_decoration object |
| 73 |
has been associated with the surface or not prior to this request. |
| 74 |
|
| 75 |
If an xdg_toplevel_decoration was associated with the surface, then |
| 76 |
destroyed without a surface commit, the previous decoration mode is |
| 77 |
retained. |
| 78 |
|
| 79 |
If no xdg_toplevel_decoration was associated with the surface prior to |
| 80 |
this request, or if a surface commit has been performed after a previous |
| 81 |
xdg_toplevel_decoration object associated with the surface was |
| 82 |
destroyed, the decoration mode is assumed to be client-side. |
| 83 |
</description> |
| 84 |
<arg name="id" type="new_id" interface="zxdg_toplevel_decoration_v1"/> |
| 85 |
<arg name="toplevel" type="object" interface="xdg_toplevel"/> |
| 86 |
</request> |
| 87 |
</interface> |
| 88 |
|
| 89 |
<interface name="zxdg_toplevel_decoration_v1" version="2"> |
| 90 |
<description summary="decoration object for a toplevel surface"> |
| 91 |
The decoration object allows the compositor to toggle server-side window |
| 92 |
decorations for a toplevel surface. The client can request to switch to |
| 93 |
another mode. |
| 94 |
|
| 95 |
The xdg_toplevel_decoration object must be destroyed before its |
| 96 |
xdg_toplevel. |
| 97 |
</description> |
| 98 |
|
| 99 |
<enum name="error"> |
| 100 |
<entry name="unconfigured_buffer" value="0" |
| 101 |
summary="xdg_toplevel has a buffer attached before configure"/> |
| 102 |
<entry name="already_constructed" value="1" |
| 103 |
summary="xdg_toplevel already has a decoration object"/> |
| 104 |
<entry name="orphaned" value="2" |
| 105 |
summary="xdg_toplevel destroyed before the decoration object"/> |
| 106 |
<entry name="invalid_mode" value="3" summary="invalid mode"/> |
| 107 |
</enum> |
| 108 |
|
| 109 |
<request name="destroy" type="destructor"> |
| 110 |
<description summary="destroy the decoration object"> |
| 111 |
Switch back to a mode without any server-side decorations at the next |
| 112 |
commit, unless a new xdg_toplevel_decoration is created for the surface |
| 113 |
first. |
| 114 |
</description> |
| 115 |
</request> |
| 116 |
|
| 117 |
<enum name="mode"> |
| 118 |
<description summary="window decoration modes"> |
| 119 |
These values describe window decoration modes. |
| 120 |
</description> |
| 121 |
<entry name="client_side" value="1" |
| 122 |
summary="no server-side window decoration"/> |
| 123 |
<entry name="server_side" value="2" |
| 124 |
summary="server-side window decoration"/> |
| 125 |
</enum> |
| 126 |
|
| 127 |
<request name="set_mode"> |
| 128 |
<description summary="set the decoration mode"> |
| 129 |
Set the toplevel surface decoration mode. This informs the compositor |
| 130 |
that the client prefers the provided decoration mode. |
| 131 |
|
| 132 |
After requesting a decoration mode, the compositor will respond by |
| 133 |
emitting an xdg_surface.configure event. The client should then update |
| 134 |
its content, drawing it without decorations if the received mode is |
| 135 |
server-side decorations. The client must also acknowledge the configure |
| 136 |
when committing the new content (see xdg_surface.ack_configure). |
| 137 |
|
| 138 |
The compositor can decide not to use the client's mode and enforce a |
| 139 |
different mode instead. |
| 140 |
|
| 141 |
Clients whose decoration mode depend on the xdg_toplevel state may send |
| 142 |
a set_mode request in response to an xdg_surface.configure event and wait |
| 143 |
for the next xdg_surface.configure event to prevent unwanted state. |
| 144 |
Such clients are responsible for preventing configure loops and must |
| 145 |
make sure not to send multiple successive set_mode requests with the |
| 146 |
same decoration mode. |
| 147 |
|
| 148 |
If an invalid mode is supplied by the client, the invalid_mode protocol |
| 149 |
error is raised by the compositor. |
| 150 |
</description> |
| 151 |
<arg name="mode" type="uint" enum="mode" summary="the decoration mode"/> |
| 152 |
</request> |
| 153 |
|
| 154 |
<request name="unset_mode"> |
| 155 |
<description summary="unset the decoration mode"> |
| 156 |
Unset the toplevel surface decoration mode. This informs the compositor |
| 157 |
that the client doesn't prefer a particular decoration mode. |
| 158 |
|
| 159 |
This request has the same semantics as set_mode. |
| 160 |
</description> |
| 161 |
</request> |
| 162 |
|
| 163 |
<event name="configure"> |
| 164 |
<description summary="notify a decoration mode change"> |
| 165 |
The configure event configures the effective decoration mode. The |
| 166 |
configured state should not be applied immediately. Clients must send an |
| 167 |
ack_configure in response to this event. See xdg_surface.configure and |
| 168 |
xdg_surface.ack_configure for details. |
| 169 |
|
| 170 |
A configure event can be sent at any time. The specified mode must be |
| 171 |
obeyed by the client. |
| 172 |
</description> |
| 173 |
<arg name="mode" type="uint" enum="mode" summary="the decoration mode"/> |
| 174 |
</event> |
| 175 |
</interface> |
| 176 |
</protocol> |