Hojun-Cho
5664a008de
One wl_surface and one zwp_input_popup_surface_v2, made once; the compositor makes them visible on activate, puts them at the text cursor and takes them down again, so popuparea, popupposition and Caret stay X11-only and popuplayout gets a constant area. Two shm buffers are used in turn, each busy from attach until the compositor releases it, because win.c's single grow-only image would be redrawn while the compositor was still reading it; a picture that arrives while both are busy waits for the next release, and the engine will not send it twice. drawthread no longer runs, so wl.c reads GDK_SCALE itself and calls textinit after it, since setfont reads Fontsz. The buffer is rounded up to a multiple of the scale: one that is not is an invalid_size error at attach, and a preedit alone really does lay out to an odd width at GDK_SCALE=2. drawc is taken where the engine's picture and our surface can part: after every key, after the Keyrelease a deactivate sends, and after the owner poll, hiding for the last two. The poll is not an optimisation -- once another frontend takes the engine, its pictures go unconsumed and no later send will ever say hide. main.c now starts either the Wayland frontend or the X11 popup and XIM, which is where the two popups would otherwise collide. Checked by hand under headless sway 1.12, reading grim screenshots: the hanja list for 가 with its selection and 1-9/125 marker, the emoji search, the popup gone after Escape, and the same at GDK_SCALE=2. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
strans
strans is a small, single-user input method for Korean, Japanese, English, emoji, and symbols. It provides one engine for IBus (which GTK 4 and Qt use), XIM, and GTK 3. Vietnamese Telex is also available as a compatibility mode.
Input modes
| Key | Mode |
|---|---|
Ctrl+N |
Japanese Hiragana and Kanji conversion |
Ctrl+K |
Japanese Katakana |
Ctrl+S |
Korean Hangul (2-beolsik) |
Ctrl+T |
English |
Ctrl+V |
Vietnamese Telex |
Ctrl+E |
Emoji and symbol search |
Ctrl+H |
One-shot Hanja search |
Switching mode shows the mode switched to — A, 한, あ, ア, ă — in
the popup until the next key.
A Korean keyboard's 한/영 key toggles Korean and English, and its 한자 key
is Ctrl+H; a Japanese keyboard's 半角/全角 toggles Japanese and English,
ひらがな/カタカナ switches between the two kana modes, 変換 turns Japanese
on and then converts like Space, and 無変換 turns it off. Only a plain
Ctrl chord is a strans key: with Shift, Alt, or Super held it
commits what is pending and goes to the application, so Ctrl+Shift+V
still pastes.
Hiragana mode composes a complete reading, then shows its Kanji candidates
with none chosen: the exact readings of the dictionary, then the verbs and
adjectives SKK keys by stem and okurigana (かく offers 確 and 書く), and
under Space the reading in Katakana last, so a word the dictionary lacks
converts to Katakana with one Space. Space or Tab chooses the first
candidate and then steps on, wrapping (with Shift, back); Up/Down and
PageUp/PageDown move without wrapping. Once a candidate is chosen, an unmodified 1-9 commits that row of the
current page; before that the digits type. Enter commits the chosen candidate, or the
reading when none is chosen, as 0 always does; so does typing on, or any
key that ends the composition. Backspace deletes the last kana shown;
romaji that made no kana stays in the reading as typed until it is mended.
The dictionary keys a verb or adjective by its stem, so kaku offers the
readings of かく and then 書く and its kin; typing the okurigana with
Shift, as SKK does — kaKu — asks for that split first. Caps Lock is
not Shift and marks nothing.
Backspace and Esc on a chosen candidate go back to the reading, and
Esc on the reading cancels it. Katakana mode does not perform Kanji
conversion.
Korean composes one syllable at a time; Enter, Tab, Esc, and any key
that is not a jamo commit the syllable and go on to the application, so
Esc still leaves insert mode. Two lone consonants join into the compound
final they make (rt → ㄳ) and a vowel typed before its consonant is
reordered under it (kr → 가), as in libhangul.
Emoji and Hanja searches take over the keys until Enter, Space, or
1-9 picks a result or Esc cancels; they return to the previous mode
after use, and switching language during a search commits the shown
query. Tab/Shift-Tab wrap through the results, and a search with
nothing typed yet shows ☺ or 漢 in the popup. The Emoji search matches the
typed keys, and what they spell in the current language, against a prefix
of every emoji's CLDR name and keywords in English, Korean, and Japanese,
and against ASCII symbol aliases such as -> and <=. Ctrl+H takes the
syllable being composed as its query and composes on from it; Esc gives
the syllable back. The Hanja dictionary converts a word as well as a
syllable, so Ctrl+H and then 한자 gives 漢字, and 대한민국 gives 大韓民國;
a syllable already committed is the application's text, not the engine's,
and cannot be converted. Leaving the field or
clicking elsewhere commits what is pending.
Preedit and candidates
| Frontend | Preedit | Candidates |
|---|---|---|
| GTK 3 and IBus | inline in the client | strans popup |
| XIM PreeditCallbacks | inline through XIM callbacks | strans popup |
| XIM PreeditPosition | strans popup | strans popup |
| XIM PreeditNothing | strans popup | strans popup |
Each XIM style is offered with StatusNothing and with StatusNone.
Dead keys and Compose sequences are composed by strans itself for the XIM
and IBus frontends, from the table XCOMPOSEFILE or the locale names; the
GTK 3 module leaves them to GtkIMContextSimple. Their text follows
whatever was pending.
XIM text travels as COMPOUND_TEXT, which carries any UTF-8. A client that
sends XNSpotLocation gets the popup under that spot whatever its preedit
style, and above the line when there is no room below; otherwise the popup
sits under the focus window, or under the client window when no focus
window is set.
The popup is an X11 window sized by GDK_SCALE on HiDPI displays, XIM is
X11-only, and GTK popup placement converts the GTK caret to X11 root
coordinates. There is no native Wayland popup surface or Wayland caret
positioning. GTK and IBus clients can still use inline preedit where their
display environment supports it.
Build and test
Initialize the bundled test library, then build in the Docker environment:
git submodule update --init
make docker-image
make docker-build
Build output:
strans daemon with IBus and XIM frontends
gtk/im-strans.so GTK 3 frontend module
Tests have three tiers:
make check # generated-map validation and focused unit tests
make check-live # one IBus, GTK, XIM, and IPC daemon smoke
make check-stress # randomized, capacity, collision, failure, and restart tests
UNITARGS filters only the focused C unit suite, for example
make check UNITARGS=hangul. It does not select or skip live and stress
tests. make docker-check rebuilds and runs all three tiers in the
container, and make docker-valgrind runs the unit suite under Valgrind
there; run make docker-image first after changing Dockerfile.
Native Linux source builds require a C toolchain, Make, and pkg-config, plus development files for:
- Plan 9 port (
9c,9l,libthread, andlibbio); - D-Bus development files;
- XCB, XCB RandR, XCB XKB, xcb-util, xcb-imdkit, xkbcommon, and xkbcommon-x11;
- Pango, PangoCairo, Cairo, and Fontconfig;
- GTK 3, plus libibus and Xlib for the live clients;
- Xvfb for the X11 live tests;
- Python 3 and
cmpformake checkand the map generators; - a working
C.UTF-8locale and fonts covering Latin, CJK, and emoji.
The package names used by the canonical Arch Linux image are listed in
Dockerfile.
Run
The popup uses the normal system fonts found by Pango and Fontconfig. Run it directly from the build tree:
./run.sh
# equivalently
./strans map
run.sh stops every same-user process whose exact name is strans, starts one
build-tree daemon in the background, and returns to the shell. It requires
pkill from procps. Startup and frontend failures remain visible on the
caller's standard error. A service supervisor should instead run
./strans map directly in the foreground, with the session's
XDG_RUNTIME_DIR and DISPLAY: the GTK module finds the daemon at
$XDG_RUNTIME_DIR/strans.sock (else /tmp/strans.UID), and IBus clients
through the address file libibus expects under ~/.config/ibus/bus/,
which strans writes as ibus-daemon would, named after WAYLAND_DISPLAY
when there is one and DISPLAY otherwise.
The build does not copy or install the daemon or its data. ./strans DIR
opens hira.map, kata.map, telex.map, kanji.dict, emoji.dict, and
hanja.dict from DIR at runtime; run.sh passes the tracked map/
directory. Only the GTK subdirectory has install and uninstall targets.
Configure clients as needed:
# XIM
export XMODIFIERS=@im=strans
# GTK 3 module
doas make -C gtk install
export GTK_IM_MODULE=strans
# IBus client example
GLFW_IM_MODULE=ibus kitty
Building gtk/im-strans.so requires GTK development files; installing one
built elsewhere, in the container for instance, does not. The install
target uses GTK_MODULE_DIR when it is set, else GTK's pkg-config
variables, else the directory the installed gtk-query-immodules-3.0
reports. Packagers and cross builds should set GTK_MODULE_DIR, and a
prebuilt module must still match the target architecture and library ABI.
DESTDIR staging is supported and deliberately skips the host module-cache
update. A native install needs the GTK runtime query utility so it can refresh
that cache. Remove a native installation with:
doas make -C gtk uninstall
strans provides its own IBus endpoint; ibus-daemon and fcitx are not
required. IBus clients that process keys synchronously — GTK 4, or GTK 3
with IBUS_ENABLE_SYNC_MODE=1 — get their commits and preedits through
PostProcessKeyEvent, in order with the key. Without DISPLAY, the daemon and IBus frontend still work, but XIM
is not started and the popup is disabled.
Dictionary data
After changing an input source, regenerate and verify the maps and dictionaries:
python3 map/mktelex.py >map/telex.map
map/mkemoji >map/emoji.dict
map/mkhanja >map/hanja.dict
make verify-map
See map/README for the emoji, Hanja, and Japanese data and
where it comes from.
Benchmark
make bench builds bench/bench. With the daemon stopped, ./bench.sh starts
one build-tree instance, warms it up, and records the workload with Linux
perf. It requires perf and permission to profile the daemon, and writes
bench/perf.data.
Licensing
Third-party license notices are in LICENSES. The repository does
not currently declare a license for the strans source as a whole.