From 4380e5ddb927205c8936234ef99cf55d70ef8fa4 Mon Sep 17 00:00:00 2001 From: Pierre Le Marre Date: Fri, 28 Nov 2025 10:28:58 +0100 Subject: [PATCH 1/4] protocol: Add keymap version negotiation to wl_keyboard Enable to negotiate the keymap format in `wl_keyboard`, in order to introduce keymap formats which are backward-incompatible. The keymap format negotiation is made mandatory from this new version of the `wl_keyboard` interface. - Added the `wl_keyboard::set_supported_keymap_formats` request - Added the `wl_keyboard::error` enum to handle error triggered by the previous request. - Added `xkb_v2` to the `wl_keyboard::keymap_format` enum, to denote the keymap format v2 provided by libxkbcommon. Signed-off-by: Pierre Le Marre --- protocol/wayland.xml | 45 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 41 insertions(+), 4 deletions(-) diff --git a/protocol/wayland.xml b/protocol/wayland.xml index 5a6a189d..b204f133 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -1906,7 +1906,7 @@ - + A seat is a group of keyboards, pointer and touch devices. This object is published as a global during start up, or when such a @@ -2040,7 +2040,7 @@ - + The wl_pointer interface represents one or more input devices, such as mice, which control the pointer location and pointer_focus @@ -2453,7 +2453,7 @@ - + The wl_keyboard interface represents one or more keyboards associated with a seat. @@ -2467,6 +2467,18 @@ By default, the active surface is null, the keys currently logically down are empty, the active modifiers and the active group are 0. + + Since version 11, clients must first negotiate the keymap format in order + to receive any keyboard event: + + 1. Client sends a set_supported_keymap_formats request, + 2. Server responds with either: + + - a keymap event, with the corresponding keymap_format being supported + by both the server and the client; the server is advised to use the + format with most features. + - a no_supported_keymap_format error if no common supported format is + found. @@ -2477,6 +2489,8 @@ + @@ -2632,9 +2646,32 @@ + + + + + + Inform the server of the keymap formats supported by the client, in + ascending order. + + If none of the formats is supported by the server, then a + no_supported_keymap_format error is triggered. + + Otherwise the server selects one of the provided format that it supports + itself and may start to send keyboard events. It is advised, but not + mandatory, to select the format with most features. + + + + + + + - + The wl_touch interface represents a touchscreen associated with a seat. From 715d52d40f332538d8b65aac5cefad62694527e1 Mon Sep 17 00:00:00 2001 From: Pierre Le Marre Date: Fri, 28 Nov 2025 12:13:15 +0100 Subject: [PATCH 2/4] Fixes after @mahkoh review Signed-off-by: Pierre Le Marre --- protocol/wayland.xml | 42 ++++++++++++++++++++++++++---------------- 1 file changed, 26 insertions(+), 16 deletions(-) diff --git a/protocol/wayland.xml b/protocol/wayland.xml index b204f133..e53b0197 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -2038,6 +2038,32 @@ + + + + + The ID provided will be initialized to the wl_keyboard interface + for this seat. + + This is an alternative to get_keyboard that informs the server of the + keymap formats supported by the client. The server selects one of the + provided format that it supports itself and may start to send keyboard + events. It is advised, but not mandatory, to respect the client’s order + of preference of the formats. + + TODO: what if none of the format is supported? + + This request only takes effect if the seat has the keyboard + capability, or has had the keyboard capability in the past. + It is a protocol violation to issue this request on a seat that has + never had the keyboard capability. The missing_capability error will + be sent in this case. + + + + + @@ -2649,22 +2675,6 @@ - - - Inform the server of the keymap formats supported by the client, in - ascending order. - - If none of the formats is supported by the server, then a - no_supported_keymap_format error is triggered. - - Otherwise the server selects one of the provided format that it supports - itself and may start to send keyboard events. It is advised, but not - mandatory, to select the format with most features. - - - - From feb5dc63085820b4874dd95f11ad2940dccef4e2 Mon Sep 17 00:00:00 2001 From: Pierre Le Marre Date: Tue, 2 Dec 2025 15:23:20 +0100 Subject: [PATCH 3/4] Add the wl_keyboard::frame event Introduce the wl_keyboard::frame event to end of a set of events that logically belong together, similarly to other frame events, e.g. wl_pointer::frame. The motivation is to enable keymap negotiation: - Compositor sends multiple consecutive wl_keyboard::keymap events, each one with a different format, then a wl_keyboard::frame event. - Clients select the most appropriate format to parse, if any. Signed-off-by: Pierre Le Marre --- protocol/wayland.xml | 77 +++++++++++++++++++------------------------- 1 file changed, 34 insertions(+), 43 deletions(-) diff --git a/protocol/wayland.xml b/protocol/wayland.xml index e53b0197..b8426384 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -2037,33 +2037,6 @@ use the seat object anymore. - - - - - - The ID provided will be initialized to the wl_keyboard interface - for this seat. - - This is an alternative to get_keyboard that informs the server of the - keymap formats supported by the client. The server selects one of the - provided format that it supports itself and may start to send keyboard - events. It is advised, but not mandatory, to respect the client’s order - of preference of the formats. - - TODO: what if none of the format is supported? - - This request only takes effect if the seat has the keyboard - capability, or has had the keyboard capability in the past. - It is a protocol violation to issue this request on a seat that has - never had the keyboard capability. The missing_capability error will - be sent in this case. - - - - - @@ -2493,18 +2466,6 @@ By default, the active surface is null, the keys currently logically down are empty, the active modifiers and the active group are 0. - - Since version 11, clients must first negotiate the keymap format in order - to receive any keyboard event: - - 1. Client sends a set_supported_keymap_formats request, - 2. Server responds with either: - - - a keymap event, with the corresponding keymap_format being supported - by both the server and the client; the server is advised to use the - format with most features. - - a no_supported_keymap_format error if no common supported format is - found. @@ -2528,6 +2489,11 @@ From version 7 onwards, the fd must be mapped with MAP_PRIVATE by the recipient, as MAP_SHARED may fail. + + From version 11 onwards, multiple wl_keyboard.keymap events may be sent + within the same frame, each one with a different keymap format. Clients + should select at most one of these events. Clients are advised to select + the format with most supported features. @@ -2675,10 +2641,35 @@ - - - + + + Indicates the end of a set of events that logically belong together. + A client is expected to accumulate the data in all events within the + frame before proceeding. + + All wl_keyboard events before a wl_keyboard.frame event belong + logically together. For example, multiple wl_keyboard.keymap event may + be sent — each one with a different format — and finally a + wl_keyboard.frame event. The client may use this information to select + the keymap format that fits best. + + A wl_keyboard.frame event is sent for every logical event group, + even if the group only contains a single wl_keyboard event. + Specifically, a client may get a sequence: key, frame, key, modifier, + frame, key, frame. + + The wl_keyboard.enter and wl_keyboard.leave events are logical events + generated by the compositor and not the hardware. These events are + also grouped by a wl_keyboard.frame. When the keyboard focus moves from + one surface to another, a compositor should group the + wl_keyboard.leave event within the same wl_keyboard.frame. + However, a client must not rely on wl_keyboard.leave and + wl_keyboard.enter being in the same wl_keyboard.frame. + Compositor-specific policies may require the wl_keyboard.leave and + wl_keyboard.enter event being split across multiple wl_keyboard.frame + groups. + + From 56e62888a3a2f0691f8d2240e707866c21c567c3 Mon Sep 17 00:00:00 2001 From: Pierre Le Marre Date: Thu, 11 Dec 2025 09:01:33 +0100 Subject: [PATCH 4/4] Fixes after @whot review Signed-off-by: Pierre Le Marre --- protocol/wayland.xml | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/protocol/wayland.xml b/protocol/wayland.xml index b8426384..b0cc0a22 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -2491,9 +2491,11 @@ the recipient, as MAP_SHARED may fail. From version 11 onwards, multiple wl_keyboard.keymap events may be sent - within the same frame, each one with a different keymap format. Clients - should select at most one of these events. Clients are advised to select - the format with most supported features. + within a single frame, each representing the same keymap in a distinct + keymap format. Clients must select and process at most one of these + keymaps, ideally the one offering the greatest feature coverage, while + immediately closing the file descriptors corresponding to unused + keymaps. Keymap events sent in a later frame replace the active keymap. @@ -2515,6 +2517,9 @@ Clients should not use the list of pressed keys to emulate key-press events. The order of keys in the list is unspecified. + + From version 11 onwards this event is part of a wl_keyboard.frame + logical event group. See wl_keyboard.frame for details. @@ -2533,6 +2538,9 @@ defaults. The compositor must not send this event if the active surface of the wl_keyboard was not equal to the surface argument immediately before this event. + + From version 11 onwards this event is part of a wl_keyboard.frame + logical event group. See wl_keyboard.frame for details. @@ -2580,6 +2588,9 @@ key state when a wl_keyboard.repeat_info event with a rate argument of 0 has been received. This allows the compositor to take over the responsibility of key repetition. + + From version 11 onwards this event is part of a wl_keyboard.frame + logical event group. See wl_keyboard.frame for details. @@ -2602,6 +2613,9 @@ In the wl_keyboard logical state, this event updates the modifiers and group. + + From version 11 onwards this event is part of a wl_keyboard.frame + logical event group. See wl_keyboard.frame for details. @@ -2632,6 +2646,9 @@ This event can be sent later on as well with a new value if necessary, so clients should continue listening for the event past the creation of wl_keyboard. + + From version 11 onwards this event is part of a wl_keyboard.frame + logical event group. See wl_keyboard.frame for details. @@ -2650,8 +2667,8 @@ All wl_keyboard events before a wl_keyboard.frame event belong logically together. For example, multiple wl_keyboard.keymap event may be sent — each one with a different format — and finally a - wl_keyboard.frame event. The client may use this information to select - the keymap format that fits best. + wl_keyboard.frame event. See the wl_keyboard.keymap event for more + details. A wl_keyboard.frame event is sent for every logical event group, even if the group only contains a single wl_keyboard event.