repository·master·Indexed 25 days ago
https://github.com/fcitx/fcitx5A next-generation, generic input method framework for Linux and BSD. It provides core infrastructure for keyboard layouts and serves as a base for language-specific input engines. The framework supports X11 and Wayland, and includes developer utilities for managing hierarchical configurations via RawConfig, DBus connectivity through the Bus class, and keyboard event handling via the fcitx::Key class.
The core fcitx5 repository contains only the keyboard layout engine. To support specific languages such as Chinese, Japanese, or Korean, you must install corresponding input method engines separately.
A complete list of available input method engines can be found on the Fcitx Wiki.
Fcitx 5 is a generic input method framework released under LGPL-2.1+. You can install it via several methods:
Developers looking to extend Fcitx 5 can follow these guides:
Fcitx 5 supports X11 and Wayland display servers.
If you need to use an input method under a TTY (Teletypewriter), you must use additional tools, as not all features are supported natively. Recommended tools include:
fbterm (fcitx5-fbterm)tmux (fcitx5-tmux)The RawConfig class provides a hierarchical tree structure for managing key-value pairs, suitable for formats like INI. Each node in the tree can contain a value, a comment, and sub-items (child nodes). Paths are represented using / as a separator.
Key capabilities include:
"group/subgroup/key").implicit so they act as default values and are not written to the physical INI file when saved.[] operator or setValueByPath to modify the configuration tree.To create a new plugin or addon in fcitx5, you must create a subclass of fcitx::AddonInstance.
Key lifecycle methods you can override:
reloadConfig(): Called to reload configuration from disk.save(): Called to save relevant data (typically when fcitx exits).getConfig(): Returns a pointer to the addon's Configuration.setConfig(const RawConfig &): Sets configuration from a RawConfig object.To make your addon discoverable as a SharedLibrary addon, you must also use the FCITX_ADDON_FACTORY(ClassName) macro to export the factory.
Fcitx5 uses an event-driven system for interacting with input contexts. Most events related to a specific client (like focus changes, key presses, or capability updates) are subclasses of InputContextEvent. You can identify if an event is an input context event using isInputContextEvent().
Common input context events include:
FocusInEvent: Triggered when a client gains focus.FocusOutEvent: Triggered when a client loses focus. Note that by default, Fcitx may commit preedit text during this event depending on the Output/DontCommitPreeditWhenUnfocus configuration.KeyEvent: Represents a key press or release.CommitStringEvent: Contains text to be committed to the client.InputContextSwitchInputMethodEvent: Triggered when the user switches input methods manually.An InputContext represents a client of Fcitx, such as a window or a specific text field within an application. It serves as the primary interface for communication between the Fcitx core (and input methods) and the application frontend.
Key responsibilities include:
focusIn() and focusOut().commitString() or commitStringWithCursor(), and managing surrounding text via surroundingText().forwardKey().updatePreedit() and coordinating with the InputPanel and StatusArea.Developers implementing a new frontend should inherit from InputContext (or InputContextV2 if cursor-based commits are required) and implement the protected virtual methods like commitStringImpl, deleteSurroundingTextImpl, and forwardKeyImpl to bridge Fcitx commands to the application's actual text handling logic.
Addons can export specific functions that other addons can invoke. This requires a three-step process involving CMake, a header declaration, and the implementation macro.
CMake Configuration: Use fcitx5_export_module in your CMakeLists.txt to export the module, including its public headers.
Header Declaration: Use FCITX_ADDON_DECLARE_FUNCTION in a public header to define the function signature and create a meta-type for it.
Implementation: Use FCITX_ADDON_EXPORT_FUNCTION inside your addon class to register the function. This macro performs a compile-time check to ensure the implementation matches the declared signature.
Example Implementation:
// In dummyaddon_public.h
FCITX_ADDON_DECLARE_FUNCTION(DummyAddon, addOne, int(int));
// In dummyaddon.cpp
class DummyAddon : public fcitx::AddonInstance {
public:
int addOne(int a) { return a + 1; }
FCITX_ADDON_EXPORT_FUNCTION(DummyAddon, addOne);
};FCITX_ADDON_DECLARE_FUNCTION(DummyAddon, addOne, int(int));
class DummyAddon : public fcitx::AddonInstance {
public:
int addOne(int a) { return a + 1; }
FCITX_ADDON_EXPORT_FUNCTION(DummyAddon, addOne);
};To call a function exported by another addon, first obtain a pointer to that addon via the AddonManager. Then, use the .call<...>() template method, passing the appropriate meta-type generated by the FCITX_ADDON_DECLARE_FUNCTION macro.
// Assuming DummyAddon is already obtained via AddonManager
int result = addon->call<fcitx::IDummyAddon::addOne>(7);addon->call<fcitx::IDummyAddon::addOne>(7);The FCITX_ADDON_DEPENDENCY_LOADER macro provides a convenient way to lazily load and access a dependency addon within your own addon code without manually managing the AddonManager calls every time.
// Inside your addon class or implementation file
FCITX_ADDON_DEPENDENCY_LOADER(TargetAddonName, MyAddonManager)
void someFunction() {
// TargetAddonName() returns the pointer to the addon instance
if (TargetAddonName()) {
// use the addon
}
}To access or perform actions on all available input methods, use the foreachEntries method. It accepts a callback function that is executed for each InputMethodEntry.
If the callback returns false, the enumeration is interrupted immediately.