-
-
Notifications
You must be signed in to change notification settings - Fork 164
Expand file tree
/
Copy pathriver-window-management-v1.xml
More file actions
1859 lines (1492 loc) · 80.9 KB
/
river-window-management-v1.xml
File metadata and controls
1859 lines (1492 loc) · 80.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="river_window_management_v1">
<copyright>
SPDX-FileCopyrightText: © 2024 Isaac Freund
SPDX-License-Identifier: MIT
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.
</copyright>
<description summary="frame-perfect window management">
This protocol allows a single "window manager" client to determine the
window management policy of the compositor. State is globally
double-buffered allowing for frame perfect state changes involving multiple
windows.
The key words "must", "must not", "required", "shall", "shall not",
"should", "should not", "recommended", "may", and "optional" in this
document are to be interpreted as described in IETF RFC 2119.
</description>
<interface name="river_window_manager_v1" version="4">
<description summary="window manager global interface">
This global interface should only be advertised to the window manager
process. Only one window management client may be active at a time. The
compositor should use the unavailable event if necessary to enforce this.
There are two disjoint categories of state managed by this protocol:
Window management state influences the communication between the
compositor and individual windows (e.g. xdg_toplevels). Window management
state includes window dimensions, fullscreen state, keyboard focus,
keyboard bindings, and more.
Rendering state only affects the rendered output of the compositor and
does not influence communication between the compositor and individual
windows. Rendering state includes the position and rendering order of
windows, shell surfaces, decoration surfaces, borders, and more.
Window management state may only be modified by the window manager as part
of a manage sequence. A manage sequence is started with the manage_start
event and ended with the manage_finish request. It is a protocol error to
modify window management state outside of a manage sequence.
A manage sequence is always followed by at least one render sequence. A
render sequence is started with the render_start event and ended with the
render_finish request.
Rendering state may be modified by the window manager during a manage
sequence or a render sequence. Regardless of when the rendering state is
modified, it is applied with the next render_finish request. It is a
protocol error to modify rendering state outside of a manage or render
sequence.
The server will start a manage sequence by sending new state and the
manage_start event as soon as possible whenever there is a change in state
that must be communicated with the window manager.
If the window manager client needs to ensure a manage sequence is started
due to a state change the compositor is not aware of, it may send the
manage_dirty request.
The server will start a render sequence by sending new state and the
render_start event as soon as possible whenever there is a change in
window dimensions that must be communicated with the window manager.
Multiple render sequences may be made consecutively without a manage
sequence in between, for example if a window independently changes its own
dimensions.
To summarize, the main loop of this protocol is as follows:
1. The server sends events indicating all changes since the last
manage sequence followed by the manage_start event.
2. The client sends requests modifying window management state or
rendering state (as defined above) followed by the manage_finish
request.
3. The server sends new state to windows and waits for responses.
4. The server sends new window dimensions to the client followed by the
render_start event.
5. The client sends requests modifying rendering state (as defined above)
followed by the render_finish request.
6. If window dimensions change, loop back to step 4.
If state that requires a manage sequence changes or if the client makes
a manage_dirty request, loop back to step 1.
For the purposes of frame perfection, the server may delay rendering new
state committed by the windows in step 3 until after step 5 is finished.
It is a protocol error for the client to make a manage_finish or
render_finish request that violates this ordering.
</description>
<enum name="error">
<entry name="sequence_order" value="0"
summary="request violates manage/render sequence ordering"/>
<entry name="role" value="1"
summary="given wl_surface already has a role"/>
<entry name="unresponsive" value="2"
summary="window manager unresponsive"/>
</enum>
<event name="unavailable">
<description summary="window management unavailable">
This event indicates that window management is not available to the
client, perhaps due to another window management client already running.
The circumstances causing this event to be sent are compositor policy.
If sent, this event is guaranteed to be the first and only event sent by
the server.
The server will send no further events on this object. The client should
destroy this object and all objects created through this interface.
</description>
</event>
<request name="stop">
<description summary="stop sending events">
This request indicates that the client no longer wishes to receive
events on this object.
The Wayland protocol is asynchronous, which means the server may send
further events until the stop request is processed. The client must wait
for a river_window_manager_v1.finished event before destroying this
object.
</description>
</request>
<event name="finished">
<description summary="the server has finished with the window manager">
This event indicates that the server will send no further events on this
object. The client should destroy the object. See
river_window_manager_v1.destroy for more information.
</description>
</event>
<request name="destroy" type="destructor">
<description summary="destroy the river_window_manager_v1 object">
This request should be called after the finished event has been received
to complete destruction of the object.
If a client wishes to destroy this object it should send a
river_window_manager_v1.stop request and wait for a
river_window_manager_v1.finished event. Once the finished event is
received it is safe to destroy this object and any other objects created
through this interface.
</description>
</request>
<event name="manage_start">
<description summary="start a manage sequence">
This event indicates that the server has sent events indicating all
state changes since the last manage sequence.
In response to this event, the client should make requests modifying
window management state as it chooses. Then, the client must make the
manage_finish request.
See the description of the river_window_manager_v1 interface for a
complete overview of the manage/render sequence loop.
</description>
</event>
<request name="manage_finish">
<description summary="finish a manage sequence">
This request indicates that the client has made all changes to window
management state it wishes to include in the current manage sequence and
that the server should atomically send these state changes to the
windows and continue with the manage sequence.
After sending this request, it is a protocol error for the client to
make further changes to window management state until the next
manage_start event is received.
See the description of the river_window_manager_v1 interface for a
complete overview of the manage/render sequence loop.
</description>
</request>
<request name="manage_dirty">
<description summary="ensure a manage sequence is started">
This request ensures a manage sequence is started and that a
manage_start event is sent by the server. If this request is made during
an ongoing manage sequence, a new manage sequence will be started as
soon as the current one is completed.
The client may want to use this request due to an internal state change
that the compositor is not aware of (e.g. a dbus event) which should
affect window management or rendering state.
</description>
</request>
<event name="render_start">
<description summary="start a render sequence">
This event indicates that the server has sent all
river_window_v1.dimensions events necessary.
In response to this event, the client should make requests modifying
rendering state as it chooses. Then, the client must make the
render_finish request.
See the description of the river_window_manager_v1 interface for a
complete overview of the manage/render sequence loop.
</description>
</event>
<request name="render_finish">
<description summary="finish a render sequence">
This request indicates that the client has made all changes to rendering
state it wishes to include in the current manage sequence and that the
server should atomically apply and display these state changes to the
user.
After sending this request, it is a protocol error for the client to
make further changes to rendering state until the next manage_start or
render_start event is received, whichever comes first.
See the description of the river_window_manager_v1 interface for a
complete overview of the manage/render sequence loop.
</description>
</request>
<event name="session_locked">
<description summary="the session has been locked">
This event indicates that the session has been locked.
The window manager may wish to restrict which key bindings are available
while locked or otherwise use this information.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
</event>
<event name="session_unlocked">
<description summary="the session has been unlocked">
This event indicates that the session has been unlocked.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
</event>
<event name="window">
<description summary="new window">
A new window has been created.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
<arg name="id" type="new_id" interface="river_window_v1" summary="new window"/>
</event>
<event name="output">
<description summary="new output">
A new logical output has been created, perhaps due to a new physical
monitor being plugged in or perhaps due to a change in configuration.
This event will be followed by river_output_v1.position and dimensions
events as well as a manage_start event after all other new state has
been sent by the server.
</description>
<arg name="id" type="new_id" interface="river_output_v1" summary="new output"/>
</event>
<event name="seat">
<description summary="new seat">
A new seat has been created.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
<arg name="id" type="new_id" interface="river_seat_v1" summary="new seat"/>
</event>
<request name="get_shell_surface">
<description summary="assign the river_shell_surface_v1 surface role">
Create a new shell surface for window manager UI and assign the
river_shell_surface_v1 role to the surface.
Providing a wl_surface which already has a role or already has a buffer
attached or committed is a protocol error.
</description>
<arg name="id" type="new_id" interface="river_shell_surface_v1"
summary="new river shell surface"/>
<arg name="surface" type="object" interface="wl_surface"
summary="base surface"/>
</request>
<request name="exit_session" since="4">
<description summary="exit the Wayland session">
End the current Wayland session and exit the compositor.
All Wayland clients running in the current session, including
the window manager, will be disconnected.
Window managers should only make this request if the user explicitly
asks to exit the Wayland session, not for example on normal window
manager termination.
</description>
</request>
</interface>
<interface name="river_window_v1" version="4">
<description summary="a logical window">
This represents a logical window. For example, a window may correspond to
an xdg_toplevel or Xwayland window.
A newly created window will not be displayed until the window manager
makes a propose_dimensions or fullscreen request as part of a manage
sequence, the server replies with a dimensions event as part of a render
sequence, and that render sequence is finished.
</description>
<enum name="error">
<entry name="node_exists" value="0"
summary="window already has a node object"/>
<entry name="invalid_dimensions" value="1"
summary="proposed dimensions out of bounds"/>
<entry name="invalid_border" value="2"
summary="invalid arg to set_borders"/>
<entry name="invalid_clip_box" value="3"
summary="invalid arg to set_clip_box"/>
</enum>
<request name="destroy" type="destructor">
<description summary="destroy the window object">
This request indicates that the client will no longer use the window
object and that it may be safely destroyed.
This request should be made after the river_window_v1.closed event or
river_window_manager_v1.finished is received to complete destruction of
the window.
</description>
</request>
<event name="closed">
<description summary="the window has been closed">
The window has been closed by the server, perhaps due to an
xdg_toplevel.close request or similar.
The server will send no further events on this object and ignore any
request other than river_window_v1.destroy made after this event is
sent. The client should destroy this object with the
river_window_v1.destroy request to free up resources.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
</event>
<request name="close">
<description summary="request that the window be closed">
Request that the window be closed. The window may ignore this request or
only close after some delay, perhaps opening a dialog asking the user to
save their work or similar.
The server will send a river_window_v1.closed event if/when the window
has been closed.
This request modifies window management state and may only be made as
part of a manage sequence, see the river_window_manager_v1 description.
</description>
</request>
<request name="get_node">
<description summary="get the window's render list node">
Get the node in the render list corresponding to the window.
It is a protocol error to make this request more than once for a single
window.
</description>
<arg name="id" type="new_id" interface="river_node_v1" summary="new node"/>
</request>
<event name="dimensions_hint">
<description summary="the window's preferred min/max dimensions">
This event informs the window manager of the window's preferred min/max
dimensions. These preferences are a hint, and the window manager is free
to propose dimensions outside of these bounds.
All min/max width/height values must be strictly greater than or equal
to 0. A value of 0 indicates that the window has no preference for that
value.
The min_width/min_height must be strictly less than or equal to the
max_width/max_height.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
<arg name="min_width" type="int" summary="minimum width"/>
<arg name="min_height" type="int" summary="minimum height"/>
<arg name="max_width" type="int" summary="maximum width"/>
<arg name="max_height" type="int" summary="maximum height"/>
</event>
<event name="dimensions">
<description summary="window dimensions">
This event indicates the dimensions of the window in the compositor's
logical coordinate space. The width and height must be strictly greater
than zero.
Note that the dimensions of a river_window_v1 refer to the dimensions of
the window content and are unaffected by the presence of borders or
decoration surfaces.
This event is sent as part of a render sequence before the render_start
event.
It may be sent due to a propose_dimensions or fullscreen request in a
previous manage sequence or because a window independently decides to
change its dimensions.
The window will not be displayed until the first dimensions event is
received and the render sequence is finished.
</description>
<arg name="width" type="int" summary="window content width"/>
<arg name="height" type="int" summary="window content height"/>
</event>
<request name="propose_dimensions">
<description summary="propose window dimensions">
This request proposes dimensions for the window in the compositor's
logical coordinate space.
The width and height must be greater than or equal to zero. If the width
or height is zero the window will be allowed to decide its own
dimensions.
The window may not take the exact dimensions proposed. The actual
dimensions taken by the window will be sent in a subsequent
river_window_v1.dimensions event. For example, a terminal emulator may
only allow dimensions that are multiple of the cell size.
When a propose_dimensions request is made, the server must send a
dimensions event in response as soon as possible. It may not be possible
to send a dimensions event in the very next render sequence if, for
example, the window takes too long to respond to the proposed
dimensions. In this case, the server will send the dimensions event in a
future render sequence.
Note that the dimensions of a river_window_v1 refer to the dimensions of
the window content and are unaffected by the presence of borders or
decoration surfaces.
This request modifies window management state and may only be made as
part of a manage sequence, see the river_window_manager_v1 description.
</description>
<arg name="width" type="int" summary="proposed content width"/>
<arg name="height" type="int" summary="proposed content height"/>
</request>
<request name="hide">
<description summary="request that the window be hidden">
Request that the window be hidden. Has no effect if the window is
already hidden. Hides any window borders and decorations as well.
Newly created windows are considered shown unless explicitly hidden with
the hide request.
This request modifies rendering state and may only be made as part of a
render sequence, see the river_window_manager_v1 description.
</description>
</request>
<request name="show">
<description summary="request that the window be shown">
Request that the window be shown. Has no effect if the window is not
hidden. Does not guarantee that the window is visible as it may be
completely obscured by other windows placed above it for example.
Newly created windows are considered shown unless explicitly hidden with
the hide request.
This request modifies rendering state and may only be made as part of a
render sequence, see the river_window_manager_v1 description.
</description>
</request>
<event name="app_id">
<description summary="the window set an application ID">
The window set an application ID.
The app_id argument will be null if the window has never set an
application ID or if the window cleared its application ID. (Xwayland
windows may do this for example, though xdg-toplevels may not.)
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
<arg name="app_id" type="string" allow-null="true"
summary="window application ID"/>
</event>
<event name="title">
<description summary="the window set a title">
The window set a title.
The title argument will be null if the window has never set a title or
if the window cleared its title. (Xwayland windows may do this for
example, though xdg-toplevels may not.)
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
<arg name="title" type="string" allow-null="true" summary="window title"/>
</event>
<event name="parent">
<description summary="the window set a parent">
The window set a parent window. If this event is never received or if
the parent argument is null then the window has no parent.
A surface with a parent set might be a dialog, file picker, or similar
for the parent window.
Child windows should generally be rendered directly above their parent.
The compositor must guarantee that there are no loops in the window
tree: a parent must not be the descendant of one of its children.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
<arg name="parent" type="object" allow-null="true"
interface="river_window_v1" summary="parent window, if any"/>
</event>
<enum name="decoration_hint">
<entry name="only_supports_csd" value="0"
summary="only supports client side decoration"/>
<entry name="prefers_csd" value="1"
summary="client side decoration preferred, both CSD and SSD supported"/>
<entry name="prefers_ssd" value="2"
summary="server side decoration preferred, both CSD and SSD supported"/>
<entry name="no_preference" value="3"
summary="no preference, both CSD and SSD supported"/>
</enum>
<event name="decoration_hint">
<description summary="supported/preferred decoration style">
Information from the window about the supported and preferred client
side/server side decoration options.
This event may be sent multiple times over the lifetime of the window if
the window changes its preferences.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
<arg name="hint" type="uint" enum="decoration_hint" summary="decoration hint"/>
</event>
<request name="use_csd">
<description summary="tell the client to use CSD">
Tell the client to use client side decoration and draw its own title
bar, borders, etc.
This is the default if neither this request nor the use_ssd request is
ever made.
This request modifies window management state and may only be made as
part of a manage sequence, see the river_window_manager_v1 description.
</description>
</request>
<request name="use_ssd">
<description summary="tell the client to use SSD">
Tell the client to use server side decoration and not draw any client
side decorations.
This request will have no effect if the client only supports client side
decoration, see the decoration_hint event.
This request modifies window management state and may only be made as
part of a manage sequence, see the river_window_manager_v1 description.
</description>
</request>
<enum name="edges" bitfield="true">
<entry name="none" value="0"/>
<entry name="top" value="1"/>
<entry name="bottom" value="2"/>
<entry name="left" value="4"/>
<entry name="right" value="8"/>
</enum>
<request name="set_borders">
<description summary="set window borders">
This request decorates the window with borders drawn by the compositor
on the specified edges of the window. Borders are drawn above the window
content.
Corners are drawn only between borders on adjacent edges. If e.g. the
left edge has a border and the top edge does not, the border drawn on
the left edge will not extend vertically beyond the top edge of the
window.
Borders are not drawn while the window is fullscreen.
The color is defined by four 32-bit RGBA values. Unless specified in
another protocol extension, the RGBA values use pre-multiplied alpha.
The valid range for the RGBA values is from 0x00000000 to 0xffffffff.
These values are interpreted as a percentage:
- 0x00000000 means 0% of the given color component
- 0xffffffff means 100% of the given color component
Setting the edges to none or the width to 0 disables the borders.
Setting a negative width is a protocol error.
This request completely overrides all previous set_borders requests.
Only the most recent set_borders request has an effect.
Note that the position/dimensions of a river_window_v1 refer to the
position/dimensions of the window content and are unaffected by the
presence of borders or decoration surfaces.
This request modifies rendering state and may only be made as part of a
render sequence, see the river_window_manager_v1 description.
</description>
<arg name="edges" type="uint" enum="edges" summary="border edges"/>
<arg name="width" type="int" summary="border width"/>
<arg name="r" type="uint" summary="32-bit red value"/>
<arg name="g" type="uint" summary="32-bit green value"/>
<arg name="b" type="uint" summary="32-bit blue value"/>
<arg name="a" type="uint" summary="32-bit alpha value"/>
</request>
<request name="set_tiled">
<description summary="set window tiled state">
Inform the window that it is part of a tiled layout and adjacent to
other elements in the tiled layout on the given edges.
The window should use this information to change the style of its client
side decorations and avoid drawing e.g. drop shadows outside of the
window dimensions on the tiled edges.
Setting the edges argument to none informs the window that it is not
part of a tiled layout. If this request is never made, the window is
informed that it is not part of a tiled layout.
This request modifies window management state and may only be made as
part of a manage sequence, see the river_window_manager_v1 description.
</description>
<arg name="edges" type="uint" enum="edges" summary="tiled edges"/>
</request>
<request name="get_decoration_above">
<description summary="create a decoration above the window in z-order">
Create a decoration surface and assign the river_decoration_v1 role to
the surface. The created decoration is placed above the window in
rendering order, see the description of river_decoration_v1.
Providing a wl_surface which already has a role or already has a buffer
attached or committed is a protocol error.
</description>
<arg name="id" type="new_id" interface="river_decoration_v1"
summary="new decoration surface"/>
<arg name="surface" type="object" interface="wl_surface"
summary="base surface"/>
</request>
<request name="get_decoration_below">
<description summary="create a decoration below the window in z-order">
Create a decoration surface and assign the river_decoration_v1 role to
the surface. The created decoration is placed below the window in
rendering order, see the description of river_decoration_v1.
Providing a wl_surface which already has a role or already has a buffer
attached or committed is a protocol error.
</description>
<arg name="id" type="new_id" interface="river_decoration_v1"
summary="new decoration surface"/>
<arg name="surface" type="object" interface="wl_surface"
summary="base surface"/>
</request>
<event name="pointer_move_requested">
<description summary="window requested interactive pointer move">
This event informs the window manager that the window has requested to
be interactively moved using the pointer. The seat argument indicates the
seat for the move.
The xdg-shell protocol for example allows windows to request that an
interactive move be started, perhaps when a client-side rendered
titlebar is dragged.
The window manager may use the river_seat_v1.op_start_pointer request to
interactively move the window or ignore this event entirely.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
<arg name="seat" type="object" interface="river_seat_v1"
summary="requested seat"/>
</event>
<event name="pointer_resize_requested">
<description summary="window requested interactive pointer resize">
This event informs the window manager that the window has requested to
be interactively resized using the pointer. The seat argument indicates
the seat for the resize.
The edges argument indicates which edges the window has requested to be
resized from. The edges argument will never be none and will never have
both top and bottom or both left and right edges set.
The xdg-shell protocol for example allows windows to request that an
interactive resize be started, perhaps when the corner of client-side
rendered decorations is dragged.
The window manager may use the river_seat_v1.op_start_pointer request to
interactively resize the window or ignore this event entirely.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
<arg name="seat" type="object" interface="river_seat_v1"
summary="requested seat"/>
<arg name="edges" type="uint" enum="edges"
summary="requested edges"/>
</event>
<request name="inform_resize_start">
<description summary="inform the window it is being resized">
Inform the window that it is being resized. The window manager should
use this request to inform windows that are the target of an interactive
resize for example.
The window manager remains responsible for handling the position and
dimensions of the window while it is resizing.
This request modifies window management state and may only be made as
part of a manage sequence, see the river_window_manager_v1 description.
</description>
</request>
<request name="inform_resize_end">
<description summary="inform the window it no longer being resized">
Inform the window that it is no longer being resized. The window manager
should use this request to inform windows that are the target of an
interactive resize that the interactive resize has ended for example.
This request modifies window management state and may only be made as
part of a manage sequence, see the river_window_manager_v1 description.
</description>
</request>
<enum name="capabilities" bitfield="true">
<entry name="window_menu" value="1"/>
<entry name="maximize" value="2"/>
<entry name="fullscreen" value="4"/>
<entry name="minimize" value="8"/>
</enum>
<request name="set_capabilities">
<description summary="inform window of supported capabilities">
This request informs the window of the capabilities supported by the
window manager. If the window manager, for example, ignores requests to
be maximized from the window it should not tell the window that it
supports the maximize capability.
The window might use this information to, for example, only show a
maximize button if the window manager supports the maximize capability.
The window manager client should use this request to set capabilities
for all new windows. If this request is never made, the compositor will
inform windows that all capabilities are supported.
This request modifies window management state and may only be made as
part of a manage sequence, see the river_window_manager_v1 description.
</description>
<arg name="caps" type="uint" enum="capabilities"
summary="supported capabilities"/>
</request>
<event name="show_window_menu_requested">
<description summary="window requested that the window menu be shown">
The xdg-shell protocol for example allows windows to request that a
window menu be shown, for example when the user right clicks on client
side window decorations.
A window menu might include options to maximize or minimize the window.
The window manager is free to ignore this request and decide what the
window menu contains if it does choose to show one.
The x and y arguments indicate where the window requested that the
window menu be shown.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
<arg name="x" type="int" summary="x offset from top left corner"/>
<arg name="y" type="int" summary="y offset from top left corner"/>
</event>
<event name="maximize_requested">
<description summary="the window requested to be maximized">
The xdg-shell protocol for example allows windows to request to be
maximized.
The window manager is free to honor this request using
river_window_v1.inform_maximized or ignore it.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
</event>
<event name="unmaximize_requested">
<description summary="the window requested to be unmaximized">
The xdg-shell protocol for example allows windows to request to be
unmaximized.
The window manager is free to honor this request using
river_window_v1.inform_unmaximized or ignore it.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
</event>
<request name="inform_maximized">
<description summary="inform the window that it is maximized">
Inform the window that it is maximized. The window might use this
information to adapt the style of its client-side window decorations for
example.
The window manager remains responsible for handling the position and
dimensions of the window while it is maximized.
This request modifies window management state and may only be made as
part of a manage sequence, see the river_window_manager_v1 description.
</description>
</request>
<request name="inform_unmaximized">
<description summary="inform the window that it is unmaximized">
Inform the window that it is unmaximized. The window might use this
information to adapt the style of its client-side window decorations for
example.
This request modifies window management state and may only be made as
part of a manage sequence, see the river_window_manager_v1 description.
</description>
</request>
<event name="fullscreen_requested">
<description summary="the window requested to be fullscreen">
The xdg-shell protocol for example allows windows to request that they
be made fullscreen and allows them to provide an optional output hint.
If the output argument is null, the window has no preference and the
window manager should choose an output.
The window manager is free to honor this request using
river_window_v1.fullscreen or ignore it.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
<arg name="output" type="object" allow-null="true"
interface="river_output_v1" summary="fullscreen output requested"/>
</event>
<event name="exit_fullscreen_requested">
<description summary="the window requested to exit fullscreen">
The xdg-shell protocol for example allows windows to request to exit
fullscreen.
The window manager is free to honor this request using
river_window_v1.exit_fullscreen or ignore it.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
</event>
<request name="inform_fullscreen">
<description summary="inform the window that it is fullscreen">
Inform the window that it is fullscreen. The window might use this
information to adapt the style of its client-side window decorations for
example.
This request does not affect the size/position of the window or cause it
to become the only window rendered, see the river_window_v1.fullscreen
and exit_fullscreen requests for that.
This request modifies window management state and may only be made as
part of a manage sequence, see the river_window_manager_v1 description.
</description>
</request>
<request name="inform_not_fullscreen">
<description summary="inform the window that it is not fullscreen">
Inform the window that it is not fullscreen. The window might use this
information to adapt the style of its client-side window decorations for
example.
This request does not affect the size/position of the window or cause it
to become the only window rendered, see the river_window_v1.fullscreen
and exit_fullscreen requests for that.
This request modifies window management state and may only be made as
part of a manage sequence, see the river_window_manager_v1 description.
</description>
</request>
<request name="fullscreen">
<description summary="make the window fullscreen">
Make the window fullscreen on the given output. If multiple windows are
fullscreen on the same output at the same time only the "top" window in
rendering order shall be displayed.
All river_shell_surface_v1 objects above the top fullscreen window in
the rendering order will continue to be rendered.
The compositor will handle the position and dimensions of the window
while it is fullscreen. The set_position and propose_dimensions requests
shall not affect the current position and dimensions of a fullscreen
window.
When a fullscreen request is made, the server must send a dimensions
event in response as soon as possible. It may not be possible to send a
dimensions event in the very next render sequence if, for example, the
window takes too long to respond. In this case, the server will send the
dimensions event in a future render sequence.
The compositor will clip window content, decoration surfaces, and
borders to the given output's dimensions while the window is fullscreen.
The effects of set_clip_box and set_content_clip_box are ignored while
the window is fullscreen.
If the output on which a window is currently fullscreen is removed, the
windowing state is modified as if there were an exit_fullscreen request
made in the same manage sequence as the river_output_v1.removed event.
This request does not inform the window that it is fullscreen, see the
river_window_v1.inform_fullscreen and inform_not_fullscreen requests.
This request modifies window management state and may only be made as
part of a manage sequence, see the river_window_manager_v1 description.
</description>
<arg name="output" type="object" interface="river_output_v1"
summary="fullscreen output"/>
</request>
<request name="exit_fullscreen">
<description summary="make the window not fullscreen">
Make the window not fullscreen.
The position and dimensions are undefined after this request is made
until a manage sequence in which the window manager makes the
propose_dimensions and set_position requests is completed.
The window manager should make propose_dimensions and set_position
requests in the same manage sequence as the exit_fullscreen request for
frame perfection.
This request does not inform the window that it is fullscreen, see the
river_window_v1.inform_fullscreen and inform_not_fullscreen requests.
This request modifies window management state and may only be made as
part of a manage sequence, see the river_window_manager_v1 description.
</description>
</request>
<event name="minimize_requested">
<description summary="the window requested to be minimized">
The xdg-shell protocol for example allows windows to request to be
minimized.
The window manager is free to ignore this request, hide the window, or
do whatever else it chooses.
This event will be followed by a manage_start event after all other new
state has been sent by the server.
</description>
</event>