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]
Type=Application
Name=My experimental OSK
Exec=my-experimental-osk
OnlyShowIn=Phosh;
Icon=input-keyboard-symbolic
NoDisplay=true
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.