phoc-layer-shell-effects-unstable-v1.xml

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="phoc_layer_surface_effects_unstable_v1">
  <copyright>
    Copyright © 2022-2024 Guido Günther

    Permission to use, copy, modify, distribute, and sell this
    software and its documentation for any purpose is hereby granted
    without fee, provided that the above copyright notice appear in
    all copies and that both that copyright notice and this permission
    notice appear in supporting documentation, and that the name of
    the copyright holders not be used in advertising or publicity
    pertaining to distribution of the software without specific,
    written prior permission.  The copyright holders make no
    representations about the suitability of this software for any
    purpose.  It is provided "as is" without express or implied
    warranty.

    THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
    SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
    FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
    SPECIAL, 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>

  <interface name="zphoc_layer_shell_effects_v1" version="3">
    <description summary="Adjust properties of layer surfaces">
      Assigns additional features to layer surfaces such as opacity or gestures interaction.

      Warning! The protocol described in this file is experimental and
      backward incompatible changes may be made. Backward compatible changes
      may be added together with the corresponding interface version bump.
      Backward incompatible changes are done by bumping the version number in
      the protocol and interface names and resetting the interface version.
      Once the protocol is to be declared stable, the 'z' prefix and the
      version number in the protocol and interface names are removed and the
      interface version number is reset.

      This protocol is meant to collect necessary bits before we propose an
      upstream solution.
    </description>

    <enum name="error">
      <entry name="bad_surface" value="0" summary="layer surface is not committed"/>
      <entry name="bad_anchors" value="1" summary="layer surface is not anchored to 3 edges"/>
      <entry name="bad_margin" value="2" summary="layer surface has no margin to use"/>
    </enum>

    <enum name="stack_error" since="3">
      <entry name="invalid_layer" value="0" summary="layer surfaces not in same layer"/>
      <entry name="invalid_output" value="1" summary="layer surfaces not on same output"/>
      <entry name="invalid_surface" value="2" summary="layer surface invalid"/>
    </enum>

    <request name="get_draggable_layer_surface">
      <description summary="Make layer_surface draggable">
        This marks a layer surface as draggable via one finger drag on touch or click and
        drag when using a mouse. E.g. a surface that is anchored to the left, right and
        top can be dragged to the bottom exposing more of it's surface.

        The state with the minimal amount of surface visible is called
        folded state, the state with the maximum amount of surface visible is
        called unfolded state. These two states are defined by the layer
        surfaces margin in those states. During drag the layer surfaces margin
        is adjusted to move the surface invalidating the margin set on the
        zwlr_layer_surface_v1 interface. The default folded and unfolded
        margins are 0.

        The threshold ([0.0, 1.0]) specifies how far the user needs to
        pull out the surface to not slide back into the folded state but
        rather slide into the unfolded state. The default is 1.0.

        The client is responsible for adjusting it's margins when it's
        size changes to e.g. make sure only the wanted parts of the surface
        are visible in folded state.

        Note that you shouldn't modify exclusive_zone or margins via
        zwlr_layer_surface_v1 interface directly when using this one.

        Margins, threshold and exclusive zone are double buffered and will
        be applied on the next surface commit.
      </description>
      <arg name="id" type="new_id" interface="zphoc_draggable_layer_surface_v1"/>
      <arg name="layer_surface" type="object" interface="zwlr_layer_surface_v1"/>
    </request>

    <request name="destroy" type="destructor">
      <description summary="destroy the layer_shell_effects object">
        This request indicates that the client will not use the layer_shell
        effects object any more. Objects that have been created through this instance
        are not affected.
      </description>
    </request>

    <request name="get_alpha_layer_surface" since="2">
      <description summary="Allow layer_surface to become transparent"/>
      <arg name="id" type="new_id" interface="zphoc_alpha_layer_surface_v1"/>
      <arg name="layer_surface" type="object" interface="zwlr_layer_surface_v1"/>
    </request>

    <request name="get_stacked_layer_surface" since="3">
      <description summary="Allow to tweak how a layer surfaces is stacked">
        Making a layer surface stacked allows to fixate it's position in
        the layer surface stack.
      </description>
      <arg name="id" type="new_id" interface="zphoc_stacked_layer_surface_v1"/>
      <arg name="surface" type="object" interface="zwlr_layer_surface_v1"/>
    </request>

  </interface>

  <interface name="zphoc_draggable_layer_surface_v1" version="2">
    <description summary="Draggable layer surface interface">
      An interface that may be implemented by a layer_surface, for surfaces that
      are designed to become draggable when anchored at three edges.
    </description>

    <request name="set_margins">
      <description summary="Set the margins">
        Sets the folded and unfolded margins. For how they are defined
        refer to margins in the layer-surface protocol.

        Margins are double-buffered, see wl_surface.commit.
      </description>
      <arg name="margin_folded" type="int"/>
      <arg name="margin_unfolded" type="int"/>
    </request>

    <request name="set_threshold">
      <description summary="Set the threshold">
        How far the surface needs to be pulled to go from folded to unfolded state
        and vice versa. Ranges  0.0 to 1.0 as fraction of the total margin
        between folded and unfolded state.

        Threshold is double-buffered, see wl_surface.commit.
      </description>
      <arg name="threshold" type="fixed"/>
    </request>

    <request name="set_exclusive">
      <description summary="Set the exclusive zone">
        Sets the exclusive zone. This is the amount of pixels from the screen
        edge that shouldn't be occluded by other surfaces.

        Exclusive zone is double-buffered, see wl_surface.commit.
      </description>
      <arg name="exclusive" type="uint"/>
    </request>

    <request name="set_drag_mode">
      <description summary="Set the drag mode">
        Specify how the surface can be dragged. The default is
        "full".

        Drag-mode is double-buffered, see wl_surface.commit.
      </description>
      <arg name="mode" type="uint" enum="drag_mode"/>
    </request>

    <request name="set_drag_handle">
      <description summary="The drag mode">
        Specify the position of the drag handle and thus the area that responds
        to drag gestures.

        If the surface's non anchored edge is at the left or right it specifies
        the x, otherwise the y coordinate of the drag handle in surface local
        coordinates. The area between the non anchored surface edge and the
        drag handle responds to drag gestures.

         0  +-----------------+
         1  |                 |
         2  |        A        |
         3  |                 |
         4  +++++++++++++++++++  -- drag handle
         5  |                 |
         6  |                 |
         7  |        B        |
         8  |                 |
         9  +-----------------+

        If the above surface's non anchored edge is at the bottom then a drag handle
        of 4 will make area B respond to touch events. If the non anchored edge is at
        the top the same value makes area A respond to touch events.

        A special value of 0 indicates that the whole surface should be draggable.

        The default is 0.

        Drag-handle is double-buffered, see wl_surface.commit.
      </description>
      <arg name="handle" type="uint"/>
    </request>

    <request name="set_state">
      <description summary="Set a certain state">
        Set state to folded or unfolded. This is applied immediately.
      </description>
      <arg name="state" type="uint" enum="drag_end_state"/>
    </request>

    <request name="destroy" type="destructor">
      <description summary="destroy the draggable_layer_surface">
        This request destroys the draggable layer surface.

        It's a protocol error if the client destroys the layer-surface before
        the draggable layer-surface.
      </description>
    </request>

    <event name="dragged">
      <description summary="A drag is ongoing">
        The is draging the surface.

        TODO: indicate drag (by user) vs slide (by compositor)
      </description>
      <arg name="margin" type="int" summary="The current margin"/>
    </event>

    <event name="drag_end">
      <description summary="A drag ended">
        The user ended dragging the surface and it entered either folded
        or unfolded state.
      </description>
      <arg name="state" type="uint" enum="drag_end_state" summary="The state"/>
    </event>

    <enum name="drag_end_state">
      <entry name="folded" value="0" summary="The surface is folded"/>
      <entry name="unfolded" value="1" summary="The surface is unfolded"/>
    </enum>

    <enum name="drag_mode">
      <entry name="full" value="0" summary="The whole surface is draggable"/>
      <entry name="handle" value="1" summary="Only the handle is draggable"/>
      <entry name="none" value="2" summary="Surface not draggable"/>
    </enum>

  </interface>

  <interface name="zphoc_alpha_layer_surface_v1" version="2">

    <request name="set_alpha">
      <description summary="Set the surface's alpha value">
        Set the surface's transparency. Valid values are between 0.0
        (fully transparent) and 1.0 (fully opaque). The set value
        also affects subsurfaces and popups.

        Alpha is double-buffered, see wl_surface.commit.
      </description>
      <arg name="alpha" type="fixed"/>
    </request>

    <request name="destroy" type="destructor">
      <description summary="destroy the alpha_layer_surface">
        This request destroys the alpha layer surface.
      </description>
    </request>

  </interface>

  <interface name="zphoc_stacked_layer_surface_v1" version="3">

    <request name="stack_below">
      <description summary="Stack surface below the given layer surface">
        Attaches the stacked layer surface below the layer surface given
        in this request. Both surfaces must be in the same layer and on
        the same output. Otherwise a protocol error will be raised.
      </description>
      <arg name="surface" type="object" interface="zwlr_layer_surface_v1"/>
    </request>

    <request name="stack_above">
      <description summary="Stack surface below the given layer surface">
        Attaches the stacked layer surface above the layer surface given
        in this request. Both surfaces must be in the same layer and on
        the same output. Otherwise a protocol error will be raised.
      </description>
      <arg name="surface" type="object" interface="zwlr_layer_surface_v1"/>
    </request>

    <request name="destroy" type="destructor">
      <description summary="destroy the stacked layer_surface">
        This request destroys the stacked layer surface
      </description>
    </request>

  </interface>

</protocol>