Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/KEYBOARD-LAYOUTS.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!-- SPDX-License-Identifier: MIT -->
# Keyboard layouts

The on-screen keyboard is squeekboard. Omarchy Mobile ships its own copies of squeekboard's layouts, with an action row and a globe key that opens the shell's language sheet. This page says what ships, how a user picks a language, how a user adds a layout file of their own, and how a contributor changes the shipped set. Greek is the example throughout: English first, Greek second, the globe opens the language sheet, and one tap on a row switches.
The on-screen keyboard is squeekboard. (An owner may install Tactus beside it and pick it in Setup > Keyboard, `packages/tactus`; this page is about squeekboard.) Omarchy Mobile ships its own copies of squeekboard's layouts, with an action row and a globe key that opens the shell's language sheet. This page says what ships, how a user picks a language, how a user adds a layout file of their own, and how a contributor changes the shipped set. Greek is the example throughout: English first, Greek second, the globe opens the language sheet, and one tap on a row switches.

Everything here is from the `omamobile-shell` package (`packages/omamobile-shell/`). Paths below are relative to it unless they start with `docs/`, `tools/` or `tests/`, or are `AGENTS.md`.

Expand Down
3 changes: 2 additions & 1 deletion packages/omamobile-shell/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,8 @@ Omarchy Mobile's phone profile for Omarchy's own shell. It isn't a fork: these a
| `bin/omamobile-setup-user` | Omarchy Mobile's per-user setup (Omarchy lifecycle `setup-user`); at every login it also enables and starts the Phone and Messages agent's user unit (`omatel-agent.service`, when installed), so calls and texts notify with no app open; `--adopt`, for a user set up by hand rather than by firstboot, marks the once-only steps that would overwrite or repeat what that user has (the shell profile, the monitor scale, the cursor and keyboard lines, the screensaver, Files' click policy) done without running them; the other steps run as for a new user (missing phone plugins and an idle block go into `shell.json`, Chromium's flags are written), and the setup service then runs at each login |
| `bin/omamobile-launch` | One app per screen: every launch from the shell (drawer, home screen, widgets, links, the agent) gets a new empty workspace through a per-launch Hyprland exec rule, or focuses the app's open window; and the switcher's "Show with…" and "Move to its own screen" |
| `bin/omamobile-home` | The home screen, as the home pill's swipe shows it (an empty workspace and the home page). An app runs it when Back (Escape, from the edge swipe) reaches its top level, so Back is phone-wide and no app needs a Hyprland call: [plugins/README.md](plugins/README.md#omamobileback) |
| `bin/omamobile-osk-watch` | Reports squeekboard's visibility (sm.puri.OSK0) to the fingerprint, keyboard and launcher plugins |
| `bin/omamobile-osk-watch` | Reports the on-screen keyboard's visibility (sm.puri.OSK0, squeekboard's or Tactus's) to the fingerprint, keyboard and launcher plugins |
| `bin/omamobile-osk` | The on-screen keyboard the owner chose. With no argument it runs it (the session's autostart line, which runs squeekboard itself where `omamobile-osk` is gone, and squeekboard's user unit through the drop-in `systemd/user/mobi.phosh.OSK-omamobile.conf`); `which` and `list` say what is chosen and installed; `use NAME` changes now. It is squeekboard unless the owner picked Tactus (`packages/tactus`, opt-in) in Setup > Keyboard, an entry shown only where Tactus is installed; a choice that can't be met means squeekboard. `hypr/phone.lua` keeps Tactus's virtual keyboard out of the hardware-key binds and Omarchy's own, as it does squeekboard's |
| `bin/omamobile-screenshot-open` | What a screenshot toast's tap ("Tap to view", patch 0020) opens on a phone (`OMARCHY_SCREENSHOT_EDITOR`, set in `environment.d/30-omamobile-screenshot.conf`; Omarchy passes the saved file's path): the screenshot in Loupe (omamobile-apps), fitted, with touch zoom, pan and swipe, and Loupe's copy, share and delete. Tensaku, Omarchy's default, can't be panned or zoomed by touch; without Loupe it is the fallback, through `omamobile-screenshot-edit` |
| `bin/omamobile-screenshot-edit` | Tensaku as Omarchy opens a screenshot in it (`tensaku-edit`), with GTK's simple input-method context so the on-screen keyboard doesn't come up over the image (show it by hand for the text tool). `omamobile-setup-user` gives Tensaku's own entry (drawer, Loupe's Open With) the same context once, and `hypr/phone.lua` maximizes its window, which Omarchy floats by class |
| `bin/omamobile-osk-guard` | Turns the on-screen keyboard (`screen-keyboard-enabled`) back on when it was left off with no screensaver running (a user unit for every graphical session) |
Expand Down
124 changes: 124 additions & 0 deletions packages/omamobile-shell/bin/omamobile-osk
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
#!/bin/bash
# SPDX-License-Identifier: MIT
# The phone's on-screen keyboard: the one the owner chose.
#
# omamobile-osk run the chosen keyboard (the session's autostart)
# omamobile-osk which the chosen keyboard: squeekboard or tactus
# omamobile-osk list the keyboards installed, one a line
# omamobile-osk use NAME choose NAME and change to it now
#
# squeekboard is the phone's keyboard and a dependency of this package. Tactus
# (packages/tactus) is one an owner may install beside it: it corrects words
# as they are typed. The choice is one word in ~/.config/omamobile/keyboard.
# Anything else there, or a keyboard that is no longer installed, means
# squeekboard, so there is always a keyboard. So does a Tactus that fails at
# its start: one that ends with an error, or a crash, within its first
# seconds (OMAMOBILE_OSK_GRACE, 5) is followed by squeekboard, as on a lock
# that takes a password no keyboard would mean no way in. A Tactus stopped
# by a signal (a change of keyboard, the session's end) is not.
set -u

file=${XDG_CONFIG_HOME:-$HOME/.config}/omamobile/keyboard

installed() {
case $1 in
squeekboard | tactus) command -v "$1" >/dev/null ;;
*) return 1 ;;
esac
}

chosen() {
local name
name=$(head -n1 "$file" 2>/dev/null | tr -d '[:space:]')
if [[ $name == tactus ]] && installed tactus; then
echo tactus
else
echo squeekboard
fi
}

running() { pgrep -u "$(id -u)" -x "$1" >/dev/null 2>&1; }

# Tactus as a child, so a failed start can be followed by squeekboard. A
# signal to this script is passed on to it.
run_tactus() {
local start=$SECONDS rc=0 pid stopped=0
tactus &
pid=$!
trap 'stopped=1; kill -TERM "$pid" 2>/dev/null' TERM INT HUP
wait "$pid" || rc=$?
if ((stopped)); then
# Stopped through this script (a change of keyboard, the session's end):
# the trap cut the wait short, so wait for Tactus's own end and stop too
rc=0
wait "$pid" 2>/dev/null || rc=$?
exit "$rc"
fi
trap - TERM INT HUP
# A failed start: an error of its own or no program to run (1-127), or a
# crash (SIGILL, SIGTRAP from g_error, SIGABRT, SIGBUS, SIGFPE, SIGSEGV),
# within its first seconds. Not a signal from elsewhere (pkill on a change).
if ((rc != 0 && SECONDS - start < ${OMAMOBILE_OSK_GRACE:-5})) &&
{ ((rc < 128)) || [[ " 132 133 134 135 136 139 " == *" $rc "* ]]; }; then
echo "omamobile-osk: tactus ended at its start (status $rc): squeekboard instead" >&2
exec squeekboard
fi
exit "$rc"
}

case ${1:-} in
"")
if [[ $(chosen) == tactus ]]; then
run_tactus
fi
exec squeekboard
;;
which)
chosen
;;
list)
for k in squeekboard tactus; do
installed "$k" && echo "$k"
done
;;
use)
name=${2:-}
case $name in
squeekboard | tactus) ;;
*) echo "omamobile-osk: use squeekboard or tactus" >&2; exit 2 ;;
esac
installed "$name" || { echo "omamobile-osk: $name is not installed" >&2; exit 1; }
mkdir -p "${file%/*}" && printf '%s\n' "$name" >"$file.new" && mv -f "$file.new" "$file" || exit 1

# Change now. Where the session runs the keyboard as squeekboard's user
# unit (this package's drop-in makes that unit run omamobile-osk), through
# the unit.
if systemctl --user is-active -q mobi.phosh.OSK.service 2>/dev/null; then
systemctl --user restart mobi.phosh.OSK.service
exit
fi
# Otherwise stop the one that runs and start the other as Omarchy's
# autostart does (uwsm-app), through Hyprland when it is there: started
# from a terminal or over SSH, a keyboard did not come up
# (omamobile-keyboard-theme, 2026-10-31).
for k in squeekboard tactus; do
running "$k" && pkill -u "$(id -u)" -x "$k"
done
for _ in $(seq 30); do
running squeekboard || running tactus || break
sleep 0.1
done
cmd=omamobile-osk
command -v uwsm-app >/dev/null && cmd="uwsm-app -- omamobile-osk"
if [[ -n ${HYPRLAND_INSTANCE_SIGNATURE:-} ]] && command -v hyprctl >/dev/null; then
hyprctl dispatch "hl.dsp.exec_cmd(\"$cmd\")" >/dev/null
else
# shellcheck disable=SC2086
setsid -f $cmd </dev/null >/dev/null 2>&1
fi
;;
*)
sed -n '3,8p' "$0" | sed 's/^# \{0,1\}//' >&2
exit 2
;;
esac
49 changes: 43 additions & 6 deletions packages/omamobile-shell/bin/omamobile-setup-user
Original file line number Diff line number Diff line change
Expand Up @@ -209,14 +209,42 @@ fi

# On-screen keyboard: squeekboard shows itself when a text field takes focus
# (Hyprland relays text-input-v3 to its input-method-v2). Started from
# Omarchy's user autostart file, once.
# Omarchy's user autostart file, once: omamobile-osk runs the keyboard the
# owner chose, which is squeekboard unless they picked Tactus (Setup >
# Keyboard, below). The line falls back to squeekboard itself when
# omamobile-osk is gone (an older omamobile-shell installed over this one),
# so the session never starts without a keyboard: on a lock that takes a
# password, that would leave no way to unlock it.
osk_line="o.launch_on_start(\"sh -c 'command -v omamobile-osk >/dev/null && exec omamobile-osk; exec squeekboard'\")"
if omarchy-done ensure omamobile-osk; then
gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled true
cat >>~/.config/hypr/autostart.lua <<'LUA'

-- Omarchy Mobile: on-screen keyboard
o.launch_on_start("squeekboard")
LUA
printf '\n-- Omarchy Mobile: on-screen keyboard\n%s\n' "$osk_line" >>~/.config/hypr/autostart.lua
fi
# Up to 0.2.133 that line started squeekboard itself. The line as this script
# wrote it is changed, once; one the owner wrote or changed is left alone
# (and then the keyboard they start is the one they get). A file that is a
# link (a dotfile setup) is left as it is, with a line saying what to
# change: the rewrite would replace the link with a copy. A file that can't
# be written is reported, the rest of the setup goes on, and the next login
# tries again.
if omarchy-done ensure omamobile-osk-chosen; then
autostart=~/.config/hypr/autostart.lua
if [[ -L $autostart ]]; then
if grep -qx 'o.launch_on_start("squeekboard")' "$autostart" 2>/dev/null; then
echo "omamobile-setup-user: $autostart is a link, left as it is; for the keyboard chosen in Setup > Keyboard," \
"its line o.launch_on_start(\"squeekboard\") becomes $osk_line" >&2
fi
elif [[ -f $autostart ]] && grep -qx 'o.launch_on_start("squeekboard")' "$autostart"; then
if ! {
while IFS= read -r l || [[ -n $l ]]; do
if [[ $l == 'o.launch_on_start("squeekboard")' ]]; then printf '%s\n' "$osk_line"; else printf '%s\n' "$l"; fi
done <"$autostart" >"$autostart.new" && mv -f "$autostart.new" "$autostart"
} 2>/dev/null; then
rm -f "$autostart.new" 2>/dev/null || true
rm -f ~/.local/state/omarchy/done/omamobile-osk-chosen
echo "omamobile-setup-user: could not change the keyboard's start line in $autostart; the next login tries again" >&2
fi
fi
fi

# Files (Nautilus) opens folders with one tap: a double tap is a mouse habit
Expand Down Expand Up @@ -510,6 +538,15 @@ if omarchy-done ensure omamobile-menu-mobilenetwork; then
sed -i '0,/^{/s//{\n "setup.mobile-network": {"icon":"\xf3\xb0\x9e\x83","label":"Mobile network","description":"Carrier, mobile data, roaming and the APN","when":"test -x \/usr\/lib\/omamobile-sit\/omamobile-sit-config","action":"omarchy-shell shell summon omamobile.mobilenetwork '"'"'{}'"'"'"},/' "$extension"
fi
fi
# Setup > Keyboard in Omarchy's menu: which on-screen keyboard, the standard
# one (squeekboard) or Tactus, with a tick on the one in use. Shown only where
# there is a choice, that is, where Tactus is installed. Added once.
if omarchy-done ensure omamobile-menu-keyboard; then
extension=~/.config/omarchy/extensions/omarchy-menu.jsonc
if [[ -f $extension ]] && ! grep -q '"setup.keyboard"' "$extension"; then
sed -i '0,/^{/s//{\n "setup.keyboard": {"icon":"\xf3\xb0\x8c\x8c","label":"Keyboard","title":"On-screen keyboard","description":"Which keyboard to type on","when":"command -v tactus"},\n "setup.keyboard.squeekboard": {"icon":"\xf3\xb0\x8c\x8c","label":"Standard","description":"Types what you tap, in every language","checked":"[[ $(omamobile-osk which) == squeekboard ]]","action":"omamobile-osk use squeekboard"},\n "setup.keyboard.tactus": {"icon":"\xf3\xb0\x8c\x8c","label":"Tactus","description":"Corrects words as you type (English)","checked":"[[ $(omamobile-osk which) == tactus ]]","action":"omamobile-osk use tactus"},/' "$extension"
fi
fi
# Setup > Voice in Omarchy's menu opens the voice settings (omamobile.voice),
# through the menu extension file. Added once.
if omarchy-done ensure omamobile-menu-voice; then
Expand Down
12 changes: 9 additions & 3 deletions packages/omamobile-shell/hypr/phone.lua
Original file line number Diff line number Diff line change
Expand Up @@ -94,8 +94,11 @@ o.launch_on_start(
-- layout one of them lands on 124, which Hyprland's keymap reads as
-- XF86PowerOff. Its keys share Hyprland's held-key state with the buttons,
-- so an OSK key could act as the power key or leave it looking held (SUSPEND-
-- PLAN P5 h: the power key's bind stopped firing until a reload).
local hw_keys = { inclusive = false, list = { "hl-virtual-keyboard-squeekboard" } }
-- PLAN P5 h: the power key's bind stopped firing until a reload). Tactus, the
-- keyboard an owner may pick instead (omamobile-osk), is a virtual keyboard
-- too, named after its binary as squeekboard's is.
local osk_devices = { "hl-virtual-keyboard-squeekboard", "hl-virtual-keyboard-tactus" }
local hw_keys = { inclusive = false, list = osk_devices }
hl.unbind("XF86PowerOff")
o.bind("XF86PowerOff", "Power key", "omamobile-keys power-down", { locked = true, device = hw_keys })
o.bind("XF86PowerOff", "System menu", "omamobile-keys power-up", { locked = true, release = true, device = hw_keys })
Expand Down Expand Up @@ -166,7 +169,10 @@ hl.layer_rule({ match = { namespace = "^omamobile-call(-top)?$" }, above_lock =
-- still pastes.
local osk_device = "hl-virtual-keyboard-squeekboard"
local osk_only = { inclusive = true, list = { osk_device } }
local not_osk = { inclusive = false, list = { osk_device } }
-- No on-screen keyboard, Tactus included: its terminal keys have Ctrl, Alt
-- and Tab as squeekboard's do. (Tactus needs none of the binds above: its
-- own keys do what squeekboard's action row does.)
local not_osk = { inclusive = false, list = osk_devices }
hl.device({ name = osk_device, resolve_binds_by_sym = true })
local function voice(method)
return "omarchy-shell shell call omamobile.voice " .. method .. " ''"
Expand Down
2 changes: 2 additions & 0 deletions packages/omamobile-shell/install
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ done < <(find squeekboard/keyboards -type f -name '*.yaml' -print0)
install -Dm755 hooks/theme-set-keyboard "$destination/usr/share/omamobile/shell/hooks/theme-set-keyboard"
install -Dm644 systemd/omamobile-nfc-open.service "$destination/usr/lib/systemd/system/omamobile-nfc-open.service"
install -Dm644 systemd/user/omarchy-fcitx5-omamobile.conf "$destination/usr/lib/systemd/user/omarchy-fcitx5.service.d/omamobile.conf"
# squeekboard's user unit runs the keyboard the owner chose (omamobile-osk)
install -Dm644 systemd/user/mobi.phosh.OSK-omamobile.conf "$destination/usr/lib/systemd/user/mobi.phosh.OSK.service.d/omamobile.conf"
# The permission sheet: the portal's Access backend, its D-Bus activation and
# the portals.conf that picks it under Hyprland (omamobile.access shows it).
install -Dm644 portal/omamobile.portal "$destination/usr/share/xdg-desktop-portal/portals/omamobile.portal"
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# SPDX-License-Identifier: MIT
# squeekboard's own user unit, for a session that starts the keyboard through
# it: the keyboard the owner chose (omamobile-osk), which is squeekboard
# unless they picked another. Whichever it is owns the unit's bus name,
# sm.puri.OSK0.
[Service]
ExecStart=
ExecStart=/usr/bin/omamobile-osk
9 changes: 8 additions & 1 deletion packages/omamobile-shell/test/all
Original file line number Diff line number Diff line change
Expand Up @@ -475,7 +475,8 @@ bash -n hooks/theme-set-keyboard || fail "the theme-set hook parses"
# key codes reach 124 (XF86PowerOff in Hyprland's keymap) and share the held
# state with the real buttons.
[[ $(grep -c 'device = hw_keys' hypr/phone.lua) == 5 ]] || fail "the five hardware-key binds are limited to real keyboards"
grep -c 'inclusive = false, list = { "hl-virtual-keyboard-squeekboard" }' hypr/phone.lua >/dev/null || fail "squeekboard is excluded from the hardware-key binds"
grep -c 'local osk_devices = { "hl-virtual-keyboard-squeekboard", "hl-virtual-keyboard-tactus" }' hypr/phone.lua >/dev/null &&
grep -c 'local hw_keys = { inclusive = false, list = osk_devices }' hypr/phone.lua >/dev/null || fail "squeekboard and Tactus are excluded from the hardware-key binds"
grep -cx 'exec omamobile-keyboard-theme --restart' hooks/theme-set-keyboard >/dev/null || fail "the theme-set hook rewrites and restarts"
rc=0; out=$(python3 -B test/keyboard-layouts.py 2>&1) || rc=$?
if [[ $rc == 77 ]]; then
Expand Down Expand Up @@ -1099,6 +1100,12 @@ else
pass "widget crash guard: same-boot death held back, one retry after a system going down, clean run and quit clear"
fi
bash test/osk-guard.sh || fail "omamobile-osk-guard"
bash -n bin/omamobile-osk || fail "omamobile-osk parses"
bash test/osk.sh || fail "omamobile-osk"
grep -cx 'ExecStart=/usr/bin/omamobile-osk' systemd/user/mobi.phosh.OSK-omamobile.conf >/dev/null &&
grep -c 'systemd/user/mobi.phosh.OSK-omamobile.conf "$destination/usr/lib/systemd/user/mobi.phosh.OSK.service.d/omamobile.conf"' install >/dev/null ||
fail "squeekboard's user unit runs the chosen keyboard"
grep -c 'omarchy-done ensure omamobile-menu-keyboard' bin/omamobile-setup-user >/dev/null || fail "Setup > Keyboard in Omarchy's menu"
bash -n bin/omamobile-onboarding || fail "omamobile-onboarding parses"
bash test/onboarding-fingerprint.sh || fail "omamobile-onboarding's fingerprint offer"
bash test/onboarding-mobile.sh || fail "omamobile-onboarding's SIM line"
Expand Down
Loading