AtlatestRepositorysigil-wm

sigil-wm / tree / protocolwlr-foreign-toplevel-management-unstable-v1.xml

1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="wlr_foreign_toplevel_management_unstable_v1">
3 <copyright>
4 Copyright © 2018 Ilia Bozhinov
5
6 Permission to use, copy, modify, distribute, and sell this
7 software and its documentation for any purpose is hereby granted
8 without fee, provided that the above copyright notice appear in
9 all copies and that both that copyright notice and this permission
10 notice appear in supporting documentation, and that the name of
11 the copyright holders not be used in advertising or publicity
12 pertaining to distribution of the software without specific,
13 written prior permission. The copyright holders make no
14 representations about the suitability of this software for any
15 purpose. It is provided "as is" without express or implied
16 warranty.
18 THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
19 SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
20 FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
21 SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
22 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
23 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
24 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
25 THIS SOFTWARE.
26 </copyright>
28 <interface name="zwlr_foreign_toplevel_manager_v1" version="3">
29 <description summary="list and control opened apps">
30 The purpose of this protocol is to enable the creation of taskbars
31 and docks by providing them with a list of opened applications and
32 letting them request certain actions on them, like maximizing, etc.
34 After a client binds the zwlr_foreign_toplevel_manager_v1, each opened
35 toplevel window will be sent via the toplevel event
36 </description>
38 <event name="toplevel">
39 <description summary="a toplevel has been created">
40 This event is emitted whenever a new toplevel window is created. It
41 is emitted for all toplevels, regardless of the app that has created
42 them.
44 All initial details of the toplevel(title, app_id, states, etc.) will
45 be sent immediately after this event via the corresponding events in
46 zwlr_foreign_toplevel_handle_v1.
47 </description>
48 <arg name="toplevel" type="new_id" interface="zwlr_foreign_toplevel_handle_v1"/>
49 </event>
51 <request name="stop">
52 <description summary="stop sending events">
53 Indicates the client no longer wishes to receive events for new toplevels.
54 However the compositor may emit further toplevel_created events, until
55 the finished event is emitted.
57 The client must not send any more requests after this one.
58 </description>
59 </request>
61 <event name="finished">
62 <description summary="the compositor has finished with the toplevel manager">
63 This event indicates that the compositor is done sending events to the
64 zwlr_foreign_toplevel_manager_v1. The server will destroy the object
65 immediately after sending this request, so it will become invalid and
66 the client should free any resources associated with it.
67 </description>
68 </event>
69 </interface>
71 <interface name="zwlr_foreign_toplevel_handle_v1" version="3">
72 <description summary="an opened toplevel">
73 A zwlr_foreign_toplevel_handle_v1 object represents an opened toplevel
74 window. Each app may have multiple opened toplevels.
76 Each toplevel has a list of outputs it is visible on, conveyed to the
77 client with the output_enter and output_leave events.
78 </description>
80 <event name="title">
81 <description summary="title change">
82 This event is emitted whenever the title of the toplevel changes.
83 </description>
84 <arg name="title" type="string"/>
85 </event>
87 <event name="app_id">
88 <description summary="app-id change">
89 This event is emitted whenever the app-id of the toplevel changes.
90 </description>
91 <arg name="app_id" type="string"/>
92 </event>
94 <event name="output_enter">
95 <description summary="toplevel entered an output">
96 This event is emitted whenever the toplevel becomes visible on
97 the given output. A toplevel may be visible on multiple outputs.
98 </description>
99 <arg name="output" type="object" interface="wl_output"/>
100 </event>
102 <event name="output_leave">
103 <description summary="toplevel left an output">
104 This event is emitted whenever the toplevel stops being visible on
105 the given output. It is guaranteed that an entered-output event
106 with the same output has been emitted before this event.
107 </description>
108 <arg name="output" type="object" interface="wl_output"/>
109 </event>
111 <request name="set_maximized">
112 <description summary="requests that the toplevel be maximized">
113 Requests that the toplevel be maximized. If the maximized state actually
114 changes, this will be indicated by the state event.
115 </description>
116 </request>
118 <request name="unset_maximized">
119 <description summary="requests that the toplevel be unmaximized">
120 Requests that the toplevel be unmaximized. If the maximized state actually
121 changes, this will be indicated by the state event.
122 </description>
123 </request>
125 <request name="set_minimized">
126 <description summary="requests that the toplevel be minimized">
127 Requests that the toplevel be minimized. If the minimized state actually
128 changes, this will be indicated by the state event.
129 </description>
130 </request>
132 <request name="unset_minimized">
133 <description summary="requests that the toplevel be unminimized">
134 Requests that the toplevel be unminimized. If the minimized state actually
135 changes, this will be indicated by the state event.
136 </description>
137 </request>
139 <request name="activate">
140 <description summary="activate the toplevel">
141 Request that this toplevel be activated on the given seat.
142 There is no guarantee the toplevel will be actually activated.
143 </description>
144 <arg name="seat" type="object" interface="wl_seat"/>
145 </request>
147 <enum name="state">
148 <description summary="types of states on the toplevel">
149 The different states that a toplevel can have. These have the same meaning
150 as the states with the same names defined in xdg-toplevel
151 </description>
153 <entry name="maximized" value="0" summary="the toplevel is maximized"/>
154 <entry name="minimized" value="1" summary="the toplevel is minimized"/>
155 <entry name="activated" value="2" summary="the toplevel is active"/>
156 <entry name="fullscreen" value="3" summary="the toplevel is fullscreen" since="2"/>
157 </enum>
159 <event name="state">
160 <description summary="the toplevel state changed">
161 This event is emitted immediately after the zlw_foreign_toplevel_handle_v1
162 is created and each time the toplevel state changes, either because of a
163 compositor action or because of a request in this protocol.
164 </description>
166 <arg name="state" type="array"/>
167 </event>
169 <event name="done">
170 <description summary="all information about the toplevel has been sent">
171 This event is sent after all changes in the toplevel state have been
172 sent.
174 This allows changes to the zwlr_foreign_toplevel_handle_v1 properties
175 to be seen as atomic, even if they happen via multiple events.
176 </description>
177 </event>
179 <request name="close">
180 <description summary="request that the toplevel be closed">
181 Send a request to the toplevel to close itself. The compositor would
182 typically use a shell-specific method to carry out this request, for
183 example by sending the xdg_toplevel.close event. However, this gives
184 no guarantees the toplevel will actually be destroyed. If and when
185 this happens, the zwlr_foreign_toplevel_handle_v1.closed event will
186 be emitted.
187 </description>
188 </request>
190 <request name="set_rectangle">
191 <description summary="the rectangle which represents the toplevel">
192 The rectangle of the surface specified in this request corresponds to
193 the place where the app using this protocol represents the given toplevel.
194 It can be used by the compositor as a hint for some operations, e.g
195 minimizing. The client is however not required to set this, in which
196 case the compositor is free to decide some default value.
198 If the client specifies more than one rectangle, only the last one is
199 considered.
201 The dimensions are given in surface-local coordinates.
202 Setting width=height=0 removes the already-set rectangle.
203 </description>
205 <arg name="surface" type="object" interface="wl_surface"/>
206 <arg name="x" type="int"/>
207 <arg name="y" type="int"/>
208 <arg name="width" type="int"/>
209 <arg name="height" type="int"/>
210 </request>
212 <enum name="error">
213 <entry name="invalid_rectangle" value="0"
214 summary="the provided rectangle is invalid"/>
215 </enum>
217 <event name="closed">
218 <description summary="this toplevel has been destroyed">
219 This event means the toplevel has been destroyed. It is guaranteed there
220 won't be any more events for this zwlr_foreign_toplevel_handle_v1. The
221 toplevel itself becomes inert so any requests will be ignored except the
222 destroy request.
223 </description>
224 </event>
226 <request name="destroy" type="destructor">
227 <description summary="destroy the zwlr_foreign_toplevel_handle_v1 object">
228 Destroys the zwlr_foreign_toplevel_handle_v1 object.
230 This request should be called either when the client does not want to
231 use the toplevel anymore or after the closed event to finalize the
232 destruction of the object.
233 </description>
234 </request>
236 <!-- Version 2 additions -->
238 <request name="set_fullscreen" since="2">
239 <description summary="request that the toplevel be fullscreened">
240 Requests that the toplevel be fullscreened on the given output. If the
241 fullscreen state and/or the outputs the toplevel is visible on actually
242 change, this will be indicated by the state and output_enter/leave
243 events.
245 The output parameter is only a hint to the compositor. Also, if output
246 is NULL, the compositor should decide which output the toplevel will be
247 fullscreened on, if at all.
248 </description>
249 <arg name="output" type="object" interface="wl_output" allow-null="true"/>
250 </request>
252 <request name="unset_fullscreen" since="2">
253 <description summary="request that the toplevel be unfullscreened">
254 Requests that the toplevel be unfullscreened. If the fullscreen state
255 actually changes, this will be indicated by the state event.
256 </description>
257 </request>
259 <!-- Version 3 additions -->
261 <event name="parent" since="3">
262 <description summary="parent change">
263 This event is emitted whenever the parent of the toplevel changes.
265 No event is emitted when the parent handle is destroyed by the client.
266 </description>
267 <arg name="parent" type="object" interface="zwlr_foreign_toplevel_handle_v1" allow-null="true"/>
268 </event>
269 </interface>
270</protocol>