phosh-osk-stub is an alternative on screen keyboard (OSK) for Phosh featuring several methods of text auto correction and completion. In the following we look at the different options available and how to use and configure them:
For any form of completion to be available, the application that features the text input needs to
support the text-input-unstable-v3 Wayland protocol. If that isn’t available phosh-osk-stub
will enter a fall back mode where it acts more like a physical keyboard (via the virtual-keyboard
Wayland protocol) and disable completion. In this case the completion bar (the area above the keys
showing the completion entries) will be hidden. Thankfully major toolkits likt GTK4, GTK3, Qt6
and lots of others support the text-input-unstable-v3 protocol nowadays so this is not
much of an issue. Note that Chromium/Electrion based apps only recently gained support so you
might still hit apps that don’t support this but let’s from here on assume that the application
featuring the text input field does support it.
There’s two areas of configuration: The completion mode (when should the OSK perform auto completion / correction) and the type of completer used (which engine powers the completion / correction).
Let’s look at the completion mode first:
Completion Mode Link to heading
Besides having any form of auto completion disabled there’s two other modes which can be configured
via the sm.puri.phosh.osk completion-mode gsetting or via the Mobile Settings app:
Opportunistic Completion Link to heading
Opportunistic completion is the default mode. It means that text completion in the on screen keyboard (OSK) is enabled whenever the application requests it. So if the applications thinks completion isn’t necessary screen estate can be saved by not showing any word completions and if there’s a field where the user enters larger amounts of text the app can enable it speeding up text input.
Requesting completion happens via the completion hint in the text-input-unstable-v3 protocol.
In GTK applications sending this hint can be enabled by setting the
GTK_INPUT_HINT_WORD_COMPLETION
on the input widget (e.g. a GtkEntry or GtkSourceView).
Here’s a list of
examples that show how applications can be updated to support this. It is usually a
one line change so whenever your favorite app doesn’t enable completion in the on screen keyboard it
might be worth sending a patch to the app developer.
Toggle via OSK Menu Link to heading
The other completion mode is “Toggle via OSK menu”. When enabled you get an entry in the OSKs popover menu to enable and disable completion manually. This mode is meant as a workaround when an app doesn’t turn on completion for you. Please consider fixing the application in those cases too.
Completers Link to heading
Now that we’ve sorted out when completion is enabled, the other interesting bit is how the completion is performed. phosh-osk-stub allows for pluggable completers so you can easily add your own. These are the current ones we have:
The Hunspell Completer Link to heading
This completer is currently the default. It uses hunspell’s dictionaries to guess what you’re trying to type. For that it doesn’t take any surrounding text into account, it just looks at the word you’re currently typing. This helps to spot typos and is a good fit if you don’t want the OSK suggest you what to type.
Supported Languages Link to heading
Hunspell dictionaries are ubiquitous, Linux distributions ship them by default so chances are
high that you just need to install the dictionaries for the language you’re using via your
distributions package management, e.g. Debian ships more than fifty of them in the
hunspell-<lang> packages.
The Presage Completer Link to heading
This completer is currently the recommended one. It uses the presage library for text
prediction. For that it takes the surrounding text into account to predict the next word allowing
you to fast type as it will adjust to your inputs over time. Everything happens locally on your
phone and you can remove all learned data by removing the files in the
~/.local/share/phosh-osk-stub/ directory.
Supporting more Languages Link to heading
In order for text prediction to suggest something useful it needs to be “trained” which means we need to build tables giving the probability of a word following another word or a combination of words (the n-gram tables). Upstream presage stores these probabilities in a sqlite database (there’s forks around that use different formats). Since this is a time consuming process we don’t want to do that on the phone but rather ship some prepacked data for different languages.
This means to support a language we
- need to get some training data
- build the databases
- make it simple to ship it to the user
For phosh-osk-stub we’re using Wikipedia dumps to build the tables. We’ve then added a script to be used on the phone that downloads the database, wraps them in a distribution package and installs it. So e.g. in order to add completion data for Swedish on your device you’d run this on a Debian based system:
# Download the n-gram table for Swedish and build a Debian package from it
phosh-osk-data-packager --language=se
# Install the generated package
sudo dpkg -i phosh-osk-data-se_0.42.0-1_all.deb
phosh-osk-data-packager currently supports the Debian packaging format but it can easily be extended to support other package managers (please send patches!). You can find the currently supported languages here. If a language is missing let us know and we can eventually add it.
Special Purpose Completers Link to heading
The hunspell and presage completers are the most widely used ones but there are more:
The Fzf Completer Link to heading
The fzf completer was the first one added to phosh-osk-stub. It uses the
fzf fuzzy matcher to complete on the system’s work list. It’s
mostly useful for experiments and to have a simple reference implementation for people wanting
to add more completers. You can enable the fzf completer with
gsettings set sm.puri.phosh.osk.Completers default fzf
The Pipe Completer Link to heading
The pipe completer allows you to configure the program that provides the completions. The
program you configure will get the currently typed word on standard input (stdin) and needs to
emit the current list of completions on standard output (stdout). This allows you to build your
own completers without modifying phosh-osk-stub itself. One such program being used is
swipeguess. See this video for a short
demo. You can enable the pipe completer with
gsettings set sm.puri.phosh.osk.Completers default pipe
and in order to set the provide the script to run use
gsettings set sm.puri.phosh.osk.Completers.Pipe command "<yourcommand>"
and replace <yourcommand> with the script that takes the input on stdin and emits the
completions on stdout. The completions should be newline ('\n') separated.
The Varnam Completer Link to heading
Finally there’s the varnam completer which uses govarnam transliteration engine to make it possible to enter Indian languages. Transliteration here means that you type English letters and it then completes the word in e.g. Malayalam script. See this video by govarnam’s upstream author for more details.
Govarnam relies on varnam-scheme-<script> data for the transliteration. Once that package is
installed there’s no special configuration necessary, You can just select Malayalam (via varnam)
from the list of OSK layouts in mobile settings:
Outlook Link to heading
So what’s coming up in the future? One thing we’d like to add in the future is a DBus based completer which would be similar to pipe but would use DBus so we can provide more information like surrounding text. A new thing we’ve recently added is the concept of “supplementary” completers that can provide additional results like emojis. This could be extended to e.g. address book entries or recently used file names. Lots of fun projects ahead, if you want to join in, let us know.
Here’s a short video showing text completion with presage and govarnam in action: