Skip to content

omamobile-settings: Keyboard page with layouts and a switch key, layout label in the bar - #892

Open
Somnius wants to merge 19 commits into
derekross:mainfrom
Somnius:settings-keyboard-layouts-1117
Open

Somnius wants to merge 19 commits into
derekross:mainfrom
Somnius:settings-keyboard-layouts-1117

Conversation

@Somnius

@Somnius Somnius commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

This adds a Keyboard page to Settings for using a real keyboard with the phone, Bluetooth or USB, plus a layout label in the bar and a small keyboard card in the shade. I type Greek and English, and until now the only way to get a second layout on a hardware keyboard was editing input.lua by hand.

It builds on the Settings app @marselnenaj started in #526, it's a great app to have on the phone so I'd rather keep adding pages to it. The input.lua handling follows what I did in my desktop plugin, https://github.com/Somnius/Keyboard-Layout-for-Omarchy.

Keyboard page

What the page does:

  • up to 4 layouts, with up, down and remove. The first one is the main layout
  • "Add a layout" is a search field. Matches from base.lst only show after typing something, so there's no long list to scroll on a phone
  • a switch key: Alt+Shift, Ctrl+Shift, Caps Lock or None
  • the first layout has to be a Latin one. The lock screen PIN and passwords get typed on layout 1, so the backend refuses a non-Latin first layout, writes nothing, and the page says why

The bar gets a small label right of the clock (EN, GR, ...) for the hardware keyboard's layout. It only shows with more than one layout, so with one layout the bar looks the same as before.

bar label

While a keyboard is connected the on-screen keyboard doesn't pop up on every text field, and the shade gets a card with Show, Hide and Disconnect:

keyboard card

How it saves: layouts go into ~/.config/hypr/input.lua, the same file Omarchy uses on the desktop. The backend only replaces the live kb_layout, kb_variant and kb_options strings and leaves comments and other options alone. It takes a lock, keeps a backup next to the file, writes through a temp file and rename, follows a symlink instead of replacing it, and aborts if the file changed meanwhile. Omarchy's stock input.lua only has those keys in a commented template, so then it appends one small hl.config({ input = { ... } }) block and edits that next time. The change goes in live with hyprctl eval (falling back to hyprctl keyword), never hyprctl reload, since a reload re-runs phone.lua and resets the refresh rate. squeekboard's list follows: a new layout is added if squeekboard has a layout file for it, and a layout removed on the page is removed there too. Languages that are only on the OSK stay. Switching layouts never writes gsettings, because that made squeekboard send its keymap again and apps got Latin letters while Hyprland said Greek.

The switch key is a plain xkb option: grp:alt_shift_toggle, grp:ctrl_shift_toggle, or grp:caps_toggle,grp_led:caps. phone.lua binds nothing. Caps Lock takes the Caps key, so compose:caps (Omarchy 4.0) or omarchy:shift_caps_compose (4.5) comes out while Caps is the switch key and goes back when another switch key is picked, but only if it was there before.

What I measured on my Pixel 8 Pro (Hyprland 0.57.0, Dell KB7120W over Bluetooth, 11-17 and 11-18), with a small logger on the keyboard's evdev node and Hyprland's socket2:

switch delay

  • the xkb options switch in about 2 ms: Alt+Shift 20 of 20 presses in both key orders, Caps Lock 2 to 3 ms over 14 presses
  • my earlier version used a Hyprland bind that ran a script, about 15 ms (35 max). With the bind and the xkb option both active, one press switched twice
  • Ctrl+Shift: 41 switches over two runs, alternating cleanly, no doubles
  • typing right after a switch comes out in the new layout (switched, typed "asd" straight away)
  • on 11-17 the xkb option looked like it never switched, which is why I went with binds first. On 11-18 it worked every time. I don't know what was different that day

One trade-off with the chord keys: xkb switches on Ctrl+Shift or Alt+Shift even when they're part of a longer chord. With Ctrl+Shift picked, Ctrl+Shift+V in foot still pasted, but the layout also flipped to Greek on the same press. Alt+Shift does the same on Alt+Shift+Tab. So with a chord switch key, shortcuts on that chord flip the layout as a side effect. Caps Lock doesn't have that problem, which is why I use it.

Known limits:

  • picking a language on the OSK's globe doesn't switch the hardware keyboard and the other way round. Two separate lists, on purpose, after the gsettings finding above
  • nothing puts the hardware keyboard back on layout 1 when the phone locks. omamobile-keyboard-switch lock is there for it but I haven't found the right place in Omarchy's lock flow to call it from
  • a chord switch key flips the layout inside other shortcuts on that chord, see above
  • while a keyboard is connected the OSK doesn't come up on a polkit password prompt either (Omarchy's agent lives inside the shell, so there's no window to notice). The card's Show button or disconnecting the keyboard brings it back. While the phone is locked the OSK stays on as before

Testing: test/all passes for omamobile-settings and omamobile-shell on my desktop after rebasing on today's main. The backend tests cover the stock commented input.lua, edited files, a symlink, missing keys, hyprctl and gsettings failures, the compose marker for both Omarchy names and both at once, and a failed backup or marker write. Putting the old marker back when input.lua itself can't be written has no test of its own yet. On the phone, on Omarchy 4.0.6, I measured all three switch keys with the xkb options set in input.lua by hand. The page and the bar label ran from an earlier build of this branch, from before the xkb-only change, so the page writing these switch keys hasn't been tried on the phone yet. The phone moved to Omarchy 4.5.0 this evening, and its default input.lua does set omarchy:shift_caps_compose, but the Caps handling for it is only covered by the tests so far.

This touches the same Settings files as #866 (catalog.json, actionrunner, install, test/all, core tests), so whichever lands second needs a rebase. I didn't bump versions here because of that, I'll set them after the rebase.

keyboard.sh edits only the live kb_layout, kb_variant and the grp: part of
kb_options in ~/.config/hypr/input.lua (backup, flock, abort if the file
changed), applies it live with hyprctl eval instead of a reload, and writes
the same list to the input-sources gsettings key for the OSK.
Test uses fake input.lua files, a fake hyprctl and gsettings.
keyboard.sh gets a list verb (layouts and grp: switch keys from the xkb
rules file). The action runner allows the keyboard tool with its wider
argument set and reads up to 32 KiB of output.
next/set/lock switch every real keyboard (never squeekboard's virtual one)
through hyprctl switchxkblayout and put the same layout, by name, first in
the on-screen keyboard's list. A user service listens for activelayout so
the xkb switch key moves the OSK too. Super+Alt+Shift+Space runs next on
hardware keyboards (Super+Space is Omarchy's menu). The Settings page no
longer offers grp:win_space_toggle for the same reason.
Shows EN/GR... for the main hardware keyboard when kb_layout has more than
one layout, re-read on activelayout and configreloaded. The call chip
anchors to the label, or to the clock when the label is hidden.
The stock file has kb_layout and kb_options only in comments. get now
reports Hyprland's effective values, and set adds one hl.config() block
at the end instead of failing.
…ards, bar rereads

The main keyboard is now the real one marked main, else the first real one with
more than one layout, else the first real one, in the bar and the switch tool.
radio-control and gpio-keys count as pseudo-keyboards. A device name with a
space, ; or quote is left out of the hyprctl --batch string. listen brings the
other real keyboards to the index of the one switched. The bar reruns its
devices read when an event comes while one is running.
gsettings is merged instead of replaced: the OSK's own languages and its
current entry stay, new hardware layouts are added (only ones squeekboard has a
file for), removed ones dropped, and a switch-key change leaves it alone. It is
written before the live apply so the layout follower never reads the old list.
A list whose first layout is not Latin is refused; the page stops it before
sending and reads the state again after a failed set. Only kb_* inside an
input = { } table are edited, a symlinked input.lua keeps its link, get uses
Hyprland's options like set does, the keyword fallback is one batch, and the
main keyboard follows the same rule as the shell.
The xkb grp: option never switched layouts on the phone (Hyprland 0.57.0),
and writing gsettings on a hardware switch made squeekboard resend its
keymap, so apps got Latin letters. Settings now writes
~/.config/hypr/omamobile-keyboard.lua (Alt+Shift, Ctrl+Shift, Caps Lock or
none, both key orders, every keyboard but squeekboard's), phone.lua loads
it, and grp: options are dropped from kb_options. omamobile-keyboard-switch
only runs switchxkblayout on real keyboards; the follower service is gone.
The layout picker is a search field instead of the full list.
…ected

omamobile-osk-guard becomes the one writer of screen-keyboard-enabled:
false while a real BT/USB keyboard is connected (same rule as the lock
backend), true otherwise, while locked with a password, or in the card's
show mode. Keyboards are listed per uniq in osk-hwkbd.json with a 5 s
grace. A true written by the screensaver restore over a connected
keyboard goes straight back off. The shade gets a keyboard card with
Show/Hide on-screen keyboard and Disconnect for Bluetooth ones.
…overs any lock

- Alt+Shift / Ctrl+Shift switch binds fire on release, non-consuming, so
  Alt+Shift+Tab, Ctrl+Shift+C/V keep working. Every switch key is bound once
  and only the chosen one is enabled; no hl.unbind on key strings.
- phone.lua binds the default (Alt+Shift) when Settings never wrote the file.
- The switch script does nothing with one layout.
- osk-guard: any lock keeps auto-show on (unknown isLocked output counts as
  locked), no auto-show written over a running screensaver, grace counted
  from the removal, one process per lock poll (slower with the screen off),
  setting followed from gsettings monitor, exits when a monitor dies, clears
  the keyboard list on exit, drops bad state entries.
- Keyboard card: no binding loop on the shade's room, reload timer only
  while the shade is open.

Not tested on the phone yet.
Measured on the 8 Pro (Hyprland 0.57.0): the release binds missed 9 of 17
presses and fired ~110 ms late, press binds running switchxkblayout current
next switched 11/11, a code:66 bind never fired and grp:caps_toggle switched
12/12. Caps now goes into kb_options (compose:caps dropped then), get reports
caps from the effective options, and keyboard-switch next reads devices once.
…compose marker on a failed write

phone.lua reads input:kb_options with hl.get_config and leaves every default
Alt+Shift/Ctrl+Shift bind off when it has a grp: switch, so one press doesn't
switch twice; get reports none then. keyboard.sh puts the compose-caps marker
on disk before input.lua loses compose:caps. Tests for both, known limits in
the header.
On the 8 Pro (Hyprland 0.57.0-3.2, Dell KB7120W, 2026-11-18)
grp:alt_shift_toggle switched 20/20 in both key orders, 1-2 ms after the
second key, and grp:ctrl_shift_toggle 19/19; an Alt+Shift press bind on
top of the option switched twice per press. So every switch key is a grp:
option in kb_options (caps stays grp:caps_toggle,grp_led:caps with the
compose:caps marker) and phone.lua binds nothing. get reads the choice
from the effective kb_options; a fresh phone has no grp: option until one
is picked. The old bind file is no longer loaded; while there is no
grp: option get reports its choice and the next save writes it as xkb
(old binds stay until hyprctl reload). A save that needs Hyprland's
effective kb_layout/kb_options writes nothing when getoption fails.
…witch key and comes back after

Later Omarchy sets Compose on Shift+Caps through omarchy:shift_caps_compose, which redefines the whole
Caps Lock key, so a Caps switch key would not switch with it left in. It is handled like compose:caps:
removed while caps holds the key and put back when caps lets go. The state file says which one to put
back; a bare restore line from before still means compose:caps.
…failed save restores the old marker

The marker named only the first Compose option it found, so with both
compose:caps and omarchy:shift_caps_compose set only compose:caps came back
after caps, and an option added by hand while caps was on replaced the one the
marker held. It now names every option that was there or is there now, and
leaving caps adds back each one that is missing. When input.lua cannot be
written after the marker changed, fail() puts the old marker back instead of
removing it. The header's counts now match the logged runs.
@Somnius
Somnius force-pushed the settings-keyboard-layouts-1117 branch from 65bf593 to 3aac25f Compare November 18, 2026 16:22

@derekross derekross left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you, Lef. A second layout on a real keyboard is something the phone should have, and a lot of care went into this: the editor leaves comments and other options alone, keeps a backup, refuses when the file changed under it, and the tests cover the stock file, a symlink and the failure paths. I ran the backend's test, the guard's test and the two model tests here on a merge with today's main, and they pass. The measurement of the three switch keys, and the finding that a bind on top of the xkb option switches twice, are exactly the kind of evidence I like to see.

It isn't close to merging yet, though, and I'd rather say why now than after another week of work on it.

1. Omarchy 4.5 already has a store for this, and the page overrides it. You built and measured this on 4.0.6. In 4.5.0-3, which every phone is on, omarchy-setup-keyboard saves the layouts to ~/.config/omarchy/keyboard-layouts, and Omarchy's default input.lua builds kb_layout, kb_variant and kb_options from that file, puts us first when a non-Latin layout leads, and adds grp:alts_toggle. I ran your backend on 4.5's stock input.lua: the first save appends an hl.config({ input = { kb_layout = "us,gr", kb_options = "omarchy:shift_caps_compose" } }) block to the user's file. From then on Omarchy's own file is ignored and its picker fails with "Your personal keyboard layout override takes precedence over this selection". I understand why you can't call Omarchy's tool (it reloads Hyprland, which resets the refresh rate here, and it goes through Fcitx). But I'd like the page to write Omarchy's file for the layouts, apply them live with the hyprctl eval you already have, and touch input.lua only for the switch key, which Omarchy has no store for. Most of the Lua editing then goes away.

2. The Latin rule. With your list of 35 layouts, jp,us, al,us, vn,us, mt,us and kr,us are refused as not Latin, and a phone whose first layout is jp can't save anything on the page; while us:rus and us:chr are accepted. Omarchy keeps the opposite list, the 29 layouts that can't type Latin plus those two us variants (default/hypr/input.lua). Please use that one, in the backend only, and let the page ask the backend.

3. Three pull requests instead of one. (a) the Settings page and its backend; (b) the layout label in the bar; (c) the on-screen keyboard staying down while a hardware keyboard is connected, with the shade card. Each can be tested and merged on its own, and (c) is a different kind of change: it rewrites the on-screen keyboard's safety net, about 40 lines of bash that every phone depends on, into a Python daemon ten times that size, and changes a default for everyone. I read it through and the fail-safe directions are right (unknown lock state counts as locked, a stop or crash turns the keyboard back on). For (c) I'd want: a plan section with a runbook in docs/TOUCH-PLAN.md next to 0.5 (the "OSK-HWKBD-PLAN" the code cites isn't in the repository); the slow 10 s lock poll chosen only after a poll has answered "locked" (as it is, a poll that lands between the backlight going to 0 and the lock being taken schedules the next one 10 s out; I read that from the code and have not reproduced it); a word on USB receivers and docks that present a full keyboard with none attached; and a run on my Pixel 7 Pro before it merges, since it runs there at every login.

4. It has to have run. As you say yourself, the page writing the switch keys hasn't been tried on the phone, nothing has run on 4.5, and the code has six "UNVERIFIED on the phone" notes, including the live apply through hyprctl eval and the bar's event names on Hyprland 0.57. For each part: uname -r, pacman -Q omarchy quickshell hyprland and the two packages, a tools/phone-smoke report, and each UNVERIFIED note turned into a dated result or removed together with its code.

5. The on-screen keyboard's language list. omamobile-keyboard-languages and the language sheet own that list today (docs/KEYBOARD-LAYOUTS.md). Your sync_osk removes from it whatever is removed on the page, including the language the on-screen keyboard is showing, and can write it empty. Since you want the two lists separate, please only ever add, and do it through omamobile-keyboard-languages so there is one writer.

Smaller things, for when you rework it:

  • The four pictures under docs/screenshots/keyboard/ aren't used by any document; please attach them to the pull request instead of committing them. The numbers in the chart belong in the plan's results.
  • Please take out what only your own phone ever had: the migration from the earlier bind file in keyboard.sh, and the test lines about the old bind and the layout follower. And omamobile-keyboard-switch, which nothing calls yet, can come with the lock-screen reset that needs it.
  • The backend leaves three files in ~/.config/hypr (backup, lock, state); ~/.local/state/omamobile/ is the place for state.
  • The bar starts hyprctl -j devices after every activelayout event on every phone. Omarchy 4.5's own bar widget (KeyboardLayoutModel.js) reads the layout from the event itself; have a look before the next version, and a count of those events during ordinary typing on the on-screen keyboard would tell us whether it matters.
  • The tests that grep KeyboardPage.qml and Bar.qml for a line of source pin the spelling, not the behaviour. #866 loads its page against a stub runner in the core tests; the same would work here.
  • Versions: you were right to leave them. Settings 0.1.3 goes to #860 and 0.1.4 to #866, so the page is 0.1.5 at the earliest; I'll set the shell's number when each part merges.
  • #896 puts the choice of on-screen keyboard under Omarchy's Setup > Keyboard. It doesn't conflict with this in git, but the two of you should agree where an owner looks for what.

If you'd like to start with one part, (b) is the smallest and (a) the most useful. I'm happy to look at a sketch of (a) on Omarchy's file before you write the tests for it.

@Somnius

Somnius commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

@derekross thanks, that's fair, and better now than in a week. I'll split it in three and redo the page on Omarchy's file.

I'd take your offer and start with the sketch of (a) before I write any tests. I read the 4.5.0-3 files on the 8 Pro today (read only, nothing run yet). Short version:

  • Layouts go to ~/.config/omarchy/keyboard-layouts as the same two lines Omarchy writes (XKBLAYOUT=, XKBVARIANT=). Nothing about layouts goes into input.lua any more.
  • Live apply is one hyprctl eval with kb_layout, kb_variant and kb_options together, computed the same way Omarchy's input.lua would at load, then checked with getoption and devices. No reload. This is still not run on the phone, it's the first thing I'll test.
  • Switch key: one marked block in the user's input.lua that sets only kb_options. I checked on the phone that a user kb_options replaces Omarchy's whole string (mine has no omarchy:shift_caps_compose left), so the block has to carry the full string, and it replaces grp:alts_toggle too. Omarchy's picker only compares kb_layout and kb_variant, so by the code that block shouldn't trigger the "takes precedence" error. I'll run that as well.
  • Latin rule: Omarchy's 29 plus us:rus and us:chr, in the backend only, the page asks. I'd put us first like Omarchy does instead of refusing. One thing I noticed: Omarchy's input.lua only checks the layout name of the first entry, so a list that leads with us:rus isn't reordered there. I'd treat it as non-Latin.
  • On-screen keyboard: add only, through omamobile-keyboard-languages. Its set moves the name to the front, which switches the keyboard, so I'd add an add verb that appends and leaves the current one alone.
  • State (lock, backup) in ~/.local/state/omamobile/. The migration, the bind file, the compose marker, omamobile-keyboard-switch, my Latin list, sync_osk and the committed screenshots all go.

Questions before I write it:

  1. Is a kb_options-only block carrying the full string what you meant by touching input.lua only for the switch key?
  2. Fourth choice "Omarchy default" (no block, so grp:alts_toggle only with a non-Latin layout) instead of "None", ok?
  3. Non-Latin list: a copy plus a test that compares it with the installed input.lua, or parse Omarchy's file at run time?
  4. Is the add verb fine inside (a), since it touches the shell package?
  5. Someone who already has a live kb_layout in their input.lua: I'd show a message and write nothing. Ok?
  6. Omarchy's picker also updates the Fcitx group after saving. The page wouldn't. Fine on the phone?

Order: once the sketch is agreed I'd send (b) first since it's small (with the KeyboardLayoutModel.js look and the event count you asked for), then (a), then (c) with the plan section in docs/TOUCH-PLAN.md, the lock poll fix and the note on receivers and docks. Each one with the versions, a phone-smoke report and no UNVERIFIED notes left.

I'll also talk to the author of #896 about where an owner looks for what.

The full sketch, with file:line for everything I read on the phone:

Sketch of (a)

Sketch for part (a): Keyboard page + backend on Omarchy 4.5's store

Date: 2026-11-18. Answers the review of #892
Status: design only. Nothing here is written or tested yet.

Marks: [V] = read on the Pixel 8 Pro today (omarchy 4.5.0-3, hyprland 0.57.0-3.3, read only, file:line given).
[G] = not verified, needs the test named next to it.

1. What Omarchy 4.5 does (facts)

  • Store ~/.config/omarchy/keyboard-layouts: two shell-style lines,
    XKBLAYOUT=us,gr and XKBVARIANT=, (variants pair with layouts by position).
    Written by save_keyboard() in /usr/share/omarchy/default/input-methods/typing_setup.py:176-193
    (atomic write at :185, then hyprctl reload at :186, then Fcitx). omarchy-setup-keyboard is only
    python3 typing_setup.py keyboard (/usr/share/omarchy/bin/omarchy-setup-keyboard:7). [V]
  • Reader: keyboard.selected() in /usr/share/omarchy/default/hypr/keyboard.lua:28-33. It parses
    KEY=value lines (quotes and trailing # comments stripped, :15-20) and falls back to
    /etc/vconsole.conf when the store has no XKBLAYOUT. It is called from
    /usr/share/omarchy/default/hypr/input.lua:12, so it is read only when Hyprland loads its config
    (start, hyprctl reload). Nothing watches the file. [V]
  • The store has no options key. input.lua:18 always starts from omarchy:shift_caps_compose and adds
    ,grp:alts_toggle when the first layout is non-Latin (:24, :51) or any layout is non-Latin (:56-63). [V]
  • Latin rule: input.lua:24-52. If the first layout is in the non-Latin list, us goes first; an
    existing us entry (unless its variant is chr or rus, :38) is moved, not duplicated. [V]
    Note: a list that leads with us:rus is not reordered by Omarchy, since :24 only looks at the layout
    name us. [V] (by reading the code, not by running it)
  • Non-Latin list: input.lua:7-8, 29 names:
    af am ara bd bg by et ge gr il in iq ir kg kh kz la lk mk mm mn mv np rs ru sy th tj ua;
    us variants at :10: chr rus. The same 29 are repeated in
    /usr/share/omarchy/default/input-methods/configure.py:17 (NON_LATIN, no us variants). [V]
  • User override: ~/.config/hypr/hyprland.lua:14 loads Omarchy's defaults, :20 loads the user's
    hypr.input after. A user hl.config({ input = { kb_options = "..." } }) replaces the whole string:
    on the phone the user file sets grp:caps_toggle,grp_led:caps,shift:both_capslock_cancel and
    hyprctl getoption input:kb_options returns exactly that, without omarchy:shift_caps_compose. [V]
    Other keys are untouched by a partial block (numlock_by_default still true from Omarchy,
    repeat_rate 8 from the user's first block, kb_layout from the second). [V]
  • Omarchy's picker error "Your personal keyboard layout override takes precedence" compares only
    kb_layout and kb_variant (typing_setup.py:190-193, keyboard_selection() :39-43). A user block
    that sets only kb_options does not trip it. [V] (by reading; not run)
  • omamobile-keyboard-languages (packages/omamobile-shell/bin/omamobile-keyboard-languages): verbs
    list, set NAME, remove NAME. The only way to add is set, which puts NAME at the front of
    gsettings org.gnome.desktop.input-sources sources (:137-141), so it also switches the on-screen
    keyboard to it. There is no "add without switching" verb. [V] (local repo, branch of omamobile-settings: Keyboard page with layouts and a switch key, layout label in the bar #892)

2. Data flow

KeyboardPage.qml
   | keyboard.sh get / list / check / set layouts / set switch-key
   v
backends/keyboard.sh
   |-- layouts ----> ~/.config/omarchy/keyboard-layouts     (Omarchy's store, atomic write)
   |-- switch key -> ~/.config/hypr/input.lua               (one marked block, kb_options only)
   |-- live -------> hyprctl eval 'hl.config({ input = { kb_layout, kb_variant, kb_options } })'
   |-- OSK --------> omamobile-keyboard-languages add NAME  (add only, new verb)
   `-- state ------> ~/.local/state/omamobile/keyboard.*

On the next Hyprland start Omarchy's input.lua builds the same values from the store, and the user's
input.lua block (if a switch key was picked) replaces kb_options. The live apply has to give the same
result as that load, so the backend computes it with the same rule.

3. Files written

File When What
~/.config/omarchy/keyboard-layouts layouts save XKBLAYOUT=...\nXKBVARIANT=...\n, same text Omarchy writes, already Latin-leading (Omarchy expects that, input.lua:54)
~/.config/hypr/input.lua switch-key save only one block between two marker comments, hl.config({ input = { kb_options = "..." } }); removed again when the key is set back to "Omarchy default"
~/.local/state/omamobile/keyboard.lock every save flock
~/.local/state/omamobile/keyboard-input.lua.bak before input.lua is changed copy of the old file

Nothing else in ~/.config/hypr. No kb_layout or kb_variant is ever written to input.lua.

4. The switch key

Omarchy has no store for it, so it lives in the user's input.lua as a kb_options-only block. Because a
user kb_options replaces Omarchy's whole string (section 1), the block has to carry the full string:

  • Alt+Shift: omarchy:shift_caps_compose,grp:alt_shift_toggle
  • Ctrl+Shift: omarchy:shift_caps_compose,grp:ctrl_shift_toggle
  • Caps Lock: grp:caps_toggle,grp_led:caps (compose leaves the Caps key; it comes back with any other choice,
    because the string is rebuilt each time. No "compose restore" marker file is needed any more.)
  • Omarchy default: no block. Omarchy then gives grp:alts_toggle for non-Latin layouts and no switch key
    for Latin-only ones.

Consequences to be honest about:

  • With a block present, Omarchy's grp:alts_toggle is gone (replaced by the chosen key). That is the point,
    but it is a change from stock.
  • The block copies omarchy:shift_caps_compose. If Omarchy changes its default options later, the block
    keeps the old one until the next switch-key save. [G] whether Hyprland 0.57's Lua has a getter that
    would let the block append to the current value instead; I did not find one and did not test.
  • If the user's input.lua already has its own live kb_options outside our markers, the backend does not
    edit it: get reports the switch key as "set in input.lua" and the switch-key row is read only.
  • Same for a live kb_layout in the user's input.lua: the page shows "input.lua overrides the layouts"
    and refuses to save, since Omarchy's store would be ignored anyway. No migration.

What is left of the Lua editing: find or replace one marked block, and detect a live kb_layout /
kb_options outside it (the existing tokenizer, read only).

5. Live apply

  1. Compute the final values the way the config load would: layouts and variants from the store (already
    Latin-leading); options = our block's string if there is one, else omarchy:shift_caps_compose plus
    ,grp:alts_toggle when any layout is non-Latin.
  2. hyprctl eval 'hl.config({ input = { kb_layout = "...", kb_variant = "...", kb_options = "..." } })',
    all three in one call so no keymap is built from a half-changed set. Never hyprctl reload (it resets
    the refresh rate and re-runs phone.lua).
  3. Check: hyprctl -j getoption input:kb_layout|kb_variant|kb_options equal what was sent, and
    hyprctl -j devices shows the new layout on the real keyboard. If not, answer
    "saved, applies at next login" as an error line; the files stay.

[G] that 0.57 rebuilds the keymap of already connected keyboards on this eval. This is the first thing
to run on the phone (test plan 1). The hyprctl --batch keyword fallback goes unless that test shows it
is needed.

6. Latin rule

  • One list, in the backend only: Omarchy's 29 names plus the us variants chr and rus.
  • The page asks the backend (keyboard.sh check us,gr or a field in list), it has no list of its own.
  • The backend does what Omarchy does instead of refusing: a non-Latin first layout gets us in front
    (an existing Latin us is moved). The answer says what was saved so the page can show it.
    jp,us, al,us, vn,us, mt,us, kr,us are saved as given.
  • A leading us:rus or us:chr is treated as non-Latin too (Omarchy's input.lua does not catch this
    case, see section 1).
  • xkb has 4 groups: 4 non-Latin layouts without us would become 5, so that one is refused with a message.

Where the list comes from: a copy in the backend, plus a test that reads the installed
/usr/share/omarchy/default/hypr/input.lua and fails when the two differ (skips when Omarchy is not
installed). Parsing Omarchy's Lua at run time is the alternative; see the questions.

7. On-screen keyboard list: add only

  • A layouts save calls omamobile-keyboard-languages add NAME for each new layout that squeekboard has a
    file for. Never remove, never reorder, never write an empty list.
  • This needs a new add verb in omamobile-keyboard-languages: append at the end when missing, no-op when
    present, current (first) entry unchanged, empty list becomes us + NAME (as set keeps the fallback,
    :139). Today's set would switch the on-screen keyboard to the new language.
  • sync_osk and every direct gsettings call leave the backend. One writer.
  • A failure here is reported ("saved and applied, on-screen keyboard list not updated"), the save stands.

8. Removed from today's backend

  • Editing or appending kb_layout / kb_variant in input.lua (write(), the appended block, the
    missing-key insertion, the symlink handling for it).
  • The 35-name LATIN set and the refusal.
  • sync_osk (removal, direct gsettings).
  • The bind-file migration (old_key, -- switch-key: lines), omamobile-keyboard.lua and the
    compose-caps marker (compose_marked, write_state, MARKER_*).
  • input.lua.bak-omamobile and input.lua.lock-omamobile in ~/.config/hypr.
  • omamobile-keyboard-switch (comes later with the lock-screen reset).
  • The test lines about the old bind and the layout follower; the tests that grep KeyboardPage.qml.
  • The screenshots under docs/screenshots/keyboard/ (attached to the PR instead).
  • Out of (a) entirely: the bar label (b) and the OSK guard daemon with the shade card (c).

Kept: get / list JSON shape, the xkb rules validation (layout and variant must exist, max 4, no
duplicates), the real-keyboard pick for active, find_hypr, lock + temp file + rename + "changed while
saving" check for input.lua.

9. Test plan

On the phone (Pixel 8 Pro, Omarchy 4.5.0-3; each with uname -r, pacman -Q omarchy quickshell hyprland
and the two packages, and a tools/phone-smoke report):

  1. hyprctl eval with us,gr and a hardware keyboard connected: getoption and devices show it, typing
    gives Greek after the switch key, no reload, refresh rate unchanged.
  2. Fresh state (no store, stock input.lua): save us,gr on the page; the store has the two lines,
    input.lua is byte-identical to before.
  3. Open Omarchy's Setup > Keyboard after 2: it lists us,gr and saves without the "takes precedence"
    error, with and without a switch-key block.
  4. Each switch key (Alt+Shift, Ctrl+Shift, Caps, Omarchy default): 20 presses each, count switches and
    doubles; Compose on Shift+Caps works for the first two and comes back after leaving Caps.
  5. Save gr,us and ru: the store says us,gr and us,ru. Save jp,us: stored as given.
  6. Re-login (not reload) after 2 and 4: same getoption values as the live apply gave.
  7. OSK: set the on-screen keyboard to German, save us,gr on the page: German still showing, gr at the
    end of the list. Remove gr on the page: still in the OSK list.
  8. A user input.lua with its own live kb_layout: the page says so and writes nothing.

In the repo: the backend test against a fake hyprctl and a fake omamobile-keyboard-languages (store
text, block add/replace/remove, refusals, Latin cases from 5, lock, changed-while-saving); the list
comparison test from section 6; add cases in test/keyboard-languages.sh; the page loaded against a stub
runner in the core tests, as #866 does. Tests are written after the sketch is agreed.

10. Open questions

  1. Switch key: is a marked kb_options-only block in the user's input.lua, carrying the full string
    (so it replaces omarchy:shift_caps_compose and grp:alts_toggle), what you meant by "touch input.lua
    only for the switch key"?
  2. Is "Omarchy default" (no block, so grp:alts_toggle only with a non-Latin layout) fine as the fourth
    choice instead of "None"?
  3. Non-Latin list: a copy with a test against the installed file, or parse Omarchy's input.lua at run
    time?
  4. Non-Latin first layout: put us first like Omarchy does, or refuse and let the owner reorder?
  5. Is a new add verb in omamobile-keyboard-languages fine inside (a)? It touches the shell package.
  6. A user who already has a live kb_layout in input.lua: refuse with a message (proposed), or offer
    to move it into the store?
  7. Fcitx: Omarchy's picker also updates the Fcitx group after saving (typing_setup.py:194-208). The page
    would not. Is that fine on the phone?
  8. Order of the three PRs: (a) sketch agreed first, then (b), (a), (c)?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants