diff --git a/protocol/river-window-management-v1.xml b/protocol/river-window-management-v1.xml index 7bae942..db170d4 100644 --- a/protocol/river-window-management-v1.xml +++ b/protocol/river-window-management-v1.xml @@ -1,26 +1,26 @@ - - - - Copyright 2024 The River Developers + SPDX-FileCopyrightText: © 2024 Isaac Freund + SPDX-License-Identifier: MIT - Permission to use, copy, modify, and/or distribute this software for any - purpose with or without fee is hereby granted, provided that the above - copyright notice and this permission notice appear in all copies. + 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 SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES - WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF - MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY - SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION - OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN - CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + 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. @@ -39,7 +39,7 @@ SPDX-License-Identifier: ISC be done by creating a new major version of the extension. - + This global interface should only be advertised to the window manager process. Only one window management client may be active at a time. The @@ -82,10 +82,10 @@ SPDX-License-Identifier: ISC 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 or position that must be communicated with the window - manager. Multiple render sequences may be made consecutively without a - manage sequence in between, for example during interactive move/resize of - windows or if a window independently changes its own dimensions. + 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: @@ -104,7 +104,7 @@ SPDX-License-Identifier: ISC 5. The client sends requests modifying rendering state (as defined above) followed by the render_finish request. - 6. If window dimensions/positions change, loop back to step 4. + 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. @@ -117,9 +117,11 @@ SPDX-License-Identifier: ISC + summary="request violates manage/render sequence ordering"/> + @@ -308,7 +310,7 @@ SPDX-License-Identifier: ISC - + This represents a logical window. For example, a window may correspond to an xdg_toplevel or Xwayland window. @@ -326,6 +328,8 @@ SPDX-License-Identifier: ISC summary="proposed dimensions out of bounds"/> + @@ -599,6 +603,8 @@ SPDX-License-Identifier: ISC 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. @@ -644,8 +650,9 @@ SPDX-License-Identifier: ISC - Create a window decoration surface above the window and assign the - river_decoration_v1 role to the surface. + 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. @@ -656,8 +663,9 @@ SPDX-License-Identifier: ISC - Create a window decoration surface below the window and assign the - river_decoration_v1 role to the surface. + 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. @@ -905,6 +913,11 @@ SPDX-License-Identifier: ISC shall not affect the current position and dimensions of a fullscreen window. + 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. @@ -950,9 +963,76 @@ SPDX-License-Identifier: ISC state has been sent by the server. + + + + Clip the window, including borders and decoration surfaces, to the box + specified by the x, y, width, and height arguments. The x/y position of + the box is relative to the top left corner of the window. + + The width and height arguments must be greater than or equal to 0. + + Setting a clip box with 0 width or height disables clipping. + + The clip box is ignored while the window is fullscreen. + + Both set_clip_box and set_content_clip_box may be enabled simultaneously. + + This request modifies rendering state and may only be made as part of a + render sequence, see the river_window_manager_v1 description. + + + + + + + + + + This event gives an unreliable PID of the process that created the + window. Obtaining this information is inherently racy due to PID reuse. + Therefore, this PID must not be used for anything security sensitive. + + Note also that a single process may create multiple windows, so there is + not necessarily a 1-to-1 mapping from PID to window. Multiple windows + may have the same PID. + + This event is sent once when the river_window_v1 is created and never + sent again. + + + + + + + Clip the content of the window, excluding borders and decoration + surfaces, to the box specified by the x, y, width, and height arguments. + The x/y position of the box is relative to the top left corner of the + window. + + Borders drawn by the compositor (see set_borders) are placed around the + intersection of the window content (as defined by the dimensions event) + and the content clip box when content clipping is enabled. + + The width and height arguments must be greater than or equal to 0. + + Setting a box with 0 width or height disables content clipping. + + The content clip box is ignored while the window is fullscreen. + + Both set_clip_box and set_content_clip_box may be enabled simultaneously. + + This request modifies rendering state and may only be made as part of a + render sequence, see the river_window_manager_v1 description. + + + + + + - + The rendering order of windows with decorations is follows: @@ -1008,7 +1088,7 @@ SPDX-License-Identifier: ISC - + The window manager might use a shell surface to display a status bar, background image, desktop notifications, launcher, desktop menu, or @@ -1055,7 +1135,7 @@ SPDX-License-Identifier: ISC - + The render list is a list of nodes that determines the rendering order of the compositor. Nodes may correspond to windows or shell surfaces. The @@ -1140,7 +1220,7 @@ SPDX-License-Identifier: ISC - + An area in the compositor's logical coordinate space that should be treated as a single output for window management purposes. This area may @@ -1242,7 +1322,7 @@ SPDX-License-Identifier: ISC - + This object represents a single user's collection of input devices. It allows the window manager to route keyboard input to windows, get @@ -1363,20 +1443,6 @@ SPDX-License-Identifier: ISC - - - The seat's pointer was moved. - - Rationale: The motivating window manager feature for this event is the - "always" style of focus-follows-cursor. Carrying out a full manage - sequence on every single pointer motion event is noisy, wasteful, and - unnecessary. - - This event will be followed by a manage_start event after all other new - state has been sent by the server. - - - A window has been interacted with beyond the pointer merely passing over @@ -1479,47 +1545,6 @@ SPDX-License-Identifier: ISC - - - This request tells the compositor to confine the movement of the pointer - to a given region, preventing movement of the input device from moving - the pointer outside the region. In addition, the pointer continues to be - confined to the bounds of the outputs. - - If the pointer is not inside the given region when this request is made - it will have no effect until the pointer is moved inside the region. - - If the pointer is warped to a point outside of the region it will - (temporarily) escape confinement. Moving or warping the pointer back - inside the region will resume the confinement. - - If the region argument is null the compositor will only confine the - cursor to the bounds of the outputs. This is also the behavior if this - request is never made. - - The region is defined in the compositor's logical coordinate space. - - This request may be useful to place bounds on an interactive pointer - move or resize 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. - - - - - - - Warp the pointer to the given position in the compositor's logical - coordinate space. - - This request modifies window management state and may only be made as - part of a manage sequence, see the river_window_manager_v1 description. - - - - - This enum is used to describe the keyboard modifiers that must be held @@ -1553,9 +1578,53 @@ SPDX-License-Identifier: ISC + + + + Set the XCursor theme for the seat. This theme is used for cursors + rendered by the compositor, but not necessarily for cursors rendered by + clients. + + Note: The window manager may also wish to set the XCURSOR_THEME and + XCURSOR_SIZE environment variable for programs it starts. + + + + + + + + The current position of the pointer in the compositor's logical + coordinate space. + + This state is special in that a change in pointer position alone must + not cause the compositor to start a manage sequence. + + Assuming the seat has a pointer, this event must be sent in every manage + sequence unless there is no change in x/y position since the last time this + event was sent. + + + + + + + + Warp the pointer to the given position in the compositor's logical + coordinate space. + + If the given position is outside the bounds of all outputs, the pointer + will be warped to the closest point inside an output instead. + + This request modifies window management state and may only be made as + part of a manage sequence, see the river_window_manager_v1 description. + + + + - + This object allows the window manager to configure a pointer binding and receive events when the binding is triggered.