River xkb config
This protocol allow a client to set the xkbcommon keymap of individual keyboard input devices. It also allows switching between the layouts of a keymap and toggling capslock/numlock state.
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.
river_xkb_config_v1
Global interface for configuring xkb devices.
This global should only be advertised if river_input_manager_v1 is advertised as well.
stop()
This request indicates that the client no longer wishes to receive events on this object.
The Wayland protocol is asynchronous, which means the server may send further events until the stop request is processed. The client must wait for a river_xkb_config_v1.finished event before destroying this object.
destroy()
This request should be called after the finished event has been received to complete destruction of the object.
It is a protocol error to make this request before the finished event has been received.
If a client wishes to destroy this object it should send a river_xkb_config_v1.stop request and wait for a river_xkb_config_v1.finished event. Once the finished event is received it is safe to destroy this object and any other objects created through this interface.
create_keymap(id: new_id<river_xkb_keymap_v1>, fd: fd, format: uint<river_xkb_config_v1.keymap_format>)
Argument | Type | Description |
|---|---|---|
| id | new_id<river_xkb_keymap_v1> | |
| fd | fd | |
| format | uint<river_xkb_config_v1.keymap_format> |
The server must be able to mmap the fd with MAP_PRIVATE. The server will fstat the fd to obtain the size of the keymap. The client must not modify the contents of the fd after making this request. The client should seal the fd with fcntl.
finished()
This event indicates that the server will send no further events on this object. The client should destroy the object. See river_xkb_config_v1.destroy for more information.
xkb_keyboard(id: new_id<river_xkb_keyboard_v1>)
Argument | Type | Description |
|---|---|---|
| id | new_id<river_xkb_keyboard_v1> |
A new xkbcommon keyboard has been created. Not every river_input_device_v1 is necessarily an xkbcommon keyboard as well.
error { invalid_destroy, invalid_format }
Argument | Value | Description |
|---|---|---|
| invalid_destroy | 0 | |
| invalid_format | 1 |
river_xkb_keymap_v1
This object is the result of attempting to create an xkbcommon keymap.
destroy()
This request indicates that the client will no longer use the keymap object and that it may be safely destroyed.
success()
The keymap object was successfully created and may be used with the river_xkb_keyboard_v1.set_keymap request.
river_xkb_keyboard_v1
This object represent a physical keyboard which has its configuration and state managed by xkbcommon.
destroy()
This request indicates that the client will no longer use the keyboard object and that it may be safely destroyed.
set_keymap(keymap: object<river_xkb_keymap_v1>)
Argument | Type | Description |
|---|---|---|
| keymap | object<river_xkb_keymap_v1> |
Set the keymap for the keyboard.
It is a protocol error to pass a keymap object for which the river_xkb_keymap_v1.success event was not received.
set_layout_by_index(index: int)
Argument | Type | Description |
|---|---|---|
| index | int |
Set the active layout for the keyboard's keymap. Has no effect if the layout index is out of bounds for the current keymap.
set_layout_by_name(name: string)
Argument | Type | Description |
|---|---|---|
| name | string |
Set the active layout for the keyboard's keymap. Has no effect if there is no layout with the give name for the keyboard's keymap.
capslock_enable()
Enable capslock for the keyboard.
capslock_disable()
Disable capslock for the keyboard.
numlock_disable()
Disable numlock for the keyboard.
removed()
This event indicates that the xkb keyboard has been removed.
The server will send no further events on this object and ignore any request (other than river_xkb_keyboard_v1.destroy) made after this event is sent. The client should destroy this object with the river_xkb_keyboard_v1.destroy request to free up resources.
input_device(device: object<river_input_device_v1>)
Argument | Type | Description |
|---|---|---|
| device | object<river_input_device_v1> |
The river_input_device_v1 corresponding to this xkb keyboard. This event will always be the first event sent on the river_xkb_keyboard_v1 object, and it will be sent exactly once.
The currently active layout index and name. The name arg may be null if the active layout does not have a name.
This event is sent once when the river_xkb_keyboard_v1 is created and again whenever the layout changes.
capslock_enabled()
Capslock is currently enabled for the keyboard.
This event is sent once when the river_xkb_keyboard_v1 is created and again whenever the capslock state changes.
capslock_disabled()
Capslock is currently disabled for the keyboard.
This event is sent once when the river_xkb_keyboard_v1 is created and again whenever the capslock state changes.
numlock_enabled()
Numlock is currently enabled for the keyboard.
This event is sent once when the river_xkb_keyboard_v1 is created and again whenever the numlock state changes.
numlock_disabled()
Numlock is currently disabled for the keyboard.
This event is sent once when the river_xkb_keyboard_v1 is created and again whenever the numlock state changes.
Compositor Support
Copyright
SPDX-FileCopyrightText: © 2026 Isaac Freund SPDX-License-Identifier: MIT
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 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.