844ffce037
It is not guaranteed that the next layout_demand event after a user_command event has the same active tags (for example when there are no views visible). As an example, a user could trigger a user_command while no views are visible, then switch to a different tag set which has active views. The active tags of the previous layout_demand may also be different. Therefore it is impossible to correctly implement a layout generator which has user commands apply only to the currently active tag set, which is solved by this patch.
197 lines
9.2 KiB
XML
197 lines
9.2 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<protocol name="river_layout_v3">
|
|
<copyright>
|
|
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.
|
|
</copyright>
|
|
|
|
<description summary="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.
|
|
</description>
|
|
|
|
<interface name="river_layout_manager_v3" version="2">
|
|
<description summary="manage river layout objects">
|
|
A global factory for river_layout_v3 objects.
|
|
</description>
|
|
|
|
<request name="destroy" type="destructor">
|
|
<description summary="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.
|
|
</description>
|
|
</request>
|
|
|
|
<request name="get_layout">
|
|
<description summary="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.
|
|
</description>
|
|
<arg name="id" type="new_id" interface="river_layout_v3"/>
|
|
<arg name="output" type="object" interface="wl_output"/>
|
|
<arg name="namespace" type="string" summary="namespace of the layout object"/>
|
|
</request>
|
|
</interface>
|
|
|
|
<interface name="river_layout_v3" version="2">
|
|
<description summary="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.
|
|
</description>
|
|
|
|
<enum name="error">
|
|
<entry name="count_mismatch" value="0" summary="number of
|
|
proposed dimensions does not match number of views in layout"/>
|
|
<entry name="already_committed" value="1" summary="the layout demand with
|
|
the provided serial was already committed"/>
|
|
</enum>
|
|
|
|
<request name="destroy" type="destructor">
|
|
<description summary="destroy the river_layout_v3 object">
|
|
This request indicates that the client will not use the river_layout_v3
|
|
object any more.
|
|
</description>
|
|
</request>
|
|
|
|
<event name="namespace_in_use">
|
|
<description summary="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.
|
|
</description>
|
|
</event>
|
|
|
|
<event name="layout_demand">
|
|
<description summary="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.
|
|
</description>
|
|
<arg name="view_count" type="uint" summary="number of views in the layout"/>
|
|
<arg name="usable_width" type="uint" summary="width of the usable area"/>
|
|
<arg name="usable_height" type="uint" summary="height of the usable area"/>
|
|
<arg name="tags" type="uint" summary="tags of the output, 32-bit bitfield"/>
|
|
<arg name="serial" type="uint" summary="serial of the layout demand"/>
|
|
</event>
|
|
|
|
<request name="push_view_dimensions">
|
|
<description summary="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.
|
|
</description>
|
|
<arg name="x" type="int" summary="x coordinate of view"/>
|
|
<arg name="y" type="int" summary="y coordinate of view"/>
|
|
<arg name="width" type="uint" summary="width of view"/>
|
|
<arg name="height" type="uint" summary="height of view"/>
|
|
<arg name="serial" type="uint" summary="serial of layout demand"/>
|
|
</request>
|
|
|
|
<request name="commit">
|
|
<description summary="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.
|
|
</description>
|
|
<arg name="layout_name" type="string" summary="name of committed layout"/>
|
|
<arg name="serial" type="uint" summary="serial of layout demand"/>
|
|
</request>
|
|
|
|
<event name="user_command">
|
|
<description summary="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.
|
|
</description>
|
|
<arg name="command" type="string"/>
|
|
</event>
|
|
|
|
<event name="user_command_tags" since="2">
|
|
<description summary="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.
|
|
</description>
|
|
<arg name="tags" type="uint" summary="tags of the output, 32-bit bitfield"/>
|
|
</event>
|
|
</interface>
|
|
</protocol>
|