d08032d685
Options are now all global but may be overridden per-output. If an output local value is requested but none has been set, the global value is provided instead. This makes for much better ergonomics when configuring layout related options in particular.
210 lines
8.6 KiB
XML
210 lines
8.6 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<protocol name="river_options_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="set and retrieve options">
|
|
This protocol allows clients to access a typed key-value store of
|
|
options. These options are global but may be overridden using a handle
|
|
scoped to a wl_output. If no output scoped value has been set, then the
|
|
global value is provided to this handle.
|
|
|
|
This protocol does not define any semantic meaning of the options,
|
|
that is left up to compositors.
|
|
|
|
Compositors are free to set or declare options themselves at any time,
|
|
though the type of any given option is immutable once set.
|
|
|
|
Options are never removed once declared.
|
|
|
|
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_options_manager_v2" version="1">
|
|
<description summary="declare options and get handles">
|
|
This interface allows clients to declare new options and create
|
|
river_option_v2 handle objects in order to retrieve the current
|
|
value or set a new one.
|
|
</description>
|
|
|
|
<request name="destroy" type="destructor">
|
|
<description summary="destroy the river_options_manager_v2 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="declare_int_option">
|
|
<description summary="declare a new option">
|
|
The option is created in the global scope and is initialized with the
|
|
provided value. This request is ignored if the option already exists.
|
|
</description>
|
|
<arg name="key" type="string"/>
|
|
<arg name="value" type="int"/>
|
|
</request>
|
|
|
|
<request name="declare_uint_option">
|
|
<description summary="declare a new option">
|
|
The option is created in the global scope and is initialized with the
|
|
provided value. This request is ignored if the option already exists.
|
|
</description>
|
|
<arg name="key" type="string"/>
|
|
<arg name="value" type="uint"/>
|
|
</request>
|
|
|
|
<request name="declare_string_option">
|
|
<description summary="declare a new option">
|
|
The option is created in the global scope and is initialized with the
|
|
provided value. This request is ignored if the option already exists.
|
|
</description>
|
|
<arg name="key" type="string"/>
|
|
<arg name="value" type="string" allow-null="true"/>
|
|
</request>
|
|
|
|
<request name="declare_fixed_option">
|
|
<description summary="declare a new option">
|
|
The option is created in the global scope and is initialized with the
|
|
provided value. This request is ignored if the option already exists.
|
|
</description>
|
|
<arg name="key" type="string"/>
|
|
<arg name="value" type="fixed"/>
|
|
</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="river_option_handle_v2"/>
|
|
</request>
|
|
|
|
<request name="unset_option">
|
|
<description summary="unset an output-local value if any">
|
|
This causes the value of the option for the given output to fall
|
|
back to the global value.
|
|
</description>
|
|
<arg name="key" type="string"/>
|
|
<arg name="output" type="object" interface="wl_output"/>
|
|
</request>
|
|
</interface>
|
|
|
|
<interface name="river_option_handle_v2" 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,
|
|
including its type. Making one of the 4 set requests before receiving
|
|
this first event would be a bug as the client would not yet know the
|
|
type 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
|
|
river_option_handle_v2 any more and that it may be safely destroyed.
|
|
</description>
|
|
</request>
|
|
|
|
<enum name="error">
|
|
<entry name="request_while_undeclared" value="0" summary="a request other
|
|
than destroy was made after receiving the undeclared event"/>
|
|
<entry name="type_mismatch" value="1"
|
|
summary="a set request of the wrong type was made"/>
|
|
</enum>
|
|
|
|
<event name="undeclared">
|
|
<description summary="the option has never been declared">
|
|
No option with the the given name has ever been declared. All requests
|
|
on this object aside from the destroy request are a protocol error and
|
|
no further events will be sent.
|
|
</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="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>
|
|
|
|
<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>
|
|
|
|
<request name="set_int_value">
|
|
<description summary="set the value of the option">
|
|
If the option is of type int, set the value of the option.
|
|
Otherwise, this request is a protocol error.
|
|
</description>
|
|
<arg name="value" type="int"/>
|
|
</request>
|
|
|
|
<request name="set_uint_value">
|
|
<description summary="set the value of the option">
|
|
If the option is of type uint, set the value of the option.
|
|
Otherwise, this request is a protocol error.
|
|
</description>
|
|
<arg name="value" type="uint"/>
|
|
</request>
|
|
|
|
<request name="set_string_value">
|
|
<description summary="set the value of the option">
|
|
If the option is of type string, set the value of the option.
|
|
Otherwise, this request is a protocol error.
|
|
</description>
|
|
<arg name="value" type="string" allow-null="true"/>
|
|
</request>
|
|
|
|
<request name="set_fixed_value">
|
|
<description summary="set the value of the option">
|
|
If the option is of type fixed, set the value of the option.
|
|
Otherwise, this request is a protocol error.
|
|
</description>
|
|
<arg name="value" type="fixed"/>
|
|
</request>
|
|
</interface>
|
|
</protocol>
|