• Windows
  • C++
  • TSF
  • input method

A Vietnamese IME on TSF instead of a keyboard hook

Why Goxvi is a TSF input method, not a global keyboard hook: keeping it working in games with anti-cheat, and swallow-commit-replay for word-ending keys.

Goxvi is a Vietnamese input method for Windows (Telex and VNI). The goal that shaped its design is simple to state: typing Vietnamese in a chat box should never get in the way of the game running in the same session. Movement keys like WASD must reach the game untouched, every time.

This post covers three decisions behind that: building on Text Services Framework, registering for secure mode, and how keys that end a word are handled.

Hook versus text service

There are two broad ways to build a Vietnamese input method on Windows.

A global keyboard hook sits in front of every key press in the system. It sees keys typed into a game exactly like keys typed into a chat window, and has to decide for each one whether to step in. The input method is in the path of WASD whether or not you are typing text.

A text service built on Text Services Framework (TSF) is the path Windows provides for input methods. Goxvi is a TSF text input processor: a COM DLL that Windows loads into the app, which receives keys through ITfKeyEventSink only when a text context has focus. When nothing is asking for text, Goxvi is not involved.

Goxvi keeps the TSF part thin. The Telex and VNI logic lives in a separate C++20 library with no Windows API calls, so it is unit-tested in seconds without registering anything. The TSF shim translates key events into engine calls and engine output into a hidden composition (no underline, like the input methods Vietnamese users are used to).

Games activate TSF in secure mode

The first real-world surprise came from games. A game with anti-cheat (League of Legends was the case that exposed it) activates TSF with ActivateEx(TF_TMAE_SECUREMODE). In that mode, the TSF runtime loads only text services registered with the secure-mode category. A probe confirmed it: with that activation flag, a text service without the category is simply not loaded.

Without it, Goxvi was dead in the game until the user toggled the input mode by hand. Every built-in Microsoft text service has the category, so registering it is the expected thing to do. Goxvi registers both secure mode and COM-less activation (activation on a thread that never initialized COM; code paths there degrade safely):

// Part of the category list Goxvi registers for its text service.
const GUID categories[] = {
    GUID_TFCAT_TIP_KEYBOARD,
    GUID_TFCAT_TIPCAP_SECUREMODE,
    GUID_TFCAT_TIPCAP_COMLESS,
};
for (const GUID& category : categories) {
    categoryMgr->RegisterCategory(CLSID_GoxviTextService, category, CLSID_GoxviTextService);
}

Registering for secure mode comes with a duty to behave. When the activation flags include secure mode, Goxvi shows no UI, respects password fields (keys pass straight through), and skips its mouse helper (below) to keep its footprint small inside games and elevation prompts. Debug key logging is compiled out of release builds entirely: an input method that logs keys is keylogger-shaped code.

Keys that end a word: swallow, commit, replay

While you type a word, Goxvi holds it in a composition. A space, Enter, punctuation or a navigation key ends the word. The naive approach commits the word and lets the key continue to the app. In most apps that works. In some it does not, because the committed text travels a slower, asynchronous route than the raw key:

  • In a terminal over SSH, pressing PageUp to search history right after typing sent the key before the text, so the shell searched the wrong prefix.
  • In Explorer’s rename box, Enter confirmed the old file name, and a - typed after a word landed in front of it (-abc).

The fix is to make sure the text always arrives first:

  1. Swallow the key: report it as eaten, so the app does not see it yet.
  2. Commit the word.
  3. Replay the key with SendInput, tagged so Goxvi’s own sink recognizes it (through GetMessageExtraInfo) and lets it pass.

The eat decision is made identically in OnTestKeyDown and OnKeyDown; the commit and replay happen only in OnKeyDown, so a test call never has side effects. The same mechanism is used by Microsoft’s built-in Telex, and Goxvi applies it in every app instead of keeping a list of special cases. When no word is in progress, keys pass through untouched, so WASD in a game never takes this path. Shortcuts with Ctrl, Alt or Win are different again: the word is committed but the key is not swallowed, because the app has to see the real chord with live modifier state.

The one hook Goxvi does use

Clicking in the middle of a word caused lost text in some hosts (Telegram, Sublime, WinForms text boxes): they treat the composition as temporary and cancel it on click. Goxvi handles this with a thread mouse hook installed inside the app’s own process, not a global one. On a button press it commits the word first, then swallows the click and replays it the same way as a key, so the text lands before the click is processed. In secure mode this hook is skipped.

Takeaways

  • Use the input path the OS provides for input methods. It is called only when text is wanted, which is exactly what you want in a game.
  • If you plug into TSF, register the capability categories that built-in text services have. Missing secure mode means silently not loading.
  • When ordering between text and keys matters, do not rely on timing. Swallow the key, commit, and replay it.
  • Keep the language logic in a plain library. Most of the hard work is testable without Windows at all.

Written by Duy Pham Independent developer. I build the apps on this site and write about how they work.

More about me