river/protocol/river-options-unstable-v1.xml

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="river_options_unstable_v1">
  <copyright>
    Copyright 2020 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>

  <interface name="zriver_options_manager_v1" version="1">
    <description summary="set and retrieve options">
      This protocol allows clients to access a typed key-value store of
      options. These options are identified by string keys and are scoped
      either globally or per-output. This protocol does not define any
      semantic meaning of the options, that is left up to compositors.

      Compositors are free to set options themselves at any time, though
      the type of any given option is immutable once set.

      Options may never be unset once set.
    </description>

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

    <request name="get_option_handle">
      <description summary="get an option handle for the given key">
        If the output argument is non-null, the option is local to the given
        output. Otherwise it is considered global.
      </description>
      <arg name="key" type="string"/>
      <arg name="output" type="object" interface="wl_output" allow-null="true"/>
      <arg name="handle" type="new_id" interface="zriver_option_handle_v1"/>
    </request>
  </interface>

  <interface name="zriver_option_handle_v1" version="1">
    <description summary="handle to an option">
      On binding this object, one of the events will immediately be sent by
      the server to inform the client of the current state of the option. New
      events will be sent as the state changes.
    </description>

    <request name="destroy" type="destructor">
      <description summary="destroy the handle">
        This request indicates that the client will not use the
        zriver_option_handle_v1 any more and that it may be safely destroyed.
      </description>
    </request>

    <event name="unset">
      <description summary="the option is currently unset">
        The option with this key has never been set, so the first set_*_value
        request received from any client will determine its type.

        This can only ever be sent as the first event after binding this
        interface as options cannot be unset once set.
      </description>
    </event>

    <event name="int_value">
      <description summary="the current value of the int option">
        This indicates to the client that the option is of type int as well
        as the current value of the option. Once set the type of the option
        can never change.
      </description>
      <arg name="value" type="int"/>
    </event>

    <event name="uint_value">
      <description summary="the current value of the uint option">
        This indicates to the client that the option is of type uint as well
        as the current value of the option. Once set the type of the option
        can never change.
      </description>
      <arg name="value" type="uint"/>
    </event>

    <event name="fixed_value">
      <description summary="the current value of the fixed option">
        This indicates to the client that the option is of type fixed as
        well as the current value of the option. Once set the type of the option
        can never change.
      </description>
      <arg name="value" type="fixed"/>
    </event>

    <event name="string_value">
      <description summary="the current value of the string option">
        This indicates to the client that the option is of type string as
        well as the current value of the option. Once set the type of the option
        can never change.
      </description>
      <arg name="value" type="string" allow-null="true"/>
    </event>

    <request name="set_int_value">
      <description summary="set the value of the option">
        If the option is either unset or set to a value of type int, this
        request asks the compositor to set the value of the option as well
        as the type if previously unset. The compositor is not required to
        honor this request.

        If the option is already set and is not of type int, this request does nothing.
      </description>
      <arg name="value" type="int"/>
    </request>

    <request name="set_uint_value">
      <description summary="set the value of the option">
        If the option is either unset or set to a value of type uint, this
        request asks the compositor to set the value of the option as well
        as the type if previously unset. The compositor is not required to
        honor this request.

        If the option is already set and is not of type uint, this request
        does nothing.
      </description>
      <arg name="value" type="uint"/>
    </request>

    <request name="set_fixed_value">
      <description summary="set the value of the option">
        If the option is either unset or set to a value of type fixed, this
        request asks the compositor to set the value of the option as well
        as the type if previously unset. The compositor is not required to
        honor this request.

        If the option is already set and is not of type fixed, this request
        does nothing.
      </description>
      <arg name="value" type="fixed"/>
    </request>

    <request name="set_string_value">
      <description summary="set the value of the option">
        If the option is either unset or set to a value of type string,
        this request asks the compositor to set the value of the option as
        well as the type if previously unset. The compositor is not required
        to honor this request.

        If the option is already set and is not of type string, this request
        does nothing.
      </description>
      <arg name="value" type="string" allow-null="true"/>
    </request>
  </interface>
</protocol>