sway/protocols/wp-screenlocker-unstable-v1.xml

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="zwp_screenlocker_v1">
  <copyright>
    Copyright © 2021 Daniel De Graaf

    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice (including the next
    paragraph) shall be included in all copies or substantial portions of the
    Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.
  </copyright>

  <interface name="zwp_screenlocker_v1" version="1">
    <description summary="Screen locking manager">
      This interface provides notification of screen lock/unlock events,
      displaying windows on a locked screen, and acting as a screenlocker.
    </description>

    <request name="destroy" type="destructor">
      <description summary="destroy this object"/>
    </request>

    <event name="locked">
      <description summary="Triggered when the screen is locked">
        This event will be sent on creation if the screen is currently locked,
        and at the start of any lock action.

        Note: windows on the unlocked desktop may still be visible (due to a
        locking animation) even after this event is sent, so this event should
        not be used to trigger post-lock actions such as a system sleep request.
      </description>
    </event>

    <event name="unlocked">
      <description summary="Triggered when the screen is unlocked">
        This event will be sent on creation if the screen is currently unlocked,
        and at the end of any unlock action.

        Note: windows on the unlocked desktop may become visible (due to an
        unlocking animation) prior to this event being sent.
      </description>
    </event>

    <request name="lock">
      <description summary="Request that this client become the screen locker">
        Requesting a new lock handle will only succeed if this client has
        permission to lock the screen. Compositors that handle screen locking
        internally may choose to always reject this request. If an existing
        client is acting as a screen locker, the compositor may choose to accept
        or reject the new request.
      </description>
      <arg name="id" type="new_id" interface="zwp_screenlocker_lock_v1"/>
    </request>

    <request name="get_visibility">
      <description summary="set the visibility of a surface on the lockscreen">
        By default, no surfaces are visible on the locked desktop. Any surface
        that should be visible on the locked desktop must set its visibility
        using this visibility object.

        This request is required for any toplevel surface displayed on the
        locked desktop to ensure that sensitive information is not present on
        the surface. The exact definition of sensitive may be defined by other
        configuration, but might include notification details, keyboard
        autocompletion, or configuration interfaces.
      </description>
      <arg name="id" type="new_id" interface="zwp_screenlocker_visibility_v1"/>
      <arg name="surface" type="object" interface="wl_surface"/>
    </request>
  </interface>

  <interface name="zwp_screenlocker_lock_v1" version="1">
    <event name="rejected">
      <description summary="The compositor has rejected the request">
        This object is inert and should be destroyed.

        If a compositor does not support external lockers, this event will always
        be sent on the creation of a lock object.
      </description>
      <arg name="reason" type="string" allow-null="true" summary="reason for the rejection"/>
    </event>

    <event name="locked">
      <description summary="The lock request was accepted and the screen is locked">
        The lock handle is active and only the locked desktop is visible on all
        outputs. If a compositor implements a locking animation or similar
        effect that results in both the locked and unlocked desktops being
        visible, this event is sent after the effect completes.
      </description>
    </event>

    <event name="closed">
      <description summary="This lock handle has been invalidated">
        This object is inert and should be destroyed.

        This will be sent if the compositor has unlocked the screen due to some
        external event (for exmple, a dbus unlock message from logind), or if
        another client has taken ownership of the lock.
      </description>
    </event>

    <request name="unlock">
      <description summary="Unlock the screen">
        Let the compositor know that it should unlock the screen.

        It is valid to call this on a newly created lock handle without waiting
        for an event; this will either cancel the lock or do nothing if the lock
        handle is inert.

        After this request has been sent by the client, this object will become
        inert and should be destroyed.
      </description>
    </request>

    <request name="destroy" type="destructor">
      <description summary="destroy this object">
        Destroying an active lock handle without first unlocking it will abandon
        the lock. If a lock is abandoned, the compositor should take some
        fallback action such as launching a new locker client in order to allow
        the user to authenticate and unlock the session.
      </description>
    </request>
  </interface>

  <interface name="zwp_screenlocker_visibility_v1" version="1">
    <request name="destroy" type="destructor">
      <description summary="destroy this object">
        Destroying this object will revert the surface to not be visible on the
        lockscreen at the next commit.
      </description>
    </request>

    <enum name="visibility">
      <entry name="default" value="0" summary="Only visible when unlocked"/>
      <entry name="lock_only" value="1" summary="Only visible when locked"/>
      <entry name="both" value="2" summary="Visible regardless of lock state"/>
    </enum>

    <request name="set_visibility">
      <description summary="set this surface visible on the lockscreen">
        This value is double-buffered, see wl_surface.commit.
      </description>
      <arg name="visibility" type="uint" enum="zwp_screenlocker_visibility_v1.visibility"/>
    </request>

    <event name="failed">
      <description summary="the locked desktop cannot show this window">
        This event is sent immediately if the associated window cannot be shown
        on a locked desktop. This object is inert and should be destroyed.
      </description>
    </event>
  </interface>
</protocol>