October 27, 2016 - Bryce Harrington

The Basics of Input Methods in Weston

Wayland provides an optional protocol, zwp_input_method, for defining alternate ways of sending keystrokes and mouse activity to clients. This could be things such as an onscreen keyboard or a popup for building Korean characters. The design of the protocol allows for different kinds of input methods to be made available via modular plugins, allowing them to be coded as discrete client applications, separate from the compositor’s core.

The Wayland project maintains a reference compositor named Weston that provides implementations of the various protocols for demonstrative purposes, including two implementations of the zwp_input_method protocol. One input method, weston-keyboard, manages an on-screen keyboard that pops up at the bottom of the screen, similar to on-screen keyboards typically seen on touch-based mobile devices. The other input method, weston-simple-im, enables a compose key functionality.

The user can configure which input method to use via their weston.ini file. No more than one input method can be registered with the Weston compositor at a time, and it cannot be changed at runtime.

What Does it Take to Create a New Input Method?

Input method modules are essentially just Weston clients. So, a trivial input method resembles a trivial Weston client with input method protocol sprinkled throughout:

The above implements a bare minimum input method client, that you can then expand to hang on whatever additional functionality you need.  It makes use of Toytoolkit, which is Weston’s simple widget library provided by the API in client/window.h, to handle making the connection to the display and setting up raw input handling.

All Wayland applications need to register the set of protocols they are interested in receiving from the compositor.  In this example, you can see this in the global_handler function, which registers the zwp_input_method protocol.  Part of registering a protocol with the compositor is to hook up the client-side routines that will be handling the API operations, typically called listeners; for our zwp_input_method protocol we are just registering two functions: one to activate the input method (input_method_activate()), another to deactivate it (input_method_deactivate()).  We set up pointers to these two functions when creating the input_method_listener structure, and then register it via the zwp_input_method_v1_add_listener() call.

Expanding this quick sketch of an input method into an actually useful method would involve adding more protocols (like zwp_input_pane) and registering more functions for the relevant API.  A logical next step would be to associate input handlers: a keyboard handler if your input method serves to translate key codes (weston-simple-im is an example of this approach), or perhaps button and touch events for an input method that provides an input panel (see weston-keyboard’s on-screen keyboard as an example). If your input method involves an input panel, code will be needed to handle redraw requests and manage the client’s visual state.

How are Input Methods Useful?

What kinds of input methods might one wish to create? One of the most common and traditional uses for input methods is to enter characters for non-Latin scripts such as for the Chinese, Japanese, Korean, Vietnamese, and Indic languages. Even for a given language, there can be different methods for entering characters, such as Cangjie and Pinyin for Chinese. Weston currently does not support any of these languages, so input methods for handling one or more of them would be useful additions.

But input methods can also be used with Latin scripts, like English, to provide various specialized behaviors. For example, automatic capitalization, automatic punctuation, spelling correction, and word suggestion are all possibilities. They can also support alternative forms of input entry, such as handwriting recognition, voice typing, and voice recognition.

Bryce Harrington

About Bryce Harrington

Bryce Harrington is a Senior Open Source Developer at the Samsung Open Source Group focusing on Open Source Graphics. Prior to Samsung, he lead Canonical, Ltd.'s Ubuntu X.org team, and focused on stabilization of the graphics and input infrastructures for the Ubuntu distribution. Bryce began his career in the aerospace industry as a spacecraft propulsions engineer at The Aerospace Corporation, Hughes Space and Communications and TRW. Later, he joined the Open Source Development Labs as a Senior Performance Engineer working on NFSv4 testing and development of automated test systems. He is a founder and developer of the Inkscape project and serves as Chairman of the Inkscape Board. Bryce has a BS-AE from USC and an MS-AE from Caltech.

Image Credits: Kristian Høgsberg

Development / Uncategorized / Wayland input / keyboard / Tutorial / Weston /

Leave a Reply

Your email address will not be published. Required fields are marked *

Comments Protected by WP-SpamShield Anti-Spam