One of the central pieces on small screens without physical keyboards it the on screen keyboard (OSK). Ever so often people want to experiment with alternative keyboards to e.g. explore alternative ways of text input (via speech or swipe) or look into how to support languages and scripts that aren’t supported by default.

Requirements Link to heading

Due to Phosh’s modular design (the on screen keyboard runs in a separate process) exchanging the OSK is simple. Here’s the required (must) and recommended (should) interfaces an OSK should provide:

1. Wayland Link to heading

First of all you likely want to send input from the OSK (via the Wayland compositor) to applications. For that the OSK should implement support for the virtual-keyboard-unstable-v1 and input-method-unstable-v2 Wayland protocols. That is not enforced though as we might support other protocol variants in the future.

The OSKs usually use the wlr-layer-shell protocol to show the OSKs surface that contains the keys. However this again is not a requirement so e.g. a “OSK” that uses the microphone and is just a speech processor is entirely possible.

You can either add support for the wlr-layer-shell protocol entirely yourself or you can use a library that hides most of the details. One such library is gtk4-layer-shell.

2. The desktop file Link to heading

The OSK must provide a sm.puri.OSK0.desktop desktop file. This is how the OSK gets spawned when the session starts.

This is similar to what is used with applications:

[Desktop Entry]
Name=My experimental OSK

System installed desktop files are usually in /usr/share/applications. If you want to temporarily test another OSK you can either put it into /usr/local/share/applications or .local/share/applications so it will be picked up before the default keyboard in /usr/share/applications/sm.puri.OSK0.desktop.

3. Session registration Link to heading

The OSK must register to gnome-session with an app-id of sm.puri.OSK0. This allows gnome-session to figure out when the OSK crashed and restart it and if that happens too often to show a failure message that this important component of the session isn’t working.

As with other components registering to the session you invoke RegisterClient DBus method. See here for an example.

If you just want to quickly try out an existing OSK you can work around this requirement by removing sm.puri.OSK0 from /usr/share/gnome-session/sessions/phosh.session and starting it manually (e.g. by symlinking the above desktop file to /etc/xdg/autostart or .config/autostart). This is not recommended though.

4. DBus protocol Link to heading

The OSK should implement the sm.puri.OSK0 DBus protocol. The interface ensures that the keyboard can be folded/unfolded “on request” (e.g. via phosh’s home bar). Again: for experimentation this can be skipped.

5. Settings Link to heading

The OSK should only show when the

org.gnome.desktop.a11y.applications screen-keyboard-enabled

gsetting is set to true. This allows the “Enable on Screen keyboard” setting in GNOME Settings to work without surprises.

Distribution considerations Link to heading

From a Linux distribution point of view you usually can’t ship the same file (like /usr/share/applications/sm.puri.OSK0.desktop) in multiple packages and have them installed at the same time. So the simplest way is to have all packaged OSKs conflict with each other allowing only one to be installed at any given time. This makes switching for users inconvenient though.

Debian based distribution however can use a mechanism called alternatives that makes it possible to have packages provide the same files to allow users to switch between different implementations of the same interface. For Phosh’s on screen keyboards there’s an alternative called Phosh-OSK that can be used:

# update-alternatives --config Phosh-OSK
There are 2 choices for the alternative Phosh-OSK (providing /usr/share/applications/sm.puri.OSK0.desktop).

  Selection    Path                                                     Priority   Status
  0            /usr/share/applications/sm.puri.Squeekboard.desktop       50        auto mode
  1            /usr/share/applications/sm.puri.Squeekboard.desktop       50        manual mode
* 2            /usr/share/phosh-osk-stub/sm.puri.Phosh.OskStub.desktop   30        manual mode

In the above the user can switch between the default OSK squeekboard and phosh-osk-stub (an experimental OSK that was initially a stub for debugging input and is hence somewhat oddly named). Selecting 1 would make the /usr/share/applications/sm.puri.OSK0.desktop point to sm.puri.Squeekboard.desktop which would run squeekboard on the next login, or to sm.puri.Phosh.OskStub.desktop (by pressing 2) which would run phosh-osk-stub at the next login.

So if you package an OSK for a Debian based distro and it implements the above interfaces hooking into that mechanism is recommended.

If non-Debian based distributions handle this in a similar way, please let us know.