river/protocol/river-layout-v2.xml

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="river_layout_v2">
  <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_v2 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_v2 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.
  </description>

  <interface name="river_layout_manager_v2" version="1">
    <description summary="manage river layout objects">
      A global factory for river_layout_v2 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_v2 object">
        This creates a new river_layout_v2 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_v2
        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_v2 object.
      </description>
      <arg name="id" type="new_id" interface="river_layout_v2"/>
      <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_v2" version="1">
    <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_v2 object">
        This request indicates that the client will not use the river_layout_v2
        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_v2 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 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.
      </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>

    <event name="advertise_view">
      <description summary="make layout client aware of view">
        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.
      </description>
      <arg name="tags" type="uint" summary="tags of the view, 32-bit bitfield"/>
      <arg name="app_id" type="string" summary="view app-id" allow-null="true"/>
      <arg name="serial" type="uint" summary="serial of the layout demand"/>
    </event>

    <event name="advertise_done">
      <description summary="all views have been advertised">
        This event is sent by the server as the last event of the layout
        demand with matching serial, after all advertise_view events.
      </description>
      <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 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.
      </description>
      <arg name="serial" type="uint" summary="serial of layout demand"/>
      <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"/>
    </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 compositor is free to use this proposed layout however it chooses,
        including ignoring it.
      </description>
      <arg name="serial" type="uint" summary="serial of layout demand"/>
    </request>

    <event name="set_int_value">
      <description summary="an int value has been set">
        This event indicates that the value of this river_layout_v2 object
        with the given name has been set to the given value.

        This event will be followed by a layout_demand if necessary (i.e. if
        this layout object is currently being used by the compositor to
        layout an output)
      </description>
      <arg name="name" type="string"/>
      <arg name="value" type="int"/>
    </event>

    <event name="mod_int_value">
      <description summary="an int value has been modified">
        This event indicates that the value of this river_layout_v2 object
        with the given name has been modifed by the given delta.

        This event will be followed by a layout_demand if necessary (i.e. if
        this layout object is currently being used by the compositor to
        layout an output)
      </description>
      <arg name="name" type="string"/>
      <arg name="delta" type="int"/>
    </event>

    <event name="set_fixed_value">
      <description summary="a fixed value has been set">
        This event indicates that the value of this river_layout_v2 object
        with the given name has been set to the given value.

        This event will be followed by a layout_demand if necessary (i.e. if
        this layout object is currently being used by the compositor to
        layout an output)
      </description>
      <arg name="name" type="string"/>
      <arg name="value" type="fixed"/>
    </event>

    <event name="mod_fixed_value">
      <description summary="a fixed value has been modified">
        This event indicates that the value of this river_layout_v2 object
        with the given name has been modifed by the given delta.

        This event will be followed by a layout_demand if necessary (i.e. if
        this layout object is currently being used by the compositor to
        layout an output)
      </description>
      <arg name="name" type="string"/>
      <arg name="delta" type="fixed"/>
    </event>

    <event name="set_string_value">
      <description summary="a string value has been set">
        This event indicates that the value of this river_layout_v2 object
        with the given name has been set to the given value.

        This event will be followed by a layout_demand if necessary (i.e. if
        this layout object is currently being used by the compositor to
        layout an output)
      </description>
      <arg name="name" type="string"/>
      <arg name="value" type="string"/>
    </event>
  </interface>
</protocol>