Basic concept

Addon

Fcitx is a input method frame work that is highly extensible via addons. There are four different type of addons in Fcitx 5.

Frontend

A Frontend Addon is a type of addon that communicate with applications. Its main task is to create input context and register input context with InputContextManager.

Input Method Engine

An input method engine receives user input from a input context. It will translate user input (usually key event) into text. Every input method engine may provides multiple different input methods.

User Interface

A user interface is a type of addon that display the user interface with information from other addons. Fcitx itself comes with two different implementation. Normally one should not implement their own User Interface addon unless there's special needs. See also Theme Customization to learn about the two built-in user interface addons.

Module

This is a type of addon that does not fall into any other categories.

• Some of them provides a sub input mode, for example, typing character with their Unicode.
• Some of them provides integration with desktop, e.g. notification item for Status Notifier-based tray icon.
• Some of them manages the low level connection to the display server, e.g. xcb/wayland.
• Some of them even can provides integration with other languages, such as luaaddonloader.

Input Context

An input context represents a client to Fcitx server. Usually, an input context may be mapped to an application, a window of the applicaiton, or a global context of the display server. When a input context has focus, it means that this specific client is actively used by user and the window of the input context should also have the focus.

Based on different display server, input context may falls into different focus group. Every focus group is mapped to one display connection, e.g. X11, Wayland. Every focus group contains a set of input context, and at most one of them will have focus in the group. A input context may also have no focus group.

Event handling

There are 5 stage of event handling for one event, only 3 of the stages are exposed to user, which are Default, PreInputMethod, and PostInputMethod. There are also ReservedFirst and ReservedLast used by Fcitx internally. The order of different stages is ReservedFirst, PreInputMethod, Default, PostInputMethod, ReservedLast. The Default stage just after the active input method engine receives event. PreInputMethod is one of the most commonly used one to implement sub input method. For example, an addon may define a trigger key. When the trigger key is pressed by user, it sets a flag and handle all the future key event in the PreInputMethod stage until it ends its input mode.

As for the event type, there are input context specific events and global events. The input context specific events always associate with an input context.

Life of a Key Event

From an actual physical keyboard press to the key event that receives by Fcitx may go through following steps.

Reaching Fcitx Frontend

Depending on the protocol between Fcitx and application, there are several different path that might be exercised.

Fcitx frontend is where Fcitx receives the key event from application and display server.

XIM

Upon application receives a KeyEvent from X Server, it need to use XIM protocol to forward it to the XIM server. The key event contains only modifier state and key code. The actual key sym is derived from the X Server key map.

DBusFrontend/IBusFrontend/Fcitx4Frontend

These frontends are similar, but just using different dbus interfaces. When application receives a key event from toolkit (e.g. Gtk/Qt/SDL), it forward the key event to Fcitx via some dbus interfaces. The key sym comes from the translation inside the application, but key code and modifier state are also available.

Wayland IM

There's zwp_input_method_v1 and zwp_input_method_v2. In V1, the key event is from application and goes through a similar code path like DBus. In V2, Input method will need to create a keyboard grab and Compositor will forward all the key to input methods. The key code to key sym translation is done on the Fcitx side, with the keymap from compositor.

From Frontend to Fcitx event pipe line and Input Method Engine

Inside Fcitx, The Key event will be wrapped as a KeyEvent object, and be processed by the Fcitx event pipeline. Before sending to the pipeline, if the current layout to be used is not same as the system layout, Fcitx will apply its own XKB translation and store the translated key object in the field rawKey. The field key() will be updated accordingly as a normalized rawKey form.

Then it goes through multiple stages and it might be filtered in the middle of the pipeline to prevent any future process.