Copyright 2020-2021 The River Developers 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. 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. This protocol specifies a way for clients to propose arbitrary positions and dimensions for a set of views on a specific output of a compositor through the river_layout_v1 object. This set of views is logically structured as a simple list. Views in this list cannot be individually addressed, instead the order of requests/events is significant. The entire set of proposed positions and dimensions for the views in the list are called a layout. Due to their list heritage, layouts are also logically strictly linear; Any complex underlying data structure a client may use when generating the layout is lost in transmission. This is an intentional limitation. Note that the client may need to handle multiple layout demands per river_layout_v1 object simultaneously. Warning! The protocol described in this file is currently in the testing phase. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes can only be done by creating a new major version of the extension. A global factory for river_layout_v1 objects. This request indicates that the client will not use the river_layout_manager object any more. Objects that have been created through this instance are not affected. This creates a new river_layout_v1 object for the given wl_output. All layout related communication is done through this interface. The namespace is used by the compositor to decide which river_layout_v1 object will receive layout demands for the output. The namespace is required to be be unique per-output. Furthermore, two separate clients may not share a namespace on separate outputs. If these conditions are not upheld, the the namespace_in_use event will be sent directly after creation of the river_layout_v1 object. This interface allows clients to receive layout demands from the compositor for a specific output and subsequently propose positions and dimensions of individual views. This request indicates that the client will not use the river_layout_v1 object any more. After this event is sent, all requests aside from the destroy event will be ignored by the server. If the client wishes to try again with a different namespace they must create a new river_layout_v1 object. The compositor sends this event to inform the client that it requires a layout for a set of views. The usable width and height height indicate the space in which the client can safely position views without interfering with desktop widgets such as panels. The serial of this event is used to identify subsequent events and request as belonging to this layout demand. Beware that the client might need to handle multiple layout demands at the same time. The server will ignore responses to all but the most recent layout demand. Thus, clients are only required to respond to the most recent layout_demand received. If a newer layout_demand is received before the client has finished responding to an old demand, the client may abort work on the old demand as any further work would be wasted. This event is sent by the server as part of the layout demand with matching serial. It provides additional information about one of the views to be arranged. Every view part of the layout demand is advertised exactly once, in the order of the view list. This event is sent by the server as the last event of the layout demand with matching serial, after all advertise_view events. This request proposes a size and position of a view in the layout demand with matching serial. Pushed view dimensions apply to the views in the same order they were advertised. That is, the first push_view_dimensions request applies to the first view advertised, the second to the second, and so on. A client must propose position and dimensions for the entire set of views. Proposing too many or too few view dimensions is a protocol error. This request may be sent before the corresponding view has been advertised. The x and y coordinates are relative to the usable area of the output, with (0,0) as the top left corner. This request indicates that the client is done pushing dimensions and the compositor may apply the layout. This completes the layout demand with matching serial, any other requests sent with the serial are a protocol error. The compositor is free to use this proposed layout however it chooses, including ignoring it. The client may use this request to inform the compositor that one or muliple of the parameters it uses to generate layouts have changed. If the client is responsible for the current view layout, the compositor may decide to send a new layout demand to update the layout.