QtCS2021 - Wayland text-input-unstable-v4 protocol

From Qt Wiki
Jump to: navigation, search

Session Summary

The next iteration of the text-input protocol is currently in specification phase. Qt is lacking in this area, and we should collaborate with the upstream project to make sure we get it right. This is a session to discuss the protocol and get everyone on the same page.

Session Owners

  • Eskil Abrahamsen Blomfeldt (eskil.abrahamsen-blomfeldt@qt.io)



The text input protocol is part of the support for complex input methods on Wayland. This protocol communicates between the compositor and applications that need text input. (There is a separate input method protocol for communicating between the compositor and out-of-process input methods. That protocol is out of scope for this discussion.)

QtWayland currently supports text_input_unstable_v2. This version has only been adopted by Qt and kwin. The current version is  text_input_unstable_v3, which does not have all of the features of v2. Qt does not currently support v3.

There are bugs in the current v2 implementation in Qt, which cause problems for the Qt virtual keyboard. In order to provide a working solution in a timely manner, Qt has added a new protocol qt_text_input_method_v1, which maps directly to the QInputMethod API. This protocol is intended for use in embedded systems where the whole stack is implemented with Qt. Qt still needs to support a standardized text input protocol in order to interoperate with other software, both on the desktop and in the embedded space.

Input V4

There is currently a process to define v4 of the text input protocol:

https://gitlab.freedesktop.org/wayland/wayland-protocols/-/issues/39 [Introduction to input method support in Wayland]

https://gitlab.freedesktop.org/wayland/wayland-protocols/-/issues/40 [Requirements]

The starting point for text-input-v4 is text-input-v3.

Qt currently relies on the client sending an acknowledge, in order to synchronize server and client side state. This makes it possible for the compositor to connect a state change from the client to a specific input method event, and thus distinguishing between a confirmation that the event has been processed and the client making a change on its own initiative. (The QInputMethod API is written on the assumption that the communication is synchronous, and that state changes take effect immediately.)

Q: Why does Qt need sync in both directions? → Qt will try to implement V3, and see if it works without this sync.

The principle behind the current protocol: Make software fit protocol, rather than a messy protocol that fits all existing software.

Other protocols that currently exist

-> text input actions

Features that are missing in v3

Text direction. This is needed to decide whether the cursor is placed at the beginning or end of the field, and is otherwise impossible to guess if there is no text yet.

Language. In some cases, the language is needed to determine the font, since the same Unicode character will be shown using different glyphs depending on the language.

Preedit cursor position and preedit styling. These are needed by existing input methods today. -> Open an issue for this.

Sending raw key codes. This is needed for terminal emulators and legacy applications. (Key codes can also be sent using wl_keyboard.)

Kai Uwe Broulik : just realized you probably also want to know "is password field", independent of input panel type, so inputtype should probably stay in the main procotol :)

Keyboard rectangle. This is needed to position the text input field so the on-screen keyboard does not overlap the text. (Should this be in a Separate protocol?) https://invent.kde.org/teams/plasma-mobile/issues/-/issues/23

Input method active/inactive: Does client really need to know? Arguably it is the compositor/input method that should decide how to enable/disable input when the client reports whether text input is active

Fundamental question: what is the basic principle for deciding what goes into the protocol?

Suggestion: The text input protocol should not care about the type of keyboard. Anything that makes a distinction between a physical keyboard and an on-screen keyboard should be put in other protocols.

Argument against: It will take more time to finish functionality with multiple separate protocols

Argument for: The text input protocol will take less time if we don't need to figure out the extra functionality which needs additional research


Most important message from the text-input-v4 project: look at the merge requests for the current state of the protocol.

Qt will finish the ongoing proof-of-concept v3 implementation, and then try the current state of v4.

Day-to-day communication and feedback should be done on the wayland-protocols issues on gitlab.