Basic concept

From Fcitx
Revision as of 01:56, 19 November 2021 by Weng Xuetian (talk | contribs)
Jump to navigation Jump to search


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


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.


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.