--- name: "phosh-osk-stub" section: "1" platform: "linux" package: "phosh-osk-stub" version: "0.46.0-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/phosh-osk-stub" --- # phosh-osk-stub(1) An on screen keyboard for Phosh ## NAME phosh-osk-stub - An on screen keyboard for Phosh ## SYNOPSIS ``` phosh-osk-stub [OPTIONS...] ``` ## DESCRIPTION **phosh-osk-stub** is an on screen keyboard (OSK) for phosh. It can replace Phosh's default keyboard **squeekboard(1)**. **phosh-osk-stub** has two modes of operation. If the application supports and uses **text-input-unstable-v3** the Wayland compositor will use the **input-method-unstable-v2** protocol to interact with the OSK. This allows it to - • automatically unfold the keyboard - • handle text prediction / correction via preedit and surrounding text - • automatically switch to special layouts like to terminal by input hints sent from the application This is the preferred mode of operation. For legacy applications like e.g. Electron applications the OSK falls back to a virtual keyboard mode (basically emulating key presses). This means that it e.g. can't unfold automatically or support completion. It will hence hide the completion bar in that mode of operation. ## OPTIONS - **-h, --help** Print help and exit - **--replace** Try to grab the *sm.puri.OSK0* DBus interface, even if it is already in use by another keyboard. - **--allow-replacement** (Temporarily) Give up the *sm.puri.OSK0* DBus name if another OSK requests it. This also unregisters the Wayland input-method-v1 so another OSK can act as input method. If the name becomes available again it is grabbed again and phosh-osk-stub registers itself as input method again. - **-v, --version** Show version information ## SETUP In order to be used by Phosh as OSK, phosh-osk-stub needs to be started from the */usr/share/applications/sm.puri.OSK0.desktop* desktop file. On Debian systems this can be achieved by running ``` update-alternatives --config Phosh-OSK ``` as root and selecting the entry ending in **sm.puri.Phosh.OskStub.desktop**. ## CONFIGURATION **phosh-osk-stub** is configured via **GSettings**. This includes configuration of the loaded layouts from **org.gnome.desktop.input-sources** via the **sources** and **xkb-options** keys, whether the OSK is enabled at all via the **org.gnome.desktop.a11y.applications**'s **screen-keyboard-enabled** and configuration of word completion (see below). For the keyboard to fold and unfold automatically make sure **org.gnome.desktop.interface** **gtk-im-module** is set to the empty string (*''*). This is the default in most distributions. If unsure check via: ``` gsettings get org.gnome.desktop.interface gtk-im-module ``` ### WORD COMPLETION **phosh-osk-stub** has support for word completion and correction via various completers (see below). It has several modes of operation represented by flags that can be combined: - • *off*: no word completion - • *manual*: enable and disable completion via an option in the language popover - • *hint*: enables and disables completion based on the text input's *completion* hint. Valid settings are *off*, *manual*, *hint* and *manual+hint*. These can be enabled configured via the *gsettings* command: ``` # off gsettings set sm.puri.phosh.osk completion-mode "[]" # manual gsettings set sm.puri.phosh.osk completion-mode "['manual']" # hint gsettings set sm.puri.phosh.osk completion-mode "['hint']" # manual+hint gsettings set sm.puri.phosh.osk completion-mode "['manual','hint']" # Reset to default (off) gsettings reset sm.puri.phosh.osk completion-mode ``` Note that completion is always disabled when - • No usable completers are found on startup - • Terminal or emoji layout is in use - • The application doesn't support text-input so **phosh-osk-stub** is falling back virtual-keyboard mode. ### AVAILABLE COMPLETERS The available completers depend on how **phosh-osk-stub** was built. Available are currently at most - • **hunspell**: word correction based on the hunspell library - • **presage**: (experimental) word prediction based on the presage library - • **pipe**: completer using a pipe - • **fzf**: completer based on fzf command line tool. Useful for experiments) - • **varnam**: completer using govarnam for Indic languages The default word completer is selected via the **sm.puri.phosh.osk.Completers** **default** GSetting. ``` gsettings set sm.puri.phosh.osk.Completers default hunspell ``` You need to restart **phosh-osk-stub** for the new default completer to become active. ### TEXT CORRECTION USING HUNSPELL The hunspell completer needs dictionaries and affix files in **/usr/share/hunspell\`. Most importantly \`\`/usr/share/hunspell/en\_US.dic** and **/usr/share/hunspell/en\_US.aff** are required as fallback when no matching dictionary for the current layout is found. ### TEXT COMPLETION USING PRESAGE The presage based completer is considered experimental as there are some known issues when interacting with GTK4 applications. For the presage based completer to work you need a model file in */usr/share/phosh/osk/presage/*. Likely your distribution already ships one with the presage library. You can simply symlink it there. Models for more languages can be found in\ \ ### TEXT COMPLETION USING PIPE This completer feeds the current input word (preedit) to an executable file and expects the executable to output possible completions on stdout. The executable to invoke is configured via the **sm.puri.phosh.osk.Completers.Pipe** **command** GSetting. It defaults to **cat**. This can be used to experiment with different completion patterns without having to modify **phosh-osk-stub** itself. ``` gsettings set sm.puri.phosh.osk.Completers.Pipe command 'wc -c' ``` You need to restart **phosh-osk-stub** for the new command to become active. A commonly used executable is swipeGuess: \ ### TEXT COMPLETION USING VARNAM This completer feeds the current input word (preedit) to govarnam for easy input of Indic languages. For the completer to work it needs govarnam and the language schema files installed. Please refer to the govarnam documentation. Note that while you can enable govarnam as default completer this is not recommended. Instead enable it for a specific language via the *sources* gsettings: ``` gsettings set org.gnome.desktop.input-sources sources "[('xkb', 'us'), ('ibus', 'varnam:ml'), ('ibus', 'varnam:ta')]" ``` The above would only enable govranam for Malayalam and Tamil while the English US layout would still use the default completer. ### TERMINAL SHORTCUTS **phosh-osk-stub** can provide a row of keyboard shortcuts on the terminal layout. These are configured via the **shortcuts** GSetting ``` gsettings set sm.puri.phosh.osk.Terminal shortcuts "['a', 'e', 'r']" ``` For valid values see documentation of *gtk\_accelerator\_parse()*: \ One can also add plain **\** and **\** keys. These then act as latched keys until the next regular key is pressed. ### IGNORING ACTIVATION For some applications you might not want to unfold the OSK when the application requests it. This can e.g. be useful when you usually read what the application displays (and hence want to use as much as screen space as possible) but the application focuses a text entry. By adding the application's app-id to the **ignore-activation** list you can prevent the automatic unfold. The OSK can still be unfolded by other means (e.g. via the DBus API or the OSK button in Phosh). To determine an applications app-id you can use the **foreign-toplevel** command. ``` gsettings set sm.puri.phosh.osk ignore-activation "['org.gnome.Calculator']" ``` ### HARDWARE KEYBOARDS By default the on screen keyboard will now show if it detects a connected hardware keyboard. To make it show nevertheless use ``` gsettings set sm.puri.phosh.osk ignore-hw-keyboards false ``` ### KEY PRESS By default moving the finger while pressing a character will cancel the gesture and not input it. This can be changed by enabling *key-drag*: ``` gsettings set sm.puri.phosh.osk osk-features "['key-drag']" ``` ## ENVIRONMENT VARIABLES **phosh-osk-stub** honors the following environment variables for debugging purposes: - • **POS\_DEBUG**: A comma separated list of flags: - • **force-show**: Ignore the *screen-keyboard-enabled* GSetting and always enable the OSK. This GSetting is usually managed by the user and Phosh. - • **force-completion**: Force text completion to ignoring the *completion-mode* GSetting. - • **POS\_TEST\_LAYOUT**: Load the given layout instead of the ones configured via GSetting. - • **POS\_TEST\_COMPLETER**: Use the given completer instead of the configured ones. The available values depend on how phosh-osk-stub was built (see above). - • **G\_MESSAGES\_DEBUG**, **G\_DEBUG** and other environment variables supported by glib. \ - • **GTK\_DEBUG** and other environment variables supported by GTK, see\ \ ## EXAMPLES Use **swipeGuess** for swipe input: ``` gsettings set sm.puri.phosh.osk.Completers default pipe gsettings set sm.puri.phosh.osk.Completers.Pipe command "swipeGuess /usr/local/share/swipeGuess/words/words-qwerty-en" gsettings set sm.puri.phosh.osk osk-features "['key-drag']" ``` ## SEE ALSO **[phosh(1)](/phosh/1.md)** **squeekboard(1)** **[text2ngram(1)](/text2ngram/1.md)** **[gsettings(1)](/gsettings/1.md)** **[hunspell(5)](/hunspell/5.md)** **swipeGuess(1)**