Wayland compositor (wlroots)
git clone https://git.lucas.co/cce-compositor.git
xkb-keybinds: delete protocol
This seems to have been a dead end, see previous commit message
protocol/river-xkb-keybinds-v1.xml | 312 -------------------------------------
1 file changed, 312 deletions(-)
diff --git a/protocol/river-xkb-keybinds-v1.xml b/protocol/river-xkb-keybinds-v1.xml
deleted file mode 100644
index 7551519..0000000
--- a/protocol/river-xkb-keybinds-v1.xml
+++ /dev/null
@@ -1,312 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<protocol name="river_xkb_keybinds_v1">
- <copyright>
- Copyright 2024 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="client managed xkbcommon-based keybinds">
- This protocol allows a single "keybind manager" client to define
- xkbcommon-based keybinds for the compositor and receive events when keybinds
- are invoked.
-
- The key words "must", "must not", "required", "shall", "shall not",
- "should", "should not", "recommended", "may", and "optional" in this
- document are to be interpreted as described in IETF RFC 2119.
-
- 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_xkb_keybind_manager_v1" version="1">
- <request name="destroy" type="destructor">
- <description summary="destroy the manager object">
- This request indicates that the client will no longer use the manager
- object and that it may be safely destroyed.
- </description>
- </request>
-
- <event name="unavailable">
- <description summary="keybind management unavailable">
- This event indicates that keybind management is not available to the
- client, perhaps due to another keybind management client already
- running. The circumstances causing this event to be sent are compositor
- policy.
-
- The server will send no further events on this object. The client should
- destroy this object and all objects created through this interface.
- </description>
- </event>
-
- <request name="get_keybind_seat">
- <arg name="id" type="new_id" interface="river_xkb_keybind_seat_v1"/>
- <arg name="seat" type="object" interface="wl_seat"/>
- </request>
- </interface>
-
- <interface name="river_xkb_keybind_seat_v1" version="1">
- <description summary="define keybinds for a seat">
- This extension of wl_seat allows the keybind manager client to define
- arbitrary keybinds for the seat.
- </description>
-
- <request name="destroy" type="destructor">
- <description summary="destroy the keybind seat object">
- This request indicates that the client will no longer use the keybind
- seat object and that it may be safely destroyed.
- </description>
- </request>
-
- <request name="get_initial_state">
- <description summary="get the object for the initial state">
- The initial state is the the state started in before any key events are
- processed and the state transitioned to when the session is unlocked.
-
- It is a protocol error to make this request more than once.
- </description>
- <arg name="id" type="new_id" interface="river_xkb_keybind_state_v1"/>
- </request>
-
- <request name="get_locked_state">
- <description summary="get the object for the locked state">
- The locked state is automatically transitioned to when the session is
- locked.
-
- When the session is unlocked, the initial state is automatically
- transitioned to.
-
- It is a protocol error to make this request more than once.
- </description>
- <arg name="id" type="new_id" interface="river_xkb_keybind_state_v1"/>
- </request>
-
- <request name="create_custom_state">
- <description summary="create a new custom state">
- This request creates a new custom state that may be transitioned to by
- keybinds defined in the initial state, locked state, or other custom
- state.
- </description>
- <arg name="id" type="new_id" interface="river_xkb_keybind_state_v1"/>
- </request>
- </interface>
-
- <interface name="river_xkb_keybind_state_v1" version="1">
- <description summary="a set of keybinds">
- A keybind state is a set of keybinds that are activated/deactivated
- together. Exactly one keybind state is active at a time. States are
- transitioned between using keybinds with a state transition defined
- through the river_xkb_keybind_v1.set_state_transition request.
-
- Conceptually, keybind states are the states in a Deterministic Finite
- Automaton or "State Machine" where keybinds are the transitions.
-
- Keybind states may also be thought of as "modes" similar to the modes in
- modal text editors.
-
- Key events that do not trigger a keybind defined in the active keybind
- state are passed on to whatever client currently has keyboard focus.
-
- Rationale: using a state machine to describe the key event routing done by
- the server avoids the need for roundtrips with the keybind manager client
- when processing keybinds. Without the ability to predefine changes in
- routing in response to key events it would be necessary to roundtrip on
- every keybind trigger to allow the keybind manager client to modify the
- set of active keybinds in response before the next key event is processed.
- This would require buffering key events on the server side during the
- roundtrip and have higher global complexity in my opinion.
-
- It is considered acceptable that modifying the keybind state machine may
- race with incoming keybind triggers. For this reason, the state machine
- should generally not be modified dynamically in response to keybind
- triggers, only in response to manual user re-configuration.
- </description>
-
- <request name="destroy" type="destructor">
- <description summary="destroy the keybind state object">
- This request indicates that the client will no longer use the keybind
- state object and that it may be safely destroyed.
-
- If the destroyed keybind state is currently active, either the initial
- state or the locked state will be activated.
-
- The initial state and locked state are special and should only be
- destroyed when the keybind manager client is terminated and is cleaning
- up resources.
- </description>
- </request>
-
- <request name="define_keybind">
- <description summary="define a new keybind">
- Define a keybind in the keybind state. The new keybind is not
- enabled until initial configuration is completed and the
- river_xkb_keybind_v1.enable request is made.
- </description>
- <arg name="id" type="new_id" interface="river_xkb_keybind_v1"/>
- <arg name="keysym" type="uint" summary="an xkbcommon keysym"/>
- </request>
- </interface>
-
- <interface name="river_xkb_keybind_v1" version="1">
- <description summary="configure a keybind and receive trigger events">
- This object allows the keybind manager to configure a keybind and receive
- events when the keybind is triggered.
-
- The new keybind is not enabled until initial configuration is completed
- and the enable request is made.
-
- If multiple keybinds enabled in the same keybind state would be triggered
- by the a single physical key event on the compositor side, it is
- compositor policy which keybind(s) will receive a trigger event or if all
- of the matched keybinds receive trigger events.
-
- If the keybinds matched by a single key event have differing state
- transitions configured it is compositor policy which transition is
- executed.
-
- Keybinds might be matched by the same physical key event due to shared
- keysym, modifiers, and trigger. The layout override feature may also cause
- the same physical key event to trigger two keybinds with different keysyms
- and different layout overrides configured.
- </description>
-
- <request name="destroy" type="destructor">
- <description summary="destroy the keybind object">
- This request indicates that the client will no longer use the keybind
- object and that it may be safely destroyed.
- </description>
- </request>
-
- <enum name="modifiers" bitfield="true">
- <description summary="a set of keyboard modifiers">
- This enum is used to describe the modifiers that must be held down to
- trigger a keybind.
-
- Note that river and wlroots use the values 2 and 16 for capslock and
- numlock internally. It doesn't make sense to use locked modifiers for
- keybinds however so these values are not included in this enum.
- </description>
- <entry name="none" value="0"/>
- <entry name="shift" value="1"/>
- <entry name="ctrl" value="4"/>
- <entry name="mod1" value="8" summary="commonly called alt"/>
- <entry name="mod3" value="32"/>
- <entry name="mod4" value="64" summary="commonly called super or logo"/>
- <entry name="mod5" value="128"/>
- </enum>
-
- <request name="set_modifiers">
- <description summary="set modifiers required to trigger keybind">
- Set the modifiers that must be held in order to trigger the keybind.
-
- If this request is not made before the enable request no modifiers will
- be required (equivalent to passing none).
-
- It is a protocol error to make this request after the enable request.
-
- Modifiers are always checked on key press regardless of the trigger
- configured with the set_trigger request. Release keybinds are handled by
- saving the set of modifiers that were held on key press and checking for
- a matching keybind in the currently active state on release.
-
- Here is a detailed example demonstrating this behavior:
-
- In keybind state foo there is a keybind A defined as:
- keysym: x, modifiers: shift, trigger: press, state_transition: bar
-
- In keybind state bar there is a keybind B defined as:
- keysym: x, modifiers: shift, trigger: release, state_transition: foo
-
- 0. currently in state foo
- 1. shift key pressed
- 2. x key pressed
- - server notes that shift mod was held on press
- 3. keybind A is triggered
- - transition to state bar
- 4. shift key released
- 5. arbitrary other key events without releasing the x key
- - state transition away from state bar is irrelevant as long as a
- transition back to state bar is made before releasing the x key
- 7. x key released
- 8. keybind B is triggered (despite shift no longer being held)
- - transition to state foo
- </description>
- <arg name="modifiers" type="uint" enum="modifiers"/>
- </request>
-
- <enum name="trigger">
- <entry name="press" value="0" summary="triggered on key press"/>
- <entry name="release" value="1" summary="triggered on key release"/>
- <entry name="repeat" value="2" summary="triggered repeatedly while
- the key is held down"/>
- </enum>
-
- <request name="set_trigger">
- <description summary="set event that triggers keybind">
- Set the event that triggers the keybind.
-
- If this request is not made before the enable request the keybind will
- be triggered on key press.
-
- It is a protocol error to make this request after the enable request.
- </description>
- <arg name="trigger" type="uint" enum="trigger"/>
- </request>
-
- <request name="set_layout_override">
- <description summary="override currently active xkb layout">
- Specify an xkb layout that should be used to translate key events for
- the purpose of triggering this keybind irrespective of the currently
- active xkb layout.
-
- If this request is not made before the enable request the currently
- active xkb layout will be used.
-
- It is a protocol error to make this request after the enable request.
- </description>
- <arg name="layout" type="uint" summary="0-indexed xkbcommon layout"/>
- </request>
-
- <request name="set_state_transition">
- <description summary="transition to a given keybind state on trigger">
- Transition to a given keybind state when the keybind is triggered.
-
- If this request is not made before the enable request the current
- keybind state will not be changed when this keybind is triggered.
-
- It is a protocol error to make this request after the enable request.
- </description>
- <arg name="mode" type="object" interface="river_xkb_keybind_state_v1"/>
- </request>
-
- <request name="enable">
- <description summary="enable the keybind">
- This request should be made after all initial configuration has been
- completed.
-
- It is a protocol error to make this request more than once.
- </description>
- </request>
-
- <event name="triggered">
- <description summary="the keybind has been triggered">
- This event indicates that the keybind has been triggered.
-
- This event will not be issued until after the enable request has been
- received by the server.
- </description>
- </event>
- </interface>
-</protocol>