vboard

A virtual keyboard for GNU/Linux with Wayland support on KDE Plasma, plus GNOME support via Xwayland, and Ctrl, Alt, Tab and Super (Meta/Win) keys.

Wayland-compatible on KDE Plasma; also works on GNOME via Xwayland.

Overview

vboard is a lightweight, customizable virtual keyboard designed for Linux desktop systems. It runs as a Wayland-compatible on-screen keyboard on KDE Plasma, and also works on GNOME by falling back to Xwayland. It provides a full on-screen keyboard with modifier keys such as Ctrl, Alt, and Super (Meta/Win), which makes it especially useful for:

• Touchscreen devices without physical keyboards
• Systems with malfunctioning physical keyboards
• Accessibility needs
• Kiosk applications

The keyboard supports customizable colors, opacity settings, and can be easily modified to support different layouts.

Features

• Customizable appearance: Change background color and opacity
• Persistent settings: Configuration is saved between sessions
• Modifier key support: Provide Ctrl, Alt, Tab and Super (Meta/Win) keys
• Desktop compatibility: Native Wayland-friendly behavior on KDE Plasma, with GNOME support via Xwayland fallback
• Hold for repetitive clicks: Keep holding the mouse button to trigger repeated clicks
• Word suggestions: Offers completions from an installed Hunspell dictionary while you type with vboard
• Gesture typing: Swipe across letter keys and vboard will decode the path into a word
• Compact interface: Headerbar with minimal controls to save screen space
• Tray icon support: Keeps vboard running in the background and you can quickly reopen it when needed
• uinput input backend: Injects keys through Linux uinput

Implementation notes for gesture typing are documented in GESTURE_TYPING.md.

Installation

Ubuntu/Debian: .deb package

Download the latest .deb from the GitHub Releases page for a lightweight on-screen keyboard with modifier keys such as Ctrl, Alt, Shift, and Super, then install it with:

sudo apt install ./vboard_*.deb

DO NOT use dpkg. Please use apt. Otherwise, it will not work.

The package post-install step sets up uinput and installs the udev rule needed for desktop-session access to /dev/uinput.

Log out and back in, or reboot, after installation.

PPA for Ubuntu

You can also use the following PPA in Ubuntu. Run the following commands one by one:

sudo add-apt-repository ppa:apandada1/vboard
sudo apt update
sudo apt install vboard

Restart for changes to take effect.

Ubuntu/Debian: install from source

For the latest unreleased changes on Ubuntu and Debian-based systems, use the automated setup script:

git clone https://github.com/archisman-panigrahi/vboard.git
cd vboard
sudo bash setup-ubuntu-debian.sh

This script will handle all setup steps including dependency installation, uinput configuration, and system-wide installation. A system restart is recommended after installation.

Manual installation on other distros

For Debian/Ubuntu, Fedora, Arch, and other distributions, install the dependencies manually and then build with Meson.

1. Install dependencies

For Debian/Ubuntu-based distributions:

sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-3.0 python3-uinput gir1.2-ayatanaappindicator3-0.1 meson ninja-build --no-install-recommends

Optional for word suggestions:

sudo apt install hunspell-en-us

For Fedora-based distributions:

sudo dnf install python3-gobject python3-cairo gtk3 python3-uinput libappindicator-gtk3 meson ninja-build

Optional for word suggestions:

sudo dnf install hunspell-en-US

For Arch-based distributions:

sudo pacman -S python-gobject gtk3 python-uinput python-cairo libayatana-appindicator meson ninja

Optional for word suggestions:

sudo pacman -S hunspell-en_us

2. Clone the repository

git clone https://github.com/archisman-panigrahi/vboard.git
cd vboard

3. Prepare uinput (required)

Run once with sudo before Meson install:

sudo bash scripts/setup-uinput.sh

For system installs, this also installs a udev rule so your logged-in desktop user can access /dev/uinput. If permissions still do not apply, log out/log in or restart your computer.

4. Build and install with Meson

Global install:

meson setup builddir --prefix=/usr/local
meson compile -C builddir
sudo meson install -C builddir

User-only install:

meson setup builddir-user --prefix=$HOME/.local
meson compile -C builddir-user
meson install -C builddir-user

Restart for changes to take effect. On KDE/Plasma, install hooks automatically create the appropriate KWin window rule for vboard using its Wayland application ID instead of the window title.

5. Uninstall

meson compile -C builddir uninstall-local

For system installs:

sudo meson compile -C builddir uninstall-local

KDE Plasma: enable vboard as the default on-screen keyboard

After installation, open System Settings, search for Virtual Keyboard, and select Vboard.

Usage

When launched, vboard presents a compact keyboard with a minimal interface. The keyboard includes:

• Standard QWERTY layout keys
• Arrow keys
• Modifier keys (Shift, Ctrl, Alt, Super)
• Header-bar suggestions that appear while typing words through vboard when a system Hunspell dictionary is available
• Experimental swipe typing on alphabetic keys: drag across the intended letters and release to insert the best matching dictionary word

Interface Controls

• ☰ (menu) - Toggle visibility of other interface controls
• + - Increase opacity
• - - Decrease opacity
• Background dropdown - Change the keyboard background color
• Tray menu gesture toggle - Enable or disable gesture typing; it is on by default

Configuration

vboard saves its settings to ~/.config/vboard/settings.conf. This configuration file stores:

• Background color
• Gesture typing enabled/disabled state
• Opacity level
• Text color

You can manually edit this file or use the built-in interface controls to customize the appearance.

Customizing Keyboard Layout

The keyboard layout is defined in the rows list in the source code. To modify the layout:

1. Download the source code
2. Locate the rows definition
3. Modify the key arrangement as needed

Troubleshooting

Input does not work

If vboard opens but pressing keys does not type anything, the uinput backend usually could not open /dev/uinput.

1. Check whether uinput exists and inspect its permissions:

ls -l /dev/uinput

2. Run the setup helper again as root:

sudo bash scripts/setup-uinput.sh

3. Reload udev rules and retrigger the device:

sudo udevadm control --reload-rules
sudo udevadm trigger --subsystem-match=misc --sysname-match=uinput

4. Log out and back in, or reboot, so your desktop session picks up the updated device permissions.

5. If it still does not work, add your user to the input group and log out/in again:

sudo usermod -a -G input $USER

You can also start vboard from a terminal and look for errors such as Could not initialize uinput backend ([Errno 13]).

Error: no such device

Make sure uinput module is loaded:

sudo modprobe uinput

To auto-load at boot:

echo 'uinput' | sudo tee /etc/modules-load.d/uinput.conf

Error: Permission denied

Run uinput setup script:

sudo bash scripts/setup-uinput.sh

This installs the packaged udev rule at /etc/udev/rules.d/70-vboard-uinput.rules for system installs. If needed, reload udev, then log out/log in or reboot:

sudo udevadm control --reload-rules
sudo udevadm trigger --subsystem-match=misc --sysname-match=uinput

Contributing

Contributions are welcome.

License

vboard is licensed under the GNU General Public License v3. See LICENSE for details.

Note

Currently only the QWERTY US layout is supported.