River window layout

let clients propose view positions and dimensions

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_v3 object.

Layouts are a strictly linear list of views, the position and dimensions of which are supplied by the client. Any complex underlying data structure a client may use when generating the layout is lost in transmission. This is an intentional limitation.

Additionally, this protocol allows the compositor to deliver arbitrary user-provided commands associated with a layout to clients. A client may use these commands to implement runtime configuration/control, or may ignore them entirely. How the user provides these commands to the compositor is not specified by this protocol and left to compositor policy.

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.

river_layout_manager_v3

version 2

manage river layout objects

A global factory for river_layout_v3 objects.

river_layout_manager_v3::destroy

Type: destructor

destroy()

destroy the river_layout_manager object

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.

river_layout_manager_v3::get_layout

get_layout(id: new_id<river_layout_v3>, output: object<wl_output>, namespace: string)

Argument	Type	Description
id	new_id<river_layout_v3>
output	object<wl_output>
namespace	string	namespace of the layout object

create a river_layout_v3 object

This creates a new river_layout_v3 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_v3 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_v3 object.

river_layout_v3

version 2

receive and respond to layout demands

This interface allows clients to receive layout demands from the compositor for a specific output and subsequently propose positions and dimensions of individual views.

river_layout_v3::destroy

Type: destructor

destroy()

destroy the river_layout_v3 object

This request indicates that the client will not use the river_layout_v3 object any more.

river_layout_v3::push_view_dimensions

push_view_dimensions(x: int, y: int, width: uint, height: uint, serial: uint)

Argument	Type	Description
x	int	x coordinate of view
y	int	y coordinate of view
width	uint	width of view
height	uint	height of view
serial	uint	serial of layout demand

propose dimensions of the next view

This request proposes a size and position for a view in the layout demand with matching serial.

A client must send this request for every view that is part of the layout demand. The number of views in the layout is given by the view_count argument of the layout_demand event. Pushing too many or too few view dimensions is a protocol error.

The x and y coordinates are relative to the usable area of the output, with (0,0) as the top left corner.

river_layout_v3::commit

commit(layout_name: string, serial: uint)

Argument	Type	Description
layout_name	string	name of committed layout
serial	uint	serial of layout demand

commit a layout

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 layout_name argument is a user-facing name or short description of the layout that is being committed. The compositor may for example display this on a status bar, though what exactly is done with it is left to the compositor's discretion.

The compositor is free to use this proposed layout however it chooses, including ignoring it.

river_layout_v3::namespace_in_use

namespace_in_use()

the requested namespace is already in use

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_v3 object.

river_layout_v3::layout_demand

layout_demand(view_count: uint, usable_width: uint, usable_height: uint, tags: uint, serial: uint)

Argument	Type	Description
view_count	uint	number of views in the layout
usable_width	uint	width of the usable area
usable_height	uint	height of the usable area
tags	uint	tags of the output, 32-bit bitfield
serial	uint	serial of the layout demand

the compositor requires a layout

The compositor sends this event to inform the client that it requires a layout for a set of views.

The usable width and 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 requests 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 should abort work on the old demand as any further work would be wasted.

river_layout_v3::user_command

user_command(command: string)

Argument	Type	Description
command	string

a command sent by the user

This event informs the client of a command sent to it by the user.

The semantic meaning of the command is left for the client to decide. It is also free to ignore it entirely if it so chooses.

A layout_demand will be sent after this event if the compositor is currently using this layout object to arrange the output.

If version 2 or higher of the river_layout_v3 object is bound, the user_command_tags event is guaranteed to be sent directly before the user_command event.

river_layout_v3::user_command_tags

since 2

user_command_tags(tags: uint)

Argument	Type	Description
tags	uint	tags of the output, 32-bit bitfield

a command sent by the user

If version 2 or higher of the river_layout_v3 object is bound, this event will be sent directly before every user_command event. This allows layout generators to be aware of the active tags when a user command is sent. This is necessary for generators wanting to keep settings on a per-tag basis.

river_layout_v3::error

error { count_mismatch, already_committed }

Argument	Value	Description
count_mismatch	0	number of proposed dimensions does not match number of views in layout
already_committed	1	the layout demand with the provided serial was already committed

Compositor Support

	Cage 0.2.0	COSMIC 1.0.0~beta.8	GameScope 3.15.14	Hyprland 0.52.1	Jay 1.11.0	KWin 6.4	Labwc 0.9.2	Louvre 2.14.1	Mir 2.19	Muffin 6.4.1	Mutter 49.2	niri 25.11	river 0.3.13	Sway 1.11	Treeland 0.8.0	Wayfire 0.9.0	Weston 14.0.2
river_layout_manager_v3	x	x	x	x	x	x	x	x	x	x	x	x	2	x	x	x	x

Copyright

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.