Fcitx - User contributions [en]

Develop an simple input method/zh-cn

2026-01-05T08:44:39Z

Weng Xuetian:

<languages />
这是编写 Fcitx 5 输入法的分步说明。同样的步骤也可以用于开发其他类型的插件，只是输入法引擎是最复杂的。

= 了解 Fcitx 共享库插件的文件结构 =
Fcitx 5 提供了一个用于添加新插件类型的可扩展框架，但共享库支持是内置的，并且是所有其他插件类型的基础。所以我们只会在本文档中介绍共享库插件。

<nowiki>
[fcitx install prefix]
|
|- share/fcitx5
| |
| |- addon/[addon name].conf
| |- inputmethod/[input method name 1].conf
| | ...
| |- inputmethod/[input method name n].conf
|
|- lib/fcitx5
|
|- [library name].so
</nowiki>

以上是输入法插件的文件结构。对于其他类型的插件，不需要 <code>inputmethod/</code> 下的文件。<code>[addon name].conf</code> 的文件名很重要，将用于唯一引用此特定插件。Fcitx 也遵循 XDG 目录标准，所以 XDG_DATA_DIR/fcitx5 下的文件也会被检查。同样，<code>inputmethod/</code>下的配置文件的文件名也很重要，将是某个输入法的唯一名称。

<code>[addon name].conf</code> 示例

<nowiki>[Addon]
Name[ca]=Pinyin
Name[da]=Pinyin
Name[de]=Pinyin
Name[he]=פיניין:
Name[ko]=병음
Name[ru]=Пиньинь
Name[zh_CN]=拼音
Name=Pinyin
Category=InputMethod
Version=5.0.8
Library=pinyin
Type=SharedLibrary
OnDemand=True
Configurable=True

[Addon/Dependencies]
0=punctuation

[Addon/OptionalDependencies]
0=fullwidth
1=quickphrase
2=cloudpinyin
3=notifications
4=spell
5=pinyinhelper
6=chttrans
7=imeapi
</nowiki>

<code>[输入法名称].conf</code>示例

<nowiki>[InputMethod]
Name[ca]=Pinyin
Name[da]=Pinyin
Name[de]=Pinyin
Name[he]=פיניין:
Name[ko]=병음
Name[ru]=Пиньинь
Name[zh_CN]=拼音
Name=Pinyin
Icon=fcitx-pinyin
Label=拼
LangCode=zh_CN
Addon=pinyin
Configurable=True
</nowiki>

该文件采用类似 ini 的格式，具有某些 fcitx 特定的扩展名和规则。它还支持 XDG 桌面文件样式 i18n 进行翻译。

= 使用 CMake 构建系统 =
理论上只要能生成正确的文件，就可以自由选择要使用的构建系统。但是Fcitx 5 对 CMake 提供了大量支持，因此使用 CMake 将是构建 Fcitx 项目的最便捷方式。在本文档中，我们将仅介绍使用 CMake 作为构建系统。

= 快速入门：区位码 =
[[wikipedia:区位码_(国标)|区位码]] 输入法是一种输入法，允许您简单的输入GB2312的数字并产生与该代码匹配的汉字。它曾经被 Fcitx 4 支持，但不再被 Fcitx 5 包含。虽然它很难使用，但它可以作为一个很好的例子来说明如何为 Fcitx 5 实现一个简单的输入法。

== 项目框架 ==
因此，让我们从这个项目的框架开始。

<nowiki>├── CMakeLists.txt
├── LICENSES
│ └── BSD-3-Clause.txt # License for this project
├── po # Optional I18n
│ ├── CMakeLists.txt
│ ├── fcitx5-quwei.pot
│ ├── LINGUAS
│ └── zh_CN.po
└── src
├── CMakeLists.txt
├── quwei-addon.conf.in.in # Addon registration file
├── quwei.conf.in # Input method registration file
├── quwei.cpp # Engine implementation
└── quwei.h # Engine implementation
</nowiki>

您也许需要查看一些 CMake 教程以了解一些基本的 CMake 用法。

CMakeLists.txt 在根目录查找依赖项。

<nowiki>
cmake_minimum_required(VERSION 3.21)
project(fcitx5-quwei)

find_package(Fcitx5Core REQUIRED)
# Setup some compiler option that is generally useful and compatible with Fcitx 5 (C++17)
include("${FCITX_INSTALL_CMAKECONFIG_DIR}/Fcitx5Utils/Fcitx5CompilerSettings.cmake")

add_subdirectory(src)</nowiki>

src/CMakeLists.txt 示例如下：

<nowiki># Make sure it produce quwei.so instead of libquwei.so
add_library(quwei SHARED quwei.cpp)
target_link_libraries(quwei PRIVATE Fcitx5::Core)
set_target_properties(quwei PROPERTIES PREFIX "")
install(TARGETS quwei DESTINATION "${FCITX_INSTALL_LIBDIR}/fcitx5")

# Addon config file
# We need additional layer of conversion because we want PROJECT_VERSION in it.
configure_file(quwei-addon.conf.in quwei-addon.conf)
install(FILES "${CMAKE_CURRENT_BINARY_DIR}/quwei-addon.conf" RENAME quwei.conf DESTINATION "${FCITX_INSTALL_PKGDATADIR}/addon")

# Input Method registration file
install(FILES "quwei.conf" DESTINATION "${FCITX_INSTALL_PKGDATADIR}/inputmethod")</nowiki>

quwei.conf.in 示例：

<nowiki>[InputMethod]
# Translatable name of the input method
Name=Quwei
# Icon name
Icon=fcitx-quwei
# A short label that present the name of input method
Label=区
# ISO 639 language code
LangCode=zh_CN
# Match addon name
Addon=quwei
# Whether this input method support customization
# Configurable=True</nowiki>

此文件将作为 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputMethodEntry.html InputMethodEntry] 对象进行加载。

quwei-addon.conf.in 示例：

<nowiki>[Addon]
Name=Quwei
Category=InputMethod
Version=@PROJECT_VERSION@
Library=quwei
Type=SharedLibrary
OnDemand=True
Configurable=True

[Addon/Dependencies]
0=punctuation

[Addon/OptionalDependencies]
0=fullwidth
1=quickphrase
2=chttrans</nowiki>

此文件将作为 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1AddonInfo.html AddonInfo] 对象加载。

== InputMethodEngine 的基本实现 ==
您可以参考github中[https://github.com/fcitx/fcitx5-quwei/commit/02c32b07e47e0e75db4f248dbb33c31137d8df74 第一笔提交]的代码。

版本 1 的 quwei.h
<nowiki>/*
* SPDX-FileCopyrightText: 2021~2021 CSSlayer <wengxt@gmail.com>
*
* SPDX-License-Identifier: BSD-3-Clause
*
*/
#ifndef _FCITX5_QUWEI_QUWEI_H_
#define _FCITX5_QUWEI_QUWEI_H_

#include <fcitx/inputmethodengine.h>
#include <fcitx/addonfactory.h>

class QuweiEngine : public fcitx::InputMethodEngineV2 {
void keyEvent(const fcitx::InputMethodEntry & entry, fcitx::KeyEvent & keyEvent) override;
};

class QuweiEngineFactory : public fcitx::AddonFactory {
fcitx::AddonInstance * create(fcitx::AddonManager * manager) override {
FCITX_UNUSED(manager);
return new QuweiEngine;
}
};

#endif // _FCITX5_QUWEI_QUWEI_H_</nowiki>

版本 1 的 quwei.cpp

<nowiki>/*
* SPDX-FileCopyrightText: 2021~2021 CSSlayer <wengxt@gmail.com>
*
* SPDX-License-Identifier: BSD-3-Clause
*
*/
#include "quwei.h"

void QuweiEngine::keyEvent(const fcitx::InputMethodEntry& entry, fcitx::KeyEvent& keyEvent)
{
FCITX_UNUSED(entry);
FCITX_INFO() << keyEvent.key() << " isRelease=" << keyEvent.isRelease();
}

FCITX_ADDON_FACTORY(QuweiEngineFactory);</nowiki>

当实现 Fcitx 插件时，它应该是 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1AddonInstance.html AddonInstance] 的子类。AddonInstance 的实例化是通过 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1AddonFactory.html AddonFactory] 完成的。 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputMethodEngineV2.html InputMethodEngineV2] 是 AddonInstance 的子类。实现输入法插件时需要使用该类。

一个输入法引擎的最小植入只需要包含keyEvent函数的实现。

在这里，我们使用类似于宏 <code>FCITX_INFO()</code> 的 iostream 将我们按下的每个键写入日志。

这里假设您的 fcitx 安装前缀是 /usr。构建这个项目的命令是：

<nowiki>
mkdir -p build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug # use Debug for easy debugging with gdb
make # or ninja, depending on your system
sudo make install # or sudo ninja install</nowiki>

如果一切正常，安装命令应该打印出如下内容：

<nowiki>-- Install configuration: "Debug"
-- Installing: /usr/lib/fcitx5/quwei.so
-- Installing: /usr/share/fcitx5/addon/quwei.conf
-- Installing: /usr/share/fcitx5/inputmethod/quwei.conf</nowiki>

现在您可以使用 <code>fcitx5 -rd</code> 重新启动 fcitx5，并使用 [[Special:myLanguage/Configtool (Fcitx 5)|配置工具（Fcitx 5）]] 将 Quwei 添加到您的配置中。

切换到区位码输入法后，应用程序中的按键将使 Fcitx 5 打印出如下内容：

<nowiki>I2021-11-16 12:29:32.352702 quwei.cpp:12] Key(f states=0) isRelease=1
I2021-11-16 12:29:32.389935 quwei.cpp:12] Key(s states=0) isRelease=0
I2021-11-16 12:29:32.413689 quwei.cpp:12] Key(d states=0) isRelease=0
I2021-11-16 12:29:32.497661 quwei.cpp:12] Key(s states=0) isRelease=1
I2021-11-16 12:29:32.498021 quwei.cpp:12] Key(f states=0) isRelease=0
I2021-11-16 12:29:32.523816 quwei.cpp:12] Key(a states=0) isRelease=1
I2021-11-16 12:29:32.524051 quwei.cpp:12] Key(d states=0) isRelease=1
I2021-11-16 12:29:32.704919 quwei.cpp:12] Key(f states=0) isRelease=1
I2021-11-16 12:29:32.705006 quwei.cpp:12] Key(d states=0) isRelease=0
I2021-11-16 12:29:32.833024 quwei.cpp:12] Key(d states=0) isRelease=1
I2021-11-16 12:29:34.633936 quwei.cpp:12] Key(Control_L states=0) isRelease=0
I2021-11-16 12:29:35.053817 quwei.cpp:12] Key(Control+C states=4) isRelease=0
I2021-11-16 12:29:35.165617 quwei.cpp:12] Key(Control+C states=4) isRelease=1
I2021-11-16 12:29:35.348654 quwei.cpp:12] Key(Control+Control_L states=4) isRelease=1</nowiki>

从这里可以知道您的输入法引擎现在可以正常工作了。

= 实现输入法逻辑 =
区位码的基本逻辑是键入 4 位数的区位代码。区位码可以看成区码 xx 和位码 yy。区位码到GB2312的映射是(0xA0 + 区码, 0xA0 + 位码)。当用户键入 3 个数字的区位码时，输入法将显示一个包含 10 个可能带有给定区码为前缀的字符的候选列表。

可以参考 github 中 [https://github.com/fcitx/fcitx5-quwei/commit/b9b047abb46fa0f9c42a0be82941b65b35b277eb 第二笔提交] 的代码。

== 存储不同输入上下文的状态 ==
Fcitx 允许不同的输入上下文保持不同的状态。状态通常是指部分类型化的文本和所有其他关联的数据结构。在这个区位码的例子里面，状态是用户已经输入的数字。为了表示这一点，Fcitx 提供了一个方便的类 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputBuffer.html InputBuffer] 让输入法引擎可以便捷地使用这个类来编辑内部状态。为了在构造输入上下文时自动构造状态，Fcitx 提供了一个名为 InputContextProperty 的框架。为了使用它，您首先需要通过 registerProperty 向 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputContextManager.html InputContextManager] 注册一个工厂类。每个属性都需要有一个全局唯一的名称。名称可以是人类可以理解的东西。在这个区位码的例子里面，我使用的是“quweiState”。使用更好的名称的好处是，以防万一您正在开发一些交叉插件（另一个插件需要访问该插件的某些内部状态），您可以使用这个通用名称将其加载到不同的插件中。如果您不需要从外部访问，那么名称并不重要。

工厂类带有一个方便的 C++ 模板，[https://codedocs.xyz/fcitx/fcitx5/group__FcitxCore.html#ga9e60042d1f671a6fa31ea04bb4961ec9 FactoryFor]。这实际上是 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1LambdaInputContextPropertyFactory.html LambdaInputContextPropertyFactory] 的类型别名。该类仅接受 lambda 函数作为工厂实现。这可以节省您创建自己的 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputContextPropertyFactory.html InputContextPropertyFactory] 子类的时间。

为了从输入上下文中获取状态对象，您可以像这样简单地使用工厂对象：

<nowiki>
auto *state = ic->propertyFor(&factory_);</nowiki>

在某些情况下，也可以注销工厂并重新注册以“刷新”所有内部状态。

== 候选词列表 ==
在 Fcitx 5 中，候选列表是 InputPanel 类的一部分，存储为 shared_ptr 以避免选择候选触发用户界面更新时的生命周期问题。候选列表通过某些接口提供了不同的功能。辅助类 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1CommonCandidateList.html CommonCandidateList] 将为候选列表提供最常用的功能。它实现了 BulkCandidateList 接口，这就是为什么它不适合去中心化的情况。因为我们要有一个曲尾的半无限候选列表。

区位码中，QuweiCandidateList 将实现一个 PageableCandidate 接口，该接口允许在输入法面板中显示上一页/下一页按钮。

== 预编辑 ==
预编辑可以指代两种不同的用户界面元素，一种是嵌入在应用程序中的预编辑，在 Fcitx 中通常称为“客户端预编辑”。另一个显示在输入法面板窗口中。通常，输入法引擎只会使用其中一种，因为只有一种形式的预编辑需要显示。可以通过 capabilityFlags 属性检查输入上下文是否支持它。

在使用客户端预编辑时，您可能还需要考虑一些事项。由于 toolkit 中的实现不同，toolkit 可能会选择在应用程序失去焦点时立即提交客户端预编辑。对于某些输入法，它可能被设计成不需要额外确认的输入方式，例如，键盘引擎中的单词完成模式。在这种情况下，即使使用了预编辑，用户仍希望提交文本，即使它仍处于预编辑模式。从这个意义上说，预编辑文本应该与确认后提交的文本完全相同。

在某些版本的 iOS 中，其拼音输入法使用其客户端预编辑的方式可能会导致混淆：用户键入“nihao”，而客户端预编辑显示为分段拼音“ni hao”。当文本框失去焦点时，“ni hao”（多余的空格）将被提交到应用程序中，而这种结果在拼音的常规使用中永远不会发生。

另一件需要考虑的事情是把光标放在哪里。虽然在预编辑中将光标显示在其实际位置可能很自然，但输入面板窗口也会显示在客户端预编辑光标位置。也就是说，随着用户正常打字，当光标移动时，候选窗口也会随之移动。在某些情况下，这是不可取的，因为它会导致候选窗口在用户键入时频繁移动。另一种处理方法是将客户端光标始终设置为 0。如果需要支持显示实际光标的位置，则可以使用高亮样式。例如，当你在预编辑中有“ABCD”，光标在B和C之间时，你可以将客户端光标设置为0，使“AB”以高亮方式显示，以指示光标的位置。

== 按键事件处理 ==
最常见的用例是为您打算处理的所有按键事件调用 filterAndAccept()。此外，对于大多数输入法，按键释放是不相关的，应该传递给应用程序。要使输入法引擎能够处理任何用户输入，请务必考虑用户可能键入的所有可能的按键事件。例如，一个常见的错误是在组合模式中忘记屏蔽某个不相关的密钥，并将密钥泄露到应用程序中。另外，请注意带有修饰符的键事件，您可能希望传递此类键以使应用程序特定的热键即使在用户正在编写时仍然可以访问。

此外，一个按键事件有 3 种不同形式的 Key 对象。通常输入法引擎可能只想考虑 key() 属性。origKey() 和 rawKey() 属性使用较少。键属性是键事件的规范化形式。这删除了某些情况下的“Shift”修饰符，这使得输入法引擎更容易处理。例如，通过 Shift+A 和 Capslocked A 生成的大写字母 A 在归一化后将相同。您可以参考实现以了解此规范化的工作原理。

= 重用其他插件的功能 =
你可以参考 github 中 [https://github.com/fcitx/fcitx5-quwei/commit/b01bf8c4344b50b496593b4d9cf8be49cd1ce9c2 第三次提交] 的代码。

Fcitx 提供了一种机制来调用其他插件的功能，而无需直接链接到它们。还有一些易于使用的 CMake 宏来查找插件依赖项。

<nowiki>find_package(Fcitx5Module REQUIRED COMPONENTS Punctuation QuickPhrase)</nowiki>

我们在上面添加 find_package 行以查找 Punctuation 和 QuickPhrase 模块的依赖项。

如果你想实现这样的模块，你可以使用下面的CMake宏

<nowiki>fcitx5_export_module(QuickPhrase TARGET quickphrase BUILD_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_SOURCE_DIR}" HEADERS quickphrase_public.h INSTALL)</nowiki>

它会自动为您的插件生成所需的 CMake 配置。

When using other addons in the code, there is a handy macro <code>FCITX_ADDON_DEPENDENCY_LOADER</code> that will handle the addon loading at the runtime. When it is called for the first time, the dependent addon will be loaded automatically. Here we defines four different dependency in the code:

<nowiki> FCITX_ADDON_DEPENDENCY_LOADER(quickphrase, instance_->addonManager());
FCITX_ADDON_DEPENDENCY_LOADER(punctuation, instance_->addonManager());

private:
FCITX_ADDON_DEPENDENCY_LOADER(chttrans, instance_->addonManager());
FCITX_ADDON_DEPENDENCY_LOADER(fullwidth, instance_->addonManager());</nowiki>

第一个参数应与插件名称相同，第二个参数是获取 AddonManager 对象的表达式。

这种机制使得重用其他插件实现的功能和共享代码变得容易。比如 classicui 从 xcb addon 和 wayland addon 查询 X11/wayland 连接。

= 配置 =
虽然区位码并不真正需要这个功能，因为它是一个非常常见的用例，所以它会在本节中介绍。该插件有几个与配置相关的不同接口，例如 getConfig、setConfig、getConfigForInputMethod、setConfigForInputMethod、reloadConfig。getter 函数需要返回一个 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1Configuration.html Configuration] 对象，而 setConfig 接受一个 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1RawConfig.html RawConfig]目的。reloadConfig 将被调用以从磁盘重新加载配置，您可能也想在插件的构造函数中调用 reloadConfig()。

如果在插件注册文件中将 Configurable 字段设置为 True，则会调用此类方法来检索信息，Configtool 会为其生成 UI。

<nowiki>FCITX_CONFIGURATION(
ClipboardConfig, KeyListOption triggerKey{this,
"TriggerKey",
_("Trigger Key"),
{Key("Control+semicolon")},
KeyListConstrain()};
KeyListOption pastePrimaryKey{
this, "PastePrimaryKey", _("Paste Primary"), {}, KeyListConstrain()};
Option<int, IntConstrain> numOfEntries{this, "Number of entries",
_("Number of entries"), 5,
IntConstrain(3, 30)};);</nowiki>

通常，您将使用 FCITX_CONFIGURATION 宏定义 Configuration 的子类。第一个参数是类的名称，然后您只需添加 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1Option.html Option] 作为成员。以下是 setConfig/getConfig/reloadConfig 的常见实现。

<nowiki> static constexpr char configFile[] = "conf/clipboard.conf";
void reloadConfig() override { readAsIni(config_, configFile); }

const Configuration *getConfig() const override { return &config_; }
void setConfig(const RawConfig &config) override {
config_.load(config, true);
safeSaveAsIni(config_, configFile);
}</nowiki>

readAsIni 和 safeSaveAsIni 是辅助函数，用于从 Fcitx ini 格式读取/保存配置对象。该文件保存在 $XDG_CONFIG_HOME 下。

Translations:Develop an simple input method/3/zh-cn

2026-01-05T08:44:38Z

Weng Xuetian:

Fcitx 5/zh-cn

2025-07-08T13:10:10Z

Weng Xuetian:

<languages/>

小企鹅输入法（Fcitx 读作[ˈfaɪtɪks]）是一个支持扩展的输入法框架。目前，它支持Linux操作系统，以及如freebsd这样的Unix操作系统。Fcitx 通过使用各种各样的输入法引擎来支持全世界大量不同种类的语言。

Fcitx本身的核心实现非常简单，它通过使用插件来提供强大的功能。fcitx可以非常容易的进行定制以满足不同的个性化需求。

[[Special:myLanguage/Fcitx|导航至旧版的 Fcitx 4 Wiki页面?]]

==== 用户 ====

* [[Special:myLanguage/Install Fcitx 5|如何安装 Fcitx 5]]
* [[Special:myLanguage/Setup Fcitx 5|设置 Fcitx 5]]
* 安装 [[Special:myLanguage/Input method engines|输入法引擎]]
* [[Special:myLanguage/Theme Customization|定制您的输入法主题]]
* [[Special:myLanguage/FAQ|常见问题]]
* [[Special:myLanguage/Using Fcitx 5 on Wayland|在 Wayland 上使用 Fcitx 5]]
* [[Special:myLanguage/Tips and Tricks|使用技巧]]
* [[Special:myLanguage/Upgrade from Fcitx 4|从 Fcitx 4 升级]]

==== 开发者 ====

* [[Special:myLanguage/Compiling fcitx5|如何编译 fcitx5]]
* [[Special:myLanguage/Basic concept|基本概念]]
* [[Special:myLanguage/Develop an simple input method|如何开发一个简单的输入法]]
* [[Special:myLanguage/Q&A for developer|开发者常见问题与解答]]
* [[Special:myLanguage/Debug fcitx5|调试 fcitx5]]

==== 新闻 ====

<rss max=5 template="Template:GithubAtom">https://github.com/fcitx/fcitx5/releases.atom</rss>

== 如何帮助 Fcitx ==
* 给你的朋友推荐Fcitx输入法
* [[Special:myLanguage/Report Bug|报告漏洞]]
* [[Special:myLanguage/Contribute to this Wiki|为Wiki做贡献]] ('''请在申请你的帐号之前仔细阅读此页面''')
* [[Special:myLanguage/Donate|捐助]]

== 关于 ==
* [[Special:myLanguage/History|Fcitx的历史]]

Translations:Fcitx 5/9/zh-cn

2025-07-08T13:10:09Z

Weng Xuetian:

<rss max=5 template="Template:GithubAtom">https://github.com/fcitx/fcitx5/releases.atom</rss>

Input method engines/zh-cn

2025-07-04T02:32:23Z

Weng Xuetian:

<languages />

= 配置 =
安装新的输入法包后，从命令或托盘菜单启动配置工具 [[Special:myLanguage/Configtool (Fcitx 5)|fcitx5-configtool]]。应该有一个带有按钮的消息，允许重新加载或重新启动 Fcitx 5 以使新的输入法引擎准备好使用。这仅适用于非 flatpak Fcitx 5。

对于旧的 flatpak 版本，则需要手动重启。基于 Flatpak 的 fcitx 5 中的重启功能不会重新加载沙箱，因此新的扩展包仍然不可见。必须完全退出 Fcitx 并启动一个新实例以使其加载新的 flatpak 扩展包。

从 5.0.16 开始，“重启”将能够启动一个新的更新的 flatpak 版本，就像普通版本一样。

=中文=
* [https://pkgs.org/search/?q=fcitx5-chinese-addons fcitx5-chinese-addons]。它包括简体中文最常用的输入法，包括拼音和码表（五笔等）引擎。
* [https://pkgs.org/search/?q=fcitx5-table-extra fcitx5-table-extra]。附加中文表
* [https://pkgs.org/search/?q=fcitx5-chewing fcitx5-chewing]。基于libchewing的咀嚼引擎。
* [https://pkgs.org/search/?q=fcitx5-zhuyin fcitx5-zhuyin]。基于lib注音的注音输入法引擎。
* [https://pkgs.org/search/?q=fcitx5-rime fcitx5-rime]。一种可自定义的输入法，但默认情况下其默认配置为拼音。
= 日语 =
* [https://pkgs.org/search/?q=fcitx5-anthy fcitx5-anthy]
* [https://pkgs.org/search/?q=fcitx5-kkc fcitx5-kkc]
* [https://pkgs.org/search/?q=fcitx5-mozc fcitx5-mozc]
* [https://pkgs.org/search/?q=fcitx5-skk fcitx5-skk]
=韩文=
* [https://pkgs.org/search/?q=fcitx5-hangul fcitx5-hangul]
= 越南语 =
* [https://pkgs.org/search/?q=fcitx5-unikey fcitx5-unikey]
=泰语=
* [https://pkgs.org/search/?q=fcitx5-libthai fcitx5-libthai]
= 僧伽罗语 =
* [https://pkgs.org/search/?q=fcitx5-sayura fcitx5-sayura]
= 多语言（如果上面没有列出，这可能是您需要的）=
* [https://pkgs.org/search/?q=fcitx5-m17n fcitx5-m17n]
* [https://pkgs.org/search/?q=fcitx5-keyman fcitx5-keyman]
* [https://pkgs.org/search/?q=fcitx5-table-other fcitx5-table-other]，它提供了许多其他表格，但如果适合您，建议您更喜欢 fcitx5-m17n。
* 内置基于键盘布局的引擎。这允许使用传统的键盘布局。

Translations:Input method engines/4/zh-cn

2025-07-04T02:32:23Z

Weng Xuetian:

=中文=
* [https://pkgs.org/search/?q=fcitx5-chinese-addons fcitx5-chinese-addons]。它包括简体中文最常用的输入法，包括拼音和码表（五笔等）引擎。
* [https://pkgs.org/search/?q=fcitx5-table-extra fcitx5-table-extra]。附加中文表
* [https://pkgs.org/search/?q=fcitx5-chewing fcitx5-chewing]。基于libchewing的咀嚼引擎。
* [https://pkgs.org/search/?q=fcitx5-zhuyin fcitx5-zhuyin]。基于lib注音的注音输入法引擎。
* [https://pkgs.org/search/?q=fcitx5-rime fcitx5-rime]。一种可自定义的输入法，但默认情况下其默认配置为拼音。
= 日语 =
* [https://pkgs.org/search/?q=fcitx5-anthy fcitx5-anthy]
* [https://pkgs.org/search/?q=fcitx5-kkc fcitx5-kkc]
* [https://pkgs.org/search/?q=fcitx5-mozc fcitx5-mozc]
* [https://pkgs.org/search/?q=fcitx5-skk fcitx5-skk]
=韩文=
* [https://pkgs.org/search/?q=fcitx5-hangul fcitx5-hangul]
= 越南语 =
* [https://pkgs.org/search/?q=fcitx5-unikey fcitx5-unikey]
=泰语=
* [https://pkgs.org/search/?q=fcitx5-libthai fcitx5-libthai]
= 僧伽罗语 =
* [https://pkgs.org/search/?q=fcitx5-sayura fcitx5-sayura]
= 多语言（如果上面没有列出，这可能是您需要的）=
* [https://pkgs.org/search/?q=fcitx5-m17n fcitx5-m17n]
* [https://pkgs.org/search/?q=fcitx5-keyman fcitx5-keyman]
* [https://pkgs.org/search/?q=fcitx5-table-other fcitx5-table-other]，它提供了许多其他表格，但如果适合您，建议您更喜欢 fcitx5-m17n。
* 内置基于键盘布局的引擎。这允许使用传统的键盘布局。

Using Fcitx 5 on Wayland

2025-06-11T05:48:54Z

Weng Xuetian:

<languages />
<translate>

[https://wayland.freedesktop.org/ Wayland] is the next generation of display server protocol. While the initial release of the protocol is in 2008, the support of input method is not really ideal.


Also, using input method on Wayland-based compositor may require different setup to make it work, and certain features of fcitx that works under X11 are not yet supported by Wayland.


This page will try to cover all the current information with some underlying details, and [[Special:MyLanguage/Setup Fcitx 5|Setup Fcitx 5]] is still generally useful.

== Applications == 
=== TL;DR Do we still need XMODIFIERS, GTK_IM_MODULE and QT_IM_MODULE? ===

==== XMODIFIERS ==== 
For XMODIFIERS, yes, we do. X11 application running under X11 and XWayland has nearly no difference.

==== GTK_IM_MODULE ==== 
In an ideal setup, you should use fcitx im module Gtk application running under X11, and Gtk's text-input-v3 for wayland. The way of doing this is:


1. Do NOT set GTK_IM_MODULE environment variable.


2. For Gtk2, Add following content to ~/.gtkrc-2.0


<nowiki>gtk-im-module="fcitx"</nowiki>
3. For Gtk 3, add following content to ~/.config/gtk-3.0/settings.ini


<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>


4. For Gtk 4, add following content to ~/.config/gtk-4.0/settings.ini


<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>


5. If you are using GNOME 3+, also run following command.


<nowiki>gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/IMModule':<'fcitx'>}"</nowiki>


For GTK_IM_MODULE, as for now, the modern Gtk 3/4 application should be able to use text-input-v3 which is supported almost by every compositor, except weston. There are a few different options in terms of setting the value of GTK_IM_MODULE. When it is unset, the Gtk built-in Wayland im module will be used for Gtk3 and Gtk4. While you can also enforce it by doing GTK_IM_MODULE=wayland, remember it will be also picked up by Gtk2. Setting GTK_IM_MODULE=fcitx can still work, and it is necessary if your compositor does not support Wayland input method frontend.


It is possible to force a certain im module with Gtk configuration file, so without GTK_IM_MODULE set, it will still be able to use different im module.


Per Gtk implementation (still valid for 3.24.41), the order of preferences is:


* X11
** GTK_IM_MODULE in the environment
** Value of Gtk/IMModule from XSettings
** Value from configuration file
** A locale based automatic selection
* Wayland
** GTK_IM_MODULE in the environment
** "wayland"

==== QT_IM_MODULE ==== 
For QT_IM_MODULE, as for now QT can only use its own text-input-v{2,4}, which is only supported by KWin. Which means, under KDE you should unset it, but under other desktop, you will need to set it to QT_IM_MODULE=fcitx. Also the proprietary Qt applications in the wild complicates the situation. Some do not work on Wayland, some do not bundle/provide Qt wayland. Most of them do not bundle fcitx im module because fcitx is only a third party application to Qt, but I also noticed some do bundle but not bundle all the required libraries. While fcitx 5 support ibus protocol, some of those applications do not even bundle ibus im module. There are a few different environment variables you can try for those proprietary Qt applications (WPS, Anki, DaVinci Resolve, Mathematica, etc...).


<nowiki>QT_IM_MODULE=fcitx # For those who bundle qt im module, e.g. WPS, Anki, you should find a .so file with fcitx in the file name
QT_IM_MODULE=ibus # For those who bundle ibus im module shipped with Qt, you should find libibusplatforminputcontextplugin.so in the package.
QT_QPA_PLATFORM=xcb QT_IM_MODULE=ibus # Enforce it to run on X11/XWayland and use ibus im module
</nowiki>


In Qt 6.7, there is a new environment variable called "QT_IM_MODULES", which allows you so specify a fallback order on im modules. You can set it to


<nowiki>QT_IM_MODULES="wayland;fcitx;ibus"</nowiki>


So it will be able pick up the most usable one even for application that bundles no fcitx/wayland. Remember, you may still need to set( or unset) QT_IM_MODULE (not "QT_IM_MODULES") in order to handle Qt 4/5 applications.

=== Legacy X11 application that runs under XWayland === 
In a word, XWayland support for input method is as good as normal X11 display server. As long as you set the same environment variable, using Xwayland should not be a issue. This category includes:


* Xlib-based (and also other toolkit based on Xlib, e.g. tk, SDL1, etc), e.g. xterm, rxvt. Make sure XMODIFIERS is set correctly.
* Gtk2-based applications, similar to Xlib, but can use fcitx im module. Set GTK_IM_MODULE to fcitx will give it best experience.
* SDL2-based applications that doesn't default to wayland. Set SDL_IM_MODULE to fcitx
* electron, chromium, these are still default to X11, similar to Gtk2 case.
* For Qt4 applcation, Qt 4 can only use X11. You will need to QT_IM_MODULE to fcitx. Same for Qt5+ that uses XCB (can be override with QT_QPA_PLATFORM=xcb).

=== Gtk3 / Gtk4 === 
Gtk3 and Gtk4 support text-input-v3 natively. At the same time, it's also possible to use fcitx im module under wayland. So, either GTK_IM_MODULE=wayland or GTK_IM_MODULE=fcitx works. There are some difference to it. text-input-v3

=== Qt5 / Qt6 === 
If your Qt application natively runs under Wayland, you can either unset QT_IM_MODULE to make it use text-input-v2, or set QT_IM_MODULE=fcitx to make it use fcitx im module.


text-input-v2 is not upstreamed to wayland-protocols, that is probably why only kwin support it. This means in non-kwin environment, you will need to use QT_IM_MODULE=fcitx to make the Qt applications work.


On Qt6, you may also use QT_IM_MODULE= (empty) or QT_IM_MODULE=wayland if your Qt vesion contains this https://codereview.qt-project.org/c/qt/qtwayland/+/416862.

=== Native wayland application (winit) === 
Most likely text-input-v3 is being used.

=== Chromium / Electron === 
{{warning|The information in this section may not be up to date to reflect upstream change, especially the default behavior when no option is changed.}}
TL;DR version, if you use XWayland to run Chromium or Electron application, just install Gtk im module and GTK_IM_MODULE=fcitx the same way like X11.


If you choose to run it natively under Wayland, for chromium you will need to use


# If your compositor supports text-input-v1 protocol. Check the compositor section below.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime


# If your compositor & chromium supports text-input-v3 protocol, you may also use
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=3


# However, due to a different understanding in text-input-v3 protocol, it has some issue when using with KWin.
# Prefer text-input-v1 if you're using kwin.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=1


Or


# You will get wrong position for the input method popup window, unless you use GNOME shell + kimpanel extension.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4


For electron, only the first option is avaiable (electron does NOT support to run internal chromium with gtk4), e.g. for vscode


# If your compositor supports text-input-v1 protocol. Check the compositor section below.
code --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime


By default it should run under Xwayland (As of 2023/02/25 on Archlinux/Chromium 110.0.5481.177), but some user also reports it is using wayland even the "Preferred Ozone Platform" is "Default". So to check whether it's really run with wayland, you can use xeyes or xwininfo. With xeyes, if it's an X11 window, the "eyes" will move with mouse, otherwise it's wayland. With xwininfo, if the mouse cursor changed to "+" shape, and click the window shows the window information, then it is a X11 window.


You may force it to run with Wayland, or X11 with the flag <code>--ozone-platform=wayland</code> and <code>--ozone-platform=x11</code>. You may persistent this by changing the option "Preferred Ozone Platform" in chrome://flags. It has four values, "Default", "X11", "Wayland", "Auto".


It's possible to make it use GTK_IM_MODULE if it runs with Gtk4 (only supported by chromium/chrome at this time, not electron) by passing <code>--gtk-version=4</code>.


It's also possible to make it use text-input-v1 by passing <code>--enable-wayland-ime</code> in addition to the flag above.


The Chromium support for text-input-v1 is not very stable and you may hit some random crash. E.g. in the past, version 112 has a crash bug: https://bugs.chromium.org/p/chromium/issues/detail?id=1431532 , which is fixed in version 115. In the bug comment, Chromium developer claims this text-input-v1 is only supposed to be used internally and not well supported, so use this at your own risk though it's currently the only out of box option.


You should only use one of <code>--enable-wayland-ime</code> or <code>--gtk-version=4</code>, depending on you want to use text-input-v1, or gtk4 im module. text-input-v1 works for kwin 5.27 and weston. Gtk4 im module works on all environment, but only GNOME with Kimpanel extension can display the popup window in the correct position.

== Support in Wayland Compositor == 


Even if you are using only native wayland applications, Xwayland is recommended to be enabled for following reason. If client side input panel in im module does not work, fcitx will fallback to a X11 window, instead of a wayland window. The reason for this is because wayland window can not be placed freely on the screen. On the contrary, even if im module can only pass a coordinate relative to the application window to fcitx, which make the coordinate position doesn't make much sense, if your application window size is "maximized", the coordinate may just be "right" if treated as the global coordinate. This makes X11 window a better option than a randomly placed wayland window.

=== KDE Plasma === 
Best setup:
* KDE Plasma 5.27 or later
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Start fcitx5 by go to "System settings" -> "Virtual keyboard" -> Select Fcitx 5
** Do not set <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> & <code>SDL_IM_MODULE</code> . You could unset <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> by runing <code>im-config</code> and then selecting <code>do not set any IM from im-config and use desktop default"</code>
** Run chromium/electron application with <code>--enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime</code>
* Caveats:
** Certain Gtk/Qt application that only works under X11 may still need to set <code>GTK_IM_MODULE</code> or <code>QT_IM_MODULE</code> for them individually.
** If you set <code>GTK_IM_MODULE/QT_IM_MODULE</code> globally, you will hit this issue [[Special:MyLanguage/FAQ#Candidate_window_is_blinking_under_wayland_with_Fcitx_5|Candidate window is blinking under wayland with Fcitx 5]]


Support Information:
* App/Compositor supports text-input-v2 and text-input-v3.
* Comopositor/Application uses zwp_input_method_v1.
* 5.27 additionally supports text-input-v1.
* 5.24 usable zwp_input_method_v1 with fcitx5. Pre-5.24 there are lots of problems, always use fcitx im module instead.
* Use "Virtual keyboard" KCM to launch fcitx5. This is required to use text-input protocol. If you launch fcitx this way, make sure you do not use "restart" in the tray menu, since the socket passed from KWin can not be reused with the newly restarted fcitx.

=== GNOME === 
Best setup:
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Set <code>QT_IM_MODULE=fcitx</code> for Qt, since Qt5 would use XWayland by default.
** Run chrome with XWayland and <code>GTK_IM_MODULE=fcitx</code>


Support information:
* Application/Compositor uses text-input-v3
* Compositor/Input Method uses ibus dbus protocol, so ibus frontend is required to be used.
* Adding Fcitx 5 to autostart, it will replace any existing ibus-daemon upon start up so it will work out of box.
* Popup candidate window is not able to be displayed over gnome-shell UI. Only solution is to use [[Special:MyLanguage/Kimpanel|Kimpanel]], [https://extensions.gnome.org/extension/261/kimpanel/ link to extension].
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Sway === 
* Application/Compositor uses text-input-v3
* Comopositor/Application uses zwp_input_method_v2, but it's partially implemented. You will need [https://github.com/swaywm/sway/pull/7226 this pull request] to make it show the popup candidate window for text-input-v3 client.
* fcitx im module also works.
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Weston === 
* Application/Compositor uses text-input-v1
* Comopositor/Application uses zwp_input_method_v1.
* Since it has no text-input-v3, which is more commonly used, im module is the only solution for Gtk/Qt, need to set GTK_IM_MODULE=fcitx and QT_IM_MODULE=fcitx.
* Add following content to ~/.config/weston.ini to make it launch fcitx 5. (xwayland part is recommended to make fcitx work best, even if it's wayland)


<pre>
[core]
xwayland=true


[input-method]
path=/usr/bin/fcitx5
</pre>

=== Other compositors === 
Please check their upstream for more information. For wlroots based compositors, it is possible that they also support in the same way as Sway does, or zwp_input_method could also be unsupported.

== Known Issues == 
=== Fcitx managed XKB layout ===
Unlike X11, there is no generic way to set XKB layout to compositor, which means it can only be implemented for every individual desktop. Right now, Fcitx managed layout only works for KDE Plasma and GNOME.


As for other desktop, in order to make this "semi" work you'll need to ensure following:


* The XKB layout of the input method group should be the same as the actual xkb layout you configured for the compositor. Fcitx will "think" the layout is the same and bypass the key conversion logic.
* If you need other layout for text typing (e.g. Arabic), just add them to the Fcitx. As long as the key is forwarded to fcitx, it should work.

=== Popup candidate window === 
Wayland does not have a global coordinate system for regular client, so for native wayland client, it is impossible for Fcitx to place a wayland surface at a certain position. In order for popup window to be placed at the correct position, there are following cases:
* Xwayland have no problem and it should work as good as X11.
* If zwp_input_method protocol can be used, it has a surface role to allow compositor to place the popup window for input method. This only works if client uses text-input protocol.
* For GNOME, kimpanel extension can read window coordinate since it's running inside compositor. As long as im module can report relative coordinate, kimpanel extension can display the popup window at the correct position. As similar approach for Plasma kimpanel is planned, but not yet implemented.
* For Gtk/Qt, fcitx's im module implement a way to render the popup with in the client process. This has some limitation because implemenation of xdg_popup in Gtk3/Qt5 doesn't support reposition the window. So show/hide trick is used to mitigate this, but it may cause window blinking. Fcitx tries not to move window if possible. You may also disable popup animation if you're using KWin to help reduce the blinking.

=== Per-window input method state === 
When zwp_input_method is used, essentially there is only one input context visible to fcitx, and fcitx cannot distinguish what application is being used. Which means the input method "active"/"inactivate" state is now "global".


Now fcitx supports two protocol to figure out the focused window and the corresponding application name, including wlr-foreign-toplevel-management (used by wlroots based compositor) and plasma-window-management (used by kwin).
</translate>

Develop an simple input method

2025-01-11T23:45:57Z

Weng Xuetian:

<languages />
<translate>

This is a step-by-step tutorial for writing a Fcitx 5 input method. The same instruction can be used for developing other types of addons. While Fcitx 5 now supports many non traditional Linux/Unix (Mac, iOS, Android) platforms, this tutorial assumes you are using Linux or FreeBSD for development and have basic knowledge about Command-line, C++ and CMake.

= Understanding the structure of a Fcitx shared library addon = 
Fcitx 5 provides a extensible framework for adding new addon types (Right now Lua is also supported, but only a small set of API is supported). Shared library can access all types of Fcitx API. Static library addon has not difference from API point of view, but you will need to put some more effort to link all addon into server properly.


<nowiki>
[fcitx install prefix]
|
|- share/fcitx5
| |
| |- addon/[addon name].conf
| |- inputmethod/[input method name 1].conf
| | ...
| |- inputmethod/[input method name n].conf
|
|- lib/fcitx5
|
|- [library name].so
</nowiki>


Above is the file structure for an input method addon. For other types of addons, files under <code>inputmethod/</code> is not needed. The file name of <code>[addon name].conf</code> matters and will be used to uniquely reference this specific addon. Fcitx also follows [https://specifications.freedesktop.org/basedir-spec/latest/ XDG directory standard], so the files under XDG_DATA_DIR/fcitx5 will also be checked. Similarly, file name of configuration file under <code>inputmethod/</code> also matters and will be the unique name of a certain input method.


Example of <code>[addon name].conf</code>


<nowiki>[Addon]
Name[ca]=Pinyin
Name[da]=Pinyin
Name[de]=Pinyin
Name[he]=פיניין:
Name[ko]=병음
Name[ru]=Пиньинь
Name[zh_CN]=拼音
Name=Pinyin
Category=InputMethod
Version=5.0.8
Library=pinyin
Type=SharedLibrary
OnDemand=True
Configurable=True


[Addon/Dependencies]
0=punctuation


[Addon/OptionalDependencies]
0=fullwidth
1=quickphrase
2=cloudpinyin
3=notifications
4=spell
5=pinyinhelper
6=chttrans
7=imeapi
</nowiki>


Example of <code>[input method name].conf</code>


<nowiki>[InputMethod]
Name[ca]=Pinyin
Name[da]=Pinyin
Name[de]=Pinyin
Name[he]=פיניין:
Name[ko]=병음
Name[ru]=Пиньинь
Name[zh_CN]=拼音
Name=Pinyin
Icon=fcitx-pinyin
Label=拼
LangCode=zh_CN
Addon=pinyin
Configurable=True
</nowiki>


The file is in a [[wikipedia:INI_file|ini-like]] format, with certain fcitx specific extensions and rules. It also supports XDG Desktop file style I18N for translation.

= Use CMake build system = 
It is your own freedom to pick whatever build system you would d like to use, as long as you produce the correct files. Fcitx 5 provides lots of support with CMake, so using CMake would be the most convenient way to build a Fcitx project. In this document, we will only cover using CMake as build system.

= A quick start: Quwei = 
[[wikipedia:区位码_(国标)|Quwei]] input method is an input method that basically allow you type the digit of GB2312 and produce the Chinese Character that matches this code. It used to be supported by Fcitx 4, but not included by Fcitx 5 anymore. Though it is hard to use, it can serve as a good example on how to implement a simple input method for Fcitx 5.

== Project skeleton == 
So let we start with a skeleton of this project.


<nowiki>├── CMakeLists.txt
├── LICENSES
│   └── BSD-3-Clause.txt # License for this project
├── po # Optional I18n
│   ├── CMakeLists.txt
│   ├── fcitx5-quwei.pot
│   ├── LINGUAS
│   └── zh_CN.po
└── src
├── CMakeLists.txt
├── quwei-addon.conf.in.in # Addon registration file
├── quwei.conf.in # Input method registration file
├── quwei.cpp # Engine implementation
└── quwei.h # Engine implementation
</nowiki>


This tutorial ass


The CMakeLists.txt in the root directory lookup for the dependency.


<nowiki>
cmake_minimum_required(VERSION 3.21)
project(fcitx5-quwei)


find_package(Fcitx5Core REQUIRED)
# Setup some compiler option that is generally useful and compatible with Fcitx 5 (C++17)
include("${FCITX_INSTALL_CMAKECONFIG_DIR}/Fcitx5Utils/Fcitx5CompilerSettings.cmake")


add_subdirectory(src)</nowiki>


The src/CMakeLists.txt would looks like


<nowiki># Make sure it produce quwei.so instead of libquwei.so
add_library(quwei SHARED quwei.cpp)
target_link_libraries(quwei PRIVATE Fcitx5::Core)
set_target_properties(quwei PROPERTIES PREFIX "")
install(TARGETS quwei DESTINATION "${FCITX_INSTALL_LIBDIR}/fcitx5")


# Addon config file
# We need additional layer of conversion because we want PROJECT_VERSION in it.
configure_file(quwei-addon.conf.in quwei-addon.conf)
install(FILES "${CMAKE_CURRENT_BINARY_DIR}/quwei-addon.conf" RENAME quwei.conf DESTINATION "${FCITX_INSTALL_PKGDATADIR}/addon")


# Input Method registration file
install(FILES "quwei.conf" DESTINATION "${FCITX_INSTALL_PKGDATADIR}/inputmethod")</nowiki>


quwei.conf.in would look like


<nowiki>[InputMethod]
# Translatable name of the input method
Name=Quwei
# Icon name
Icon=fcitx-quwei
# A short label that present the name of input method
Label=区
# ISO 639 language code
LangCode=zh_CN
# Match addon name
Addon=quwei
# Whether this input method support customization
# Configurable=True</nowiki>


This file will be loaded as an [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputMethodEntry.html InputMethodEntry] object.


quwei-addon.conf.in looks like


<nowiki>[Addon]
Name=Quwei
Category=InputMethod
Version=@PROJECT_VERSION@
Library=quwei
Type=SharedLibrary
OnDemand=True
Configurable=True


[Addon/Dependencies]
0=punctuation


[Addon/OptionalDependencies]
0=fullwidth
1=quickphrase
2=chttrans</nowiki>


This file will be loaded as an [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1AddonInfo.html AddonInfo] object.

== Basic implementation of InputMethodEngine == 
You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/02c32b07e47e0e75db4f248dbb33c31137d8df74 first commit] in the github.


Version 1 of quwei.h
<nowiki>/*
* SPDX-FileCopyrightText: 2021~2021 CSSlayer <wengxt@gmail.com>
*
* SPDX-License-Identifier: BSD-3-Clause
*
*/
#ifndef _FCITX5_QUWEI_QUWEI_H_
#define _FCITX5_QUWEI_QUWEI_H_


#include <fcitx/inputmethodengine.h>
#include <fcitx/addonfactory.h>


class QuweiEngine : public fcitx::InputMethodEngineV2 {
void keyEvent(const fcitx::InputMethodEntry & entry, fcitx::KeyEvent & keyEvent) override;
};


class QuweiEngineFactory : public fcitx::AddonFactory {
fcitx::AddonInstance * create(fcitx::AddonManager * manager) override {
FCITX_UNUSED(manager);
return new QuweiEngine;
}
};


#endif // _FCITX5_QUWEI_QUWEI_H_</nowiki>


Version 1 of quwei.cpp


<nowiki>/*
* SPDX-FileCopyrightText: 2021~2021 CSSlayer <wengxt@gmail.com>
*
* SPDX-License-Identifier: BSD-3-Clause
*
*/
#include "quwei.h"


void QuweiEngine::keyEvent(const fcitx::InputMethodEntry& entry, fcitx::KeyEvent& keyEvent)
{
FCITX_UNUSED(entry);
FCITX_INFO() << keyEvent.key() << " isRelease=" << keyEvent.isRelease();
}


FCITX_ADDON_FACTORY(QuweiEngineFactory);</nowiki>


When implement a Fcitx addon, it should be a sub-class of [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1AddonInstance.html AddonInstance]. The instantiation of AddonInstance is done via a [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1AddonFactory.html AddonFactory]. [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputMethodEngineV2.html InputMethodEngineV2] is a sub-class of AddonInstance. This class needs to be used when implementing an input method addon.


The minimum implantation of an input method engine only need to contain the implementation of the keyEvent function.


Here, we use a iostream like macro <code>FCITX_INFO()</code> to write every key we pressed to the log.


Assume the prefix your fcitx installation is /usr. The command to build this project would be:


<nowiki>
mkdir -p build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug # use Debug for easy debugging with gdb
make # or ninja, depending on your system
sudo make install # or sudo ninja install</nowiki>


If everything works fine, the install command should print out something like:


<nowiki>-- Install configuration: "Debug"
-- Installing: /usr/lib/fcitx5/quwei.so
-- Installing: /usr/share/fcitx5/addon/quwei.conf
-- Installing: /usr/share/fcitx5/inputmethod/quwei.conf</nowiki>


Now you can restart fcitx5 with <code>fcitx5 -rd</code> and add Quwei to the your configuration with [[Special:myLanguage/Configtool (Fcitx 5)|Configtool (Fcitx 5)]].


After switching to Quwei, the key press in application will make Fcitx 5 print out something like:


<nowiki>I2021-11-16 12:29:32.352702 quwei.cpp:12] Key(f states=0) isRelease=1
I2021-11-16 12:29:32.389935 quwei.cpp:12] Key(s states=0) isRelease=0
I2021-11-16 12:29:32.413689 quwei.cpp:12] Key(d states=0) isRelease=0
I2021-11-16 12:29:32.497661 quwei.cpp:12] Key(s states=0) isRelease=1
I2021-11-16 12:29:32.498021 quwei.cpp:12] Key(f states=0) isRelease=0
I2021-11-16 12:29:32.523816 quwei.cpp:12] Key(a states=0) isRelease=1
I2021-11-16 12:29:32.524051 quwei.cpp:12] Key(d states=0) isRelease=1
I2021-11-16 12:29:32.704919 quwei.cpp:12] Key(f states=0) isRelease=1
I2021-11-16 12:29:32.705006 quwei.cpp:12] Key(d states=0) isRelease=0
I2021-11-16 12:29:32.833024 quwei.cpp:12] Key(d states=0) isRelease=1
I2021-11-16 12:29:34.633936 quwei.cpp:12] Key(Control_L states=0) isRelease=0
I2021-11-16 12:29:35.053817 quwei.cpp:12] Key(Control+C states=4) isRelease=0
I2021-11-16 12:29:35.165617 quwei.cpp:12] Key(Control+C states=4) isRelease=1
I2021-11-16 12:29:35.348654 quwei.cpp:12] Key(Control+Control_L states=4) isRelease=1</nowiki>


So you know your input method engine is now working.

= Implement Input Method logic = 
Quwei is basically typing 4 digit number of Quwei code. Quwei code can be treated as Qu code xx and Wei code yy. The mapping from Quwei to GB2312 is (0xA0 + Qu, 0xA0 + Wei). When user type 3 digits of Quwei, input method will display a candidate list of 10 possible character with given quwei prefix.


You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/b9b047abb46fa0f9c42a0be82941b65b35b277eb second commit] in the github.

== Store the state for different input contexts == 
Fcitx allows different input context to held a different state. The state usually refers to the partially typed text and all other associated data structures. In Quwei case, the state is the digits that user already typed. To represent this, Fcitx provides a convenient class [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputBuffer.html InputBuffer] to allow engine to use this class conveniently to edit the internal state. In order to automatically construct the state when an input context getting constructed, Fcitx provides a framework called InputContextProperty. In order to use this, you first need to register a factory class to [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputContextManager.html InputContextManager], via registerProperty. Each property need to have a global unique name. The name can be something human-understandable. In Quwei case, I just use "quweiState". The benefit of using a nicer name is just in case you're developing something cross addon (Another addon need to access certain internal state of this addon), you can use this common name to load it in a different addon. If you do not need access from outside, the name does not really matter.


The factory class comes with a handy C++ template, [https://codedocs.xyz/fcitx/fcitx5/group__FcitxCore.html#ga9e60042d1f671a6fa31ea04bb4961ec9 FactoryFor]. This is actually an type alias to [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1LambdaInputContextPropertyFactory.html LambdaInputContextPropertyFactory]. This class simply accepts a lambda function as the factory implementation. This can save you sometime from creating your own subclass of [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputContextPropertyFactory.html InputContextPropertyFactory].


In order to get the state object from input context, you can simply use the factory object like this:


<nowiki>
auto *state = ic->propertyFor(&factory_);</nowiki>


In certain cases, it is also possible to un-register the factory and re-register it again in order to "refresh" all the internal state.

== Candidate List == 
In Fcitx 5, a candidate list is a part of the InputPanel class, stored as shared_ptr to avoid life time issue when selecting candidate triggers the User interface update. There's different capability provided by candidate list via certain interfaces. The helper class [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1CommonCandidateList.html CommonCandidateList] would provide most common functionality for a candidate list. It implements BulkCandidateList interface, and that is why it is not suitable for Quwei case. Because we want to have a semi-infinite candidate list for Quwei.


In Quwei, QuweiCandidateList gonna implement a PageableCandidate interface, which allows a prev/next page button to be displayed in the input method panel.

== Preedit == 
Preedit can refer to two different user interface element, one is the preedit embedded within the application, usually referred as "client preedit" in Fcitx. Another one is displayed with in the input method panel window. Usually, input method engine would only use one of them because there is only 1 form of preedit that need to be displayed. Whether the input context supports it or not can be checked via the capabilityFlags property.


Also there's something you may want to consider when using client preedit. Due to the different implementation in toolkit, toolkit may choose to commit the client preedit right away when application loses focus. For certain input methods, it might be designed to work in a way that typing does not need extra confirmation, for example, the word completion mode in keyboard engine. In such case, even though the preedit is used, user would expect the text it to be committed even if it is still in a preedit mode. In that sense, the preedit text should be exact same of the text that will be committed after confirmation.


In some version of iOS, its Pinyin input method using its client preedit in a way that may causes confusion: user types "nihao", and client preedit is displayed as segmented pinyin "ni hao". When text box loses focus, "ni hao" (extra space) would be committed into the application, and such outcome would never happen in regular usage of Pinyin.


Another thing to consider is where to put the cursor. While it might be natural to display the cursor at the its actual place within preedit, the input panel window will also be displayed at the client preedit cursor position. That means along with user regular typing, when cursor moves, the candidate window would also moves. In some cases, this is not desirable because it causes candidate window to be moved frequently when user types. An alternative way to handle this is to set the client cursor always to be 0. If you need to support display the position of actual cursor, you may use highlight style instead. For example, when you have "ABCD" in preedit and the cursor is between B and C. You may set client cursor to 0, and make "AB" displayed with highlight style to indicate the position of cursor.

== Key event handling == 
The most common use case is to call filterAndAccept() for all the key event that you intends to handle. Also, for most input method, key release is not relevant and should be pass-through to application. To make input method engine to work with any user input, be sure to consider all the possible key event that may be typed by user. For example, a common error is forgetting to block certain irrelevant key in composing mode and leaking the key into the application. Also, be careful for key event with modifier, you may want to pass through such key to make application specific hotkey still accessible even when user is composing.


Also, a key event has 3 different form of the Key objects. Normally a input method engine may only want to consider only the key() property. origKey() and rawKey() properties are less used. Key property is in a normalized form of key event. That removes "Shift" modifier for certain cases, which makes it easier to handle by the input method engine. For example, upper case A produced by Shift+A and Capslocked A will be the same after normalization. You may refer to the implementation to learn about how this normalization works.

= Reuse features from other addons = 
You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/b01bf8c4344b50b496593b4d9cf8be49cd1ce9c2 third commit] in the github.


Fcitx provides a mechanism to invoking functions from other addons without having the need of directly linking to them. And also some easy to use CMake macro to look up the addon dependencies.


<nowiki>find_package(Fcitx5Module REQUIRED COMPONENTS Punctuation QuickPhrase)</nowiki>


We add the find_package line above to look up dependencies for Punctuation and QuickPhrase module.


If you want to implement such a module, you can use the following CMake macro


<nowiki>fcitx5_export_module(QuickPhrase TARGET quickphrase BUILD_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_SOURCE_DIR}" HEADERS quickphrase_public.h INSTALL)</nowiki>


And it will automatically generate the required CMake config for your addon.


When using other addons in the code, there is a handy macro <code>FCITX_ADDON_DEPENDENCY_LOADER</code> that will handle the addon loading at the runtime. When it is called for the first time, the dependent addon will be loaded automatically. Here we defines four different dependency in the code:


<nowiki> FCITX_ADDON_DEPENDENCY_LOADER(quickphrase, instance_->addonManager());
FCITX_ADDON_DEPENDENCY_LOADER(punctuation, instance_->addonManager());


private:
FCITX_ADDON_DEPENDENCY_LOADER(chttrans, instance_->addonManager());
FCITX_ADDON_DEPENDENCY_LOADER(fullwidth, instance_->addonManager());</nowiki>


The first parameter should be same as the addon name, second parameter is the expression to get the AddonManager object.


This mechanism make it easy to reuse the functionality implemented by other addons and shared the code. For example, classicui queries the X11/wayland connection from xcb addon and wayland addon.

= Configuration = 
While Quwei does not really need this feature, since it is a really common use case so it will be covered in this section. The addon has a few different interface relevant to configuration, such as getConfig, setConfig, getConfigForInputMethod, setConfigForInputMethod, reloadConfig. The getter function would need to return a [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1Configuration.html Configuration] object, while setConfig accepts a [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1RawConfig.html RawConfig] object. reloadConfig will be called to reload the configuration from disk, you may want to call reloadConfig() in the constructor of the addon too.


If Configurable field is set to True in the addon registration file, such method would be called to retrieve the information and Configtool would generate UI for it.


<nowiki>FCITX_CONFIGURATION(
ClipboardConfig, KeyListOption triggerKey{this,
"TriggerKey",
_("Trigger Key"),
{Key("Control+semicolon")},
KeyListConstrain()};
KeyListOption pastePrimaryKey{
this, "PastePrimaryKey", _("Paste Primary"), {}, KeyListConstrain()};
Option<int, IntConstrain> numOfEntries{this, "Number of entries",
_("Number of entries"), 5,
IntConstrain(3, 30)};);</nowiki>


Usually, you will define a sub class of Configuration with the FCITX_CONFIGURATION macro. First argument is the name of the class, and then you just simply add [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1Option.html Option] as member. Following is a common implemenation of setConfig/getConfig/reloadConfig.


<nowiki> static constexpr char configFile[] = "conf/clipboard.conf";
void reloadConfig() override { readAsIni(config_, configFile); }


const Configuration *getConfig() const override { return &config_; }
void setConfig(const RawConfig &config) override {
config_.load(config, true);
safeSaveAsIni(config_, configFile);
}</nowiki>


readAsIni and safeSaveAsIni are helper functions to read/save Configuration object from/to the Fcitx ini-format. The file is saved under $XDG_CONFIG_HOME.

</translate>

Develop an simple input method/zh-cn

2025-01-11T23:30:41Z

Weng Xuetian:

<languages />
这是编写 Fcitx 5 输入法的分步说明。同样的步骤也可以用于开发其他类型的插件，只是输入法引擎是最复杂的。

= 了解 Fcitx 共享库插件的文件结构 =
Fcitx 5 提供了一个用于添加新插件类型的可扩展框架，但共享库支持是内置的，并且是所有其他插件类型的基础。所以我们只会在本文档中介绍共享库插件。

<div class="mw-translate-fuzzy">
<nowiki>
[fcitx install prefix]
|
|- share/fcitx5
| |
| |- addons/[addon name].conf
| |- inputmethod/[input method name 1].conf
| | ...
| |- inputmethod/[input method name n].conf
|
|- lib/fcitx5
|
|- [library name].so
</nowiki>
</div>

以上是输入法插件的文件结构。对于其他类型的插件，不需要 <code>inputmethod/</code> 下的文件。<code>[addon name].conf</code> 的文件名很重要，将用于唯一引用此特定插件。Fcitx 也遵循 XDG 目录标准，所以 XDG_DATA_DIR/fcitx5 下的文件也会被检查。同样，<code>inputmethod/</code>下的配置文件的文件名也很重要，将是某个输入法的唯一名称。

<code>[addon name].conf</code> 示例

<nowiki>[Addon]
Name[ca]=Pinyin
Name[da]=Pinyin
Name[de]=Pinyin
Name[he]=פיניין:
Name[ko]=병음
Name[ru]=Пиньинь
Name[zh_CN]=拼音
Name=Pinyin
Category=InputMethod
Version=5.0.8
Library=pinyin
Type=SharedLibrary
OnDemand=True
Configurable=True

[Addon/Dependencies]
0=punctuation

[Addon/OptionalDependencies]
0=fullwidth
1=quickphrase
2=cloudpinyin
3=notifications
4=spell
5=pinyinhelper
6=chttrans
7=imeapi
</nowiki>

<code>[输入法名称].conf</code>示例

<nowiki>[InputMethod]
Name[ca]=Pinyin
Name[da]=Pinyin
Name[de]=Pinyin
Name[he]=פיניין:
Name[ko]=병음
Name[ru]=Пиньинь
Name[zh_CN]=拼音
Name=Pinyin
Icon=fcitx-pinyin
Label=拼
LangCode=zh_CN
Addon=pinyin
Configurable=True
</nowiki>

该文件采用类似 ini 的格式，具有某些 fcitx 特定的扩展名和规则。它还支持 XDG 桌面文件样式 i18n 进行翻译。

= 使用 CMake 构建系统 =
理论上只要能生成正确的文件，就可以自由选择要使用的构建系统。但是Fcitx 5 对 CMake 提供了大量支持，因此使用 CMake 将是构建 Fcitx 项目的最便捷方式。在本文档中，我们将仅介绍使用 CMake 作为构建系统。

= 快速入门：区位码 =
[[wikipedia:区位码_(国标)|区位码]] 输入法是一种输入法，允许您简单的输入GB2312的数字并产生与该代码匹配的汉字。它曾经被 Fcitx 4 支持，但不再被 Fcitx 5 包含。虽然它很难使用，但它可以作为一个很好的例子来说明如何为 Fcitx 5 实现一个简单的输入法。

== 项目框架 ==
因此，让我们从这个项目的框架开始。

<nowiki>├── CMakeLists.txt
├── LICENSES
│ └── BSD-3-Clause.txt # License for this project
├── po # Optional I18n
│ ├── CMakeLists.txt
│ ├── fcitx5-quwei.pot
│ ├── LINGUAS
│ └── zh_CN.po
└── src
├── CMakeLists.txt
├── quwei-addon.conf.in.in # Addon registration file
├── quwei.conf.in # Input method registration file
├── quwei.cpp # Engine implementation
└── quwei.h # Engine implementation
</nowiki>

您也许需要查看一些 CMake 教程以了解一些基本的 CMake 用法。

CMakeLists.txt 在根目录查找依赖项。

<nowiki>
cmake_minimum_required(VERSION 3.21)
project(fcitx5-quwei)

find_package(Fcitx5Core REQUIRED)
# Setup some compiler option that is generally useful and compatible with Fcitx 5 (C++17)
include("${FCITX_INSTALL_CMAKECONFIG_DIR}/Fcitx5Utils/Fcitx5CompilerSettings.cmake")

add_subdirectory(src)</nowiki>

src/CMakeLists.txt 示例如下：

<nowiki># Make sure it produce quwei.so instead of libquwei.so
add_library(quwei SHARED quwei.cpp)
target_link_libraries(quwei PRIVATE Fcitx5::Core)
set_target_properties(quwei PROPERTIES PREFIX "")
install(TARGETS quwei DESTINATION "${FCITX_INSTALL_LIBDIR}/fcitx5")

# Addon config file
# We need additional layer of conversion because we want PROJECT_VERSION in it.
configure_file(quwei-addon.conf.in quwei-addon.conf)
install(FILES "${CMAKE_CURRENT_BINARY_DIR}/quwei-addon.conf" RENAME quwei.conf DESTINATION "${FCITX_INSTALL_PKGDATADIR}/addon")

# Input Method registration file
install(FILES "quwei.conf" DESTINATION "${FCITX_INSTALL_PKGDATADIR}/inputmethod")</nowiki>

quwei.conf.in 示例：

<nowiki>[InputMethod]
# Translatable name of the input method
Name=Quwei
# Icon name
Icon=fcitx-quwei
# A short label that present the name of input method
Label=区
# ISO 639 language code
LangCode=zh_CN
# Match addon name
Addon=quwei
# Whether this input method support customization
# Configurable=True</nowiki>

此文件将作为 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputMethodEntry.html InputMethodEntry] 对象进行加载。

quwei-addon.conf.in 示例：

<nowiki>[Addon]
Name=Quwei
Category=InputMethod
Version=@PROJECT_VERSION@
Library=quwei
Type=SharedLibrary
OnDemand=True
Configurable=True

[Addon/Dependencies]
0=punctuation

[Addon/OptionalDependencies]
0=fullwidth
1=quickphrase
2=chttrans</nowiki>

此文件将作为 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1AddonInfo.html AddonInfo] 对象加载。

== InputMethodEngine 的基本实现 ==
您可以参考github中[https://github.com/fcitx/fcitx5-quwei/commit/02c32b07e47e0e75db4f248dbb33c31137d8df74 第一笔提交]的代码。

版本 1 的 quwei.h
<nowiki>/*
* SPDX-FileCopyrightText: 2021~2021 CSSlayer <wengxt@gmail.com>
*
* SPDX-License-Identifier: BSD-3-Clause
*
*/
#ifndef _FCITX5_QUWEI_QUWEI_H_
#define _FCITX5_QUWEI_QUWEI_H_

#include <fcitx/inputmethodengine.h>
#include <fcitx/addonfactory.h>

class QuweiEngine : public fcitx::InputMethodEngineV2 {
void keyEvent(const fcitx::InputMethodEntry & entry, fcitx::KeyEvent & keyEvent) override;
};

class QuweiEngineFactory : public fcitx::AddonFactory {
fcitx::AddonInstance * create(fcitx::AddonManager * manager) override {
FCITX_UNUSED(manager);
return new QuweiEngine;
}
};

#endif // _FCITX5_QUWEI_QUWEI_H_</nowiki>

版本 1 的 quwei.cpp

<nowiki>/*
* SPDX-FileCopyrightText: 2021~2021 CSSlayer <wengxt@gmail.com>
*
* SPDX-License-Identifier: BSD-3-Clause
*
*/
#include "quwei.h"

void QuweiEngine::keyEvent(const fcitx::InputMethodEntry& entry, fcitx::KeyEvent& keyEvent)
{
FCITX_UNUSED(entry);
FCITX_INFO() << keyEvent.key() << " isRelease=" << keyEvent.isRelease();
}

FCITX_ADDON_FACTORY(QuweiEngineFactory);</nowiki>

当实现 Fcitx 插件时，它应该是 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1AddonInstance.html AddonInstance] 的子类。AddonInstance 的实例化是通过 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1AddonFactory.html AddonFactory] 完成的。 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputMethodEngineV2.html InputMethodEngineV2] 是 AddonInstance 的子类。实现输入法插件时需要使用该类。

一个输入法引擎的最小植入只需要包含keyEvent函数的实现。

在这里，我们使用类似于宏 <code>FCITX_INFO()</code> 的 iostream 将我们按下的每个键写入日志。

这里假设您的 fcitx 安装前缀是 /usr。构建这个项目的命令是：

<nowiki>
mkdir -p build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug # use Debug for easy debugging with gdb
make # or ninja, depending on your system
sudo make install # or sudo ninja install</nowiki>

如果一切正常，安装命令应该打印出如下内容：

<nowiki>-- Install configuration: "Debug"
-- Installing: /usr/lib/fcitx5/quwei.so
-- Installing: /usr/share/fcitx5/addon/quwei.conf
-- Installing: /usr/share/fcitx5/inputmethod/quwei.conf</nowiki>

现在您可以使用 <code>fcitx5 -rd</code> 重新启动 fcitx5，并使用 [[Special:myLanguage/Configtool (Fcitx 5)|配置工具（Fcitx 5）]] 将 Quwei 添加到您的配置中。

切换到区位码输入法后，应用程序中的按键将使 Fcitx 5 打印出如下内容：

<nowiki>I2021-11-16 12:29:32.352702 quwei.cpp:12] Key(f states=0) isRelease=1
I2021-11-16 12:29:32.389935 quwei.cpp:12] Key(s states=0) isRelease=0
I2021-11-16 12:29:32.413689 quwei.cpp:12] Key(d states=0) isRelease=0
I2021-11-16 12:29:32.497661 quwei.cpp:12] Key(s states=0) isRelease=1
I2021-11-16 12:29:32.498021 quwei.cpp:12] Key(f states=0) isRelease=0
I2021-11-16 12:29:32.523816 quwei.cpp:12] Key(a states=0) isRelease=1
I2021-11-16 12:29:32.524051 quwei.cpp:12] Key(d states=0) isRelease=1
I2021-11-16 12:29:32.704919 quwei.cpp:12] Key(f states=0) isRelease=1
I2021-11-16 12:29:32.705006 quwei.cpp:12] Key(d states=0) isRelease=0
I2021-11-16 12:29:32.833024 quwei.cpp:12] Key(d states=0) isRelease=1
I2021-11-16 12:29:34.633936 quwei.cpp:12] Key(Control_L states=0) isRelease=0
I2021-11-16 12:29:35.053817 quwei.cpp:12] Key(Control+C states=4) isRelease=0
I2021-11-16 12:29:35.165617 quwei.cpp:12] Key(Control+C states=4) isRelease=1
I2021-11-16 12:29:35.348654 quwei.cpp:12] Key(Control+Control_L states=4) isRelease=1</nowiki>

从这里可以知道您的输入法引擎现在可以正常工作了。

= 实现输入法逻辑 =
区位码的基本逻辑是键入 4 位数的区位代码。区位码可以看成区码 xx 和位码 yy。区位码到GB2312的映射是(0xA0 + 区码, 0xA0 + 位码)。当用户键入 3 个数字的区位码时，输入法将显示一个包含 10 个可能带有给定区码为前缀的字符的候选列表。

可以参考 github 中 [https://github.com/fcitx/fcitx5-quwei/commit/b9b047abb46fa0f9c42a0be82941b65b35b277eb 第二笔提交] 的代码。

== 存储不同输入上下文的状态 ==
Fcitx 允许不同的输入上下文保持不同的状态。状态通常是指部分类型化的文本和所有其他关联的数据结构。在这个区位码的例子里面，状态是用户已经输入的数字。为了表示这一点，Fcitx 提供了一个方便的类 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputBuffer.html InputBuffer] 让输入法引擎可以便捷地使用这个类来编辑内部状态。为了在构造输入上下文时自动构造状态，Fcitx 提供了一个名为 InputContextProperty 的框架。为了使用它，您首先需要通过 registerProperty 向 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputContextManager.html InputContextManager] 注册一个工厂类。每个属性都需要有一个全局唯一的名称。名称可以是人类可以理解的东西。在这个区位码的例子里面，我使用的是“quweiState”。使用更好的名称的好处是，以防万一您正在开发一些交叉插件（另一个插件需要访问该插件的某些内部状态），您可以使用这个通用名称将其加载到不同的插件中。如果您不需要从外部访问，那么名称并不重要。

工厂类带有一个方便的 C++ 模板，[https://codedocs.xyz/fcitx/fcitx5/group__FcitxCore.html#ga9e60042d1f671a6fa31ea04bb4961ec9 FactoryFor]。这实际上是 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1LambdaInputContextPropertyFactory.html LambdaInputContextPropertyFactory] 的类型别名。该类仅接受 lambda 函数作为工厂实现。这可以节省您创建自己的 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputContextPropertyFactory.html InputContextPropertyFactory] 子类的时间。

为了从输入上下文中获取状态对象，您可以像这样简单地使用工厂对象：

<nowiki>
auto *state = ic->propertyFor(&factory_);</nowiki>

在某些情况下，也可以注销工厂并重新注册以“刷新”所有内部状态。

== 候选词列表 ==
在 Fcitx 5 中，候选列表是 InputPanel 类的一部分，存储为 shared_ptr 以避免选择候选触发用户界面更新时的生命周期问题。候选列表通过某些接口提供了不同的功能。辅助类 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1CommonCandidateList.html CommonCandidateList] 将为候选列表提供最常用的功能。它实现了 BulkCandidateList 接口，这就是为什么它不适合去中心化的情况。因为我们要有一个曲尾的半无限候选列表。

区位码中，QuweiCandidateList 将实现一个 PageableCandidate 接口，该接口允许在输入法面板中显示上一页/下一页按钮。

== 预编辑 ==
预编辑可以指代两种不同的用户界面元素，一种是嵌入在应用程序中的预编辑，在 Fcitx 中通常称为“客户端预编辑”。另一个显示在输入法面板窗口中。通常，输入法引擎只会使用其中一种，因为只有一种形式的预编辑需要显示。可以通过 capabilityFlags 属性检查输入上下文是否支持它。

在使用客户端预编辑时，您可能还需要考虑一些事项。由于 toolkit 中的实现不同，toolkit 可能会选择在应用程序失去焦点时立即提交客户端预编辑。对于某些输入法，它可能被设计成不需要额外确认的输入方式，例如，键盘引擎中的单词完成模式。在这种情况下，即使使用了预编辑，用户仍希望提交文本，即使它仍处于预编辑模式。从这个意义上说，预编辑文本应该与确认后提交的文本完全相同。

在某些版本的 iOS 中，其拼音输入法使用其客户端预编辑的方式可能会导致混淆：用户键入“nihao”，而客户端预编辑显示为分段拼音“ni hao”。当文本框失去焦点时，“ni hao”（多余的空格）将被提交到应用程序中，而这种结果在拼音的常规使用中永远不会发生。

另一件需要考虑的事情是把光标放在哪里。虽然在预编辑中将光标显示在其实际位置可能很自然，但输入面板窗口也会显示在客户端预编辑光标位置。也就是说，随着用户正常打字，当光标移动时，候选窗口也会随之移动。在某些情况下，这是不可取的，因为它会导致候选窗口在用户键入时频繁移动。另一种处理方法是将客户端光标始终设置为 0。如果需要支持显示实际光标的位置，则可以使用高亮样式。例如，当你在预编辑中有“ABCD”，光标在B和C之间时，你可以将客户端光标设置为0，使“AB”以高亮方式显示，以指示光标的位置。

== 按键事件处理 ==
最常见的用例是为您打算处理的所有按键事件调用 filterAndAccept()。此外，对于大多数输入法，按键释放是不相关的，应该传递给应用程序。要使输入法引擎能够处理任何用户输入，请务必考虑用户可能键入的所有可能的按键事件。例如，一个常见的错误是在组合模式中忘记屏蔽某个不相关的密钥，并将密钥泄露到应用程序中。另外，请注意带有修饰符的键事件，您可能希望传递此类键以使应用程序特定的热键即使在用户正在编写时仍然可以访问。

此外，一个按键事件有 3 种不同形式的 Key 对象。通常输入法引擎可能只想考虑 key() 属性。origKey() 和 rawKey() 属性使用较少。键属性是键事件的规范化形式。这删除了某些情况下的“Shift”修饰符，这使得输入法引擎更容易处理。例如，通过 Shift+A 和 Capslocked A 生成的大写字母 A 在归一化后将相同。您可以参考实现以了解此规范化的工作原理。

= 重用其他插件的功能 =
你可以参考 github 中 [https://github.com/fcitx/fcitx5-quwei/commit/b01bf8c4344b50b496593b4d9cf8be49cd1ce9c2 第三次提交] 的代码。

Fcitx 提供了一种机制来调用其他插件的功能，而无需直接链接到它们。还有一些易于使用的 CMake 宏来查找插件依赖项。

<nowiki>find_package(Fcitx5Module REQUIRED COMPONENTS Punctuation QuickPhrase)</nowiki>

我们在上面添加 find_package 行以查找 Punctuation 和 QuickPhrase 模块的依赖项。

如果你想实现这样的模块，你可以使用下面的CMake宏

<nowiki>fcitx5_export_module(QuickPhrase TARGET quickphrase BUILD_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_SOURCE_DIR}" HEADERS quickphrase_public.h INSTALL)</nowiki>

它会自动为您的插件生成所需的 CMake 配置。

When using other addons in the code, there is a handy macro <code>FCITX_ADDON_DEPENDENCY_LOADER</code> that will handle the addon loading at the runtime. When it is called for the first time, the dependent addon will be loaded automatically. Here we defines four different dependency in the code:

<nowiki> FCITX_ADDON_DEPENDENCY_LOADER(quickphrase, instance_->addonManager());
FCITX_ADDON_DEPENDENCY_LOADER(punctuation, instance_->addonManager());

private:
FCITX_ADDON_DEPENDENCY_LOADER(chttrans, instance_->addonManager());
FCITX_ADDON_DEPENDENCY_LOADER(fullwidth, instance_->addonManager());</nowiki>

第一个参数应与插件名称相同，第二个参数是获取 AddonManager 对象的表达式。

这种机制使得重用其他插件实现的功能和共享代码变得容易。比如 classicui 从 xcb addon 和 wayland addon 查询 X11/wayland 连接。

= 配置 =
虽然区位码并不真正需要这个功能，因为它是一个非常常见的用例，所以它会在本节中介绍。该插件有几个与配置相关的不同接口，例如 getConfig、setConfig、getConfigForInputMethod、setConfigForInputMethod、reloadConfig。getter 函数需要返回一个 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1Configuration.html Configuration] 对象，而 setConfig 接受一个 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1RawConfig.html RawConfig]目的。reloadConfig 将被调用以从磁盘重新加载配置，您可能也想在插件的构造函数中调用 reloadConfig()。

如果在插件注册文件中将 Configurable 字段设置为 True，则会调用此类方法来检索信息，Configtool 会为其生成 UI。

<nowiki>FCITX_CONFIGURATION(
ClipboardConfig, KeyListOption triggerKey{this,
"TriggerKey",
_("Trigger Key"),
{Key("Control+semicolon")},
KeyListConstrain()};
KeyListOption pastePrimaryKey{
this, "PastePrimaryKey", _("Paste Primary"), {}, KeyListConstrain()};
Option<int, IntConstrain> numOfEntries{this, "Number of entries",
_("Number of entries"), 5,
IntConstrain(3, 30)};);</nowiki>

通常，您将使用 FCITX_CONFIGURATION 宏定义 Configuration 的子类。第一个参数是类的名称，然后您只需添加 [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1Option.html Option] 作为成员。以下是 setConfig/getConfig/reloadConfig 的常见实现。

<nowiki> static constexpr char configFile[] = "conf/clipboard.conf";
void reloadConfig() override { readAsIni(config_, configFile); }

const Configuration *getConfig() const override { return &config_; }
void setConfig(const RawConfig &config) override {
config_.load(config, true);
safeSaveAsIni(config_, configFile);
}</nowiki>

readAsIni 和 safeSaveAsIni 是辅助函数，用于从 Fcitx ini 格式读取/保存配置对象。该文件保存在 $XDG_CONFIG_HOME 下。

Translations:Develop an simple input method/1/zh-cn

2025-01-11T23:30:41Z

Weng Xuetian:

这是编写 Fcitx 5 输入法的分步说明。同样的步骤也可以用于开发其他类型的插件，只是输入法引擎是最复杂的。

Using Fcitx 5 on Wayland

2024-12-31T08:03:26Z

Weng Xuetian: /* Chromium / Electron */

[https://wayland.freedesktop.org/ Wayland] is the next generation of display server protocol. While the initial release of the protocol is in 2008, the support of input method is not really ideal.

Also, using input method on Wayland-based compositor may require different setup to make it work, and certain features of fcitx that works under X11 are not yet supported by Wayland.

This page will try to cover all the current information with some underlying details, and [[Special:MyLanguage/Setup Fcitx 5|Setup Fcitx 5]] is still generally useful.

== Applications ==
=== TL;DR Do we still need XMODIFIERS, GTK_IM_MODULE and QT_IM_MODULE? ===

==== XMODIFIERS ====
For XMODIFIERS, yes, we do. X11 application running under X11 and XWayland has nearly no difference.

==== GTK_IM_MODULE ====
In an ideal setup, you should use fcitx im module Gtk application running under X11, and Gtk's text-input-v3 for wayland. The way of doing this is:

1. Do NOT set GTK_IM_MODULE environment variable.

2. For Gtk2, Add following content to ~/.gtkrc-2.0

<nowiki>gtk-im-module="fcitx"</nowiki>
3. For Gtk 3, add following content to ~/.config/gtk-3.0/settings.ini

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

4. For Gtk 4, add following content to ~/.config/gtk-4.0/settings.ini

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

5. If you are using GNOME 3+, also run following command.

<nowiki>gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/IMModule':<'fcitx'>}"</nowiki>

For GTK_IM_MODULE, as for now, the modern Gtk 3/4 application should be able to use text-input-v3 which is supported almost by every compositor, except weston. There are a few different options in terms of setting the value of GTK_IM_MODULE. When it is unset, the Gtk built-in Wayland im module will be used for Gtk3 and Gtk4. While you can also enforce it by doing GTK_IM_MODULE=wayland, remember it will be also picked up by Gtk2. Setting GTK_IM_MODULE=fcitx can still work, and it is necessary if your compositor does not support Wayland input method frontend.

It is possible to force a certain im module with Gtk configuration file, so without GTK_IM_MODULE set, it will still be able to use different im module.

Per Gtk implementation (still valid for 3.24.41), the order of preferences is:

* X11
** GTK_IM_MODULE in the environment
** Value of Gtk/IMModule from XSettings
** Value from configuration file
** A locale based automatic selection
* Wayland
** GTK_IM_MODULE in the environment
** "wayland"

==== QT_IM_MODULE ====
For QT_IM_MODULE, as for now QT can only use its own text-input-v{2,4}, which is only supported by KWin. Which means, under KDE you should unset it, but under other desktop, you will need to set it to QT_IM_MODULE=fcitx. Also the proprietary Qt applications in the wild complicates the situation. Some do not work on Wayland, some do not bundle/provide Qt wayland. Most of them do not bundle fcitx im module because fcitx is only a third party application to Qt, but I also noticed some do bundle but not bundle all the required libraries. While fcitx 5 support ibus protocol, some of those applications do not even bundle ibus im module. There are a few different environment variables you can try for those proprietary Qt applications (WPS, Anki, DaVinci Resolve, Mathematica, etc...).

<nowiki>QT_IM_MODULE=fcitx # For those who bundle qt im module, e.g. WPS, Anki, you should find a .so file with fcitx in the file name
QT_IM_MODULE=ibus # For those who bundle ibus im module shipped with Qt, you should find libibusplatforminputcontextplugin.so in the package.
QT_QPA_PLATFORM=xcb QT_IM_MODULE=ibus # Enforce it to run on X11/XWayland and use ibus im module
</nowiki>

In Qt 6.7, there is a new environment variable called "QT_IM_MODULES", which allows you so specify a fallback order on im modules. You can set it to

<nowiki>QT_IM_MODULES="wayland;fcitx;ibus"</nowiki>

So it will be able pick up the most usable one even for application that bundles no fcitx/wayland. Remember, you may still need to set( or unset) QT_IM_MODULE (not "QT_IM_MODULES") in order to handle Qt 4/5 applications.

=== Legacy X11 application that runs under XWayland ===
In a word, XWayland support for input method is as good as normal X11 display server. As long as you set the same environment variable, using Xwayland should not be a issue. This category includes:

* Xlib-based (and also other toolkit based on Xlib, e.g. tk, SDL1, etc), e.g. xterm, rxvt. Make sure XMODIFIERS is set correctly.
* Gtk2-based applications, similar to Xlib, but can use fcitx im module. Set GTK_IM_MODULE to fcitx will give it best experience.
* SDL2-based applications that doesn't default to wayland. Set SDL_IM_MODULE to fcitx
* electron, chromium, these are still default to X11, similar to Gtk2 case.
* For Qt4 applcation, Qt 4 can only use X11. You will need to QT_IM_MODULE to fcitx. Same for Qt5+ that uses XCB (can be override with QT_QPA_PLATFORM=xcb).

=== Gtk3 / Gtk4 ===
Gtk3 and Gtk4 support text-input-v3 natively. At the same time, it's also possible to use fcitx im module under wayland. So, either GTK_IM_MODULE=wayland or GTK_IM_MODULE=fcitx works. There are some difference to it. text-input-v3

=== Qt5 / Qt6 ===
If your Qt application natively runs under Wayland, you can either unset QT_IM_MODULE to make it use text-input-v2, or set QT_IM_MODULE=fcitx to make it use fcitx im module.

text-input-v2 is not upstreamed to wayland-protocols, that is probably why only kwin support it. This means in non-kwin environment, you will need to use QT_IM_MODULE=fcitx to make the Qt applications work.

On Qt6, you may also use QT_IM_MODULE= (empty) or QT_IM_MODULE=wayland if your Qt vesion contains this https://codereview.qt-project.org/c/qt/qtwayland/+/416862.

=== Native wayland application (winit) ===
Most likely text-input-v3 is being used.

=== Chromium / Electron ===
{{warning|The information in this section may not be up to date to reflect upstream change, especially the default behavior when no option is changed.}}
TL;DR version, if you use XWayland to run Chromium or Electron application, just install Gtk im module and GTK_IM_MODULE=fcitx the same way like X11.

If you choose to run it natively under Wayland, for chromium you will need to use

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

# If your compositor & chromium supports text-input-v3 protocol, you may also use
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=3

# However, due to a different understanding in text-input-v3 protocol, it has some issue when using with KWin.
# Prefer text-input-v1 if you're using kwin.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=1

Or

# You will get wrong position for the input method popup window, unless you use GNOME shell + kimpanel extension.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4

For electron, only the first option is avaiable (electron does NOT support to run internal chromium with gtk4), e.g. for vscode

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
code --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

By default it should run under Xwayland (As of 2023/02/25 on Archlinux/Chromium 110.0.5481.177), but some user also reports it is using wayland even the "Preferred Ozone Platform" is "Default". So to check whether it's really run with wayland, you can use xeyes or xwininfo. With xeyes, if it's an X11 window, the "eyes" will move with mouse, otherwise it's wayland. With xwininfo, if the mouse cursor changed to "+" shape, and click the window shows the window information, then it is a X11 window.

You may force it to run with Wayland, or X11 with the flag <code>--ozone-platform=wayland</code> and <code>--ozone-platform=x11</code>. You may persistent this by changing the option "Preferred Ozone Platform" in chrome://flags. It has four values, "Default", "X11", "Wayland", "Auto".

It's possible to make it use GTK_IM_MODULE if it runs with Gtk4 (only supported by chromium/chrome at this time, not electron) by passing <code>--gtk-version=4</code>.

It's also possible to make it use text-input-v1 by passing <code>--enable-wayland-ime</code> in addition to the flag above.

The Chromium support for text-input-v1 is not very stable and you may hit some random crash. E.g. in the past, version 112 has a crash bug: https://bugs.chromium.org/p/chromium/issues/detail?id=1431532 , which is fixed in version 115. In the bug comment, Chromium developer claims this text-input-v1 is only supposed to be used internally and not well supported, so use this at your own risk though it's currently the only out of box option.

You should only use one of <code>--enable-wayland-ime</code> or <code>--gtk-version=4</code>, depending on you want to use text-input-v1, or gtk4 im module. text-input-v1 works for kwin 5.27 and weston. Gtk4 im module works on all environment, but only GNOME with Kimpanel extension can display the popup window in the correct position.

== Support in Wayland Compositor ==

Even if you are using only native wayland applications, Xwayland is recommended to be enabled for following reason. If client side input panel in im module does not work, fcitx will fallback to a X11 window, instead of a wayland window. The reason for this is because wayland window can not be placed freely on the screen. On the contrary, even if im module can only pass a coordinate relative to the application window to fcitx, which make the coordinate position doesn't make much sense, if your application window size is "maximized", the coordinate may just be "right" if treated as the global coordinate. This makes X11 window a better option than a randomly placed wayland window.

=== KDE Plasma ===
Best setup:
* KDE Plasma 5.27
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Start fcitx5 by go to "System settings" -> "Virtual keyboard" -> Select Fcitx 5
** Do not set <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> & <code>SDL_IM_MODULE</code> . You could unset <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> by runing <code>im-config</code> and then selecting <code>do not set any IM from im-config and use desktop default"</code>
** Run chromium/electron application with <code>--enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime</code>
* Caveats:
** Certain Gtk/Qt application that only works under X11 may still need to set <code>GTK_IM_MODULE</code> or <code>QT_IM_MODULE</code> for them individually.
** If you set <code>GTK_IM_MODULE/QT_IM_MODULE</code> globally, you will hit this issue [[Special:MyLanguage/FAQ#Candidate_window_is_blinking_under_wayland_with_Fcitx_5|Candidate window is blinking under wayland with Fcitx 5]]

Support Information:
* App/Compositor supports text-input-v2 and text-input-v3.
* Comopositor/Application uses zwp_input_method_v1.
* 5.27 additionally supports text-input-v1.
* 5.24 usable zwp_input_method_v1 with fcitx5. Pre-5.24 there are lots of problems, always use fcitx im module instead.
* Use "Virtual keyboard" KCM to launch fcitx5. This is required to use text-input protocol. If you launch fcitx this way, make sure you do not use "restart" in the tray menu, since the socket passed from KWin can not be reused with the newly restarted fcitx.

=== GNOME ===
Best setup:
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Set <code>QT_IM_MODULE=fcitx</code> for Qt, since Qt5 would use XWayland by default.
** Run chrome with XWayland and <code>GTK_IM_MODULE=fcitx</code>

Support information:
* Application/Compositor uses text-input-v3
* Compositor/Input Method uses ibus dbus protocol, so ibus frontend is required to be used.
* Adding Fcitx 5 to autostart, it will replace any existing ibus-daemon upon start up so it will work out of box.
* Popup candidate window is not able to be displayed over gnome-shell UI. Only solution is to use [[Special:MyLanguage/Kimpanel|Kimpanel]], [https://extensions.gnome.org/extension/261/kimpanel/ link to extension].
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Sway ===
* Application/Compositor uses text-input-v3
* Comopositor/Application uses zwp_input_method_v2, but it's partially implemented. You will need [https://github.com/swaywm/sway/pull/7226 this pull request] to make it show the popup candidate window for text-input-v3 client.
* fcitx im module also works.
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Weston ===
* Application/Compositor uses text-input-v1
* Comopositor/Application uses zwp_input_method_v1.
* Since it has no text-input-v3, which is more commonly used, im module is the only solution for Gtk/Qt, need to set GTK_IM_MODULE=fcitx and QT_IM_MODULE=fcitx.
* Add following content to ~/.config/weston.ini to make it launch fcitx 5. (xwayland part is recommended to make fcitx work best, even if it's wayland)

<pre>
[core]
xwayland=true

[input-method]
path=/usr/bin/fcitx5
</pre>

=== Other compositors ===
Please check their upstream for more information. For wlroots based compositors, it is possible that they also support in the same way as Sway does, or zwp_input_method could also be unsupported.

== Known Issues ==
=== Fcitx managed XKB layout ===
Unlike X11, there is no generic way to set XKB layout to compositor, which means it can only be implemented for every individual desktop. Right now, Fcitx managed layout only works for KDE Plasma and GNOME.

As for other desktop, in order to make this "semi" work you'll need to ensure following:

* The XKB layout of the input method group should be the same as the actual xkb layout you configured for the compositor. Fcitx will "think" the layout is the same and bypass the key conversion logic.
* If you need other layout for text typing (e.g. Arabic), just add them to the Fcitx. As long as the key is forwarded to fcitx, it should work.

=== Popup candidate window ===
Wayland does not have a global coordinate system for regular client, so for native wayland client, it is impossible for Fcitx to place a wayland surface at a certain position. In order for popup window to be placed at the correct position, there are following cases:
* Xwayland have no problem and it should work as good as X11.
* If zwp_input_method protocol can be used, it has a surface role to allow compositor to place the popup window for input method. This only works if client uses text-input protocol.
* For GNOME, kimpanel extension can read window coordinate since it's running inside compositor. As long as im module can report relative coordinate, kimpanel extension can display the popup window at the correct position. As similar approach for Plasma kimpanel is planned, but not yet implemented.
* For Gtk/Qt, fcitx's im module implement a way to render the popup with in the client process. This has some limitation because implemenation of xdg_popup in Gtk3/Qt5 doesn't support reposition the window. So show/hide trick is used to mitigate this, but it may cause window blinking. Fcitx tries not to move window if possible. You may also disable popup animation if you're using KWin to help reduce the blinking.

=== Per-window input method state ===
When zwp_input_method is used, essentially there is only one input context visible to fcitx, and fcitx cannot distinguish what application is being used. Which means the input method "active"/"inactivate" state is now "global".

Now fcitx supports two protocol to figure out the focused window and the corresponding application name, including wlr-foreign-toplevel-management (used by wlroots based compositor) and plasma-window-management (used by kwin).

FAQ

2024-11-22T01:28:43Z

Weng Xuetian:

<languages/>
<translate>


When you want to complain about input method cannot work correctly, please read this first.


Since 4.2.7, fcitx provides a command called fcitx-diagnose, it will try to detect some common problem and give some advice.


[[Special:MyLanguage/Hall of Shame for Linux IME Support|Hall of Shame for Linux IME Support]]

== When use Ctrl + Space, Fcitx cannot be triggered on == 


Check the application you want to type into.

=== Wayland === 


See [[Special:MyLanguage/Using Fcitx 5 on Wayland|Using Fcitx 5 on Wayland]].

=== Only one specific app has problem? === 
* The most possible reason for this is Ctrl+Space occupied by some hotkey, please change to another trigger key and try again. This usually happens in some editor, since many ide use Ctrl+Space as default key binding for Completion.

=== All Gtk Apps have problem? === 
* Please open a traditional Gtk App (traditional Gtk App means, it cannot be Firefox, Libreoffice, which only use Gtk as a UI style). Gedit is a good choice. Right click at the input box, there will be a menu named "Input Method", please make sure there is "Fcitx" in it and being choosed.


* If there is "Fcitx", but it still not works. Please try to restart Fcitx, if it will works at this time, please check your DBus settings, or make Fcitx start later. You can read [[Special:MyLanguage/Configure (Other)|Configure (Other)]] if you're using a custom startup script.


* If there is Fcitx but not being choosed by default, and please select it and you can immediately try again in this app. If not works, please read the entry above. For permanent fix (To use Fcitx by default), please read Configure part in [[Special:MyLanguage/Install And Configure|Install And Configure]].


* If there is no Fcitx, you should check your install first. Usually, the package name contains fcitx and gtk. If you [[Special:MyLanguage/Compile from source|compile fcitx from source]], please make sure you have enable GTK{2,3}_IM_MODULE option. If you're sure about this, please read [[Special:MyLanguage/Input method related environment variables|Input method related environment variables]] for how to update some cached file for gtk.


* If you are using Ubuntu and upgrade to 12.04 recently, or something werid happens to your system (Due to packager careless, or buggy package manager which can not do upgrade in correct order, for example, [https://bugs.archlinux.org/task/32764 pacman]), you might notice that gtk.immodules related files doesn't generate correctly during upgrade. Try uninstall {{package ubuntu|fcitx-frontend-gtk2}}, {{package ubuntu|fcitx-frontend-gtk3}} or coressponding package on your system and re-install them to trigger the file generate. Then recheck the input method menu to see whether it have "Fcitx" in the menu or not.

=== All Qt Apps have problem? === 
* Run qtconfig (might have different name on your distribution, it might be qtconfig-qt4), and go to the third tab, make sure fcitx is in the "Default Input Method" combo-box. If not, please check your install.
* Above solution can also applies if you want use XIM, but still we highly recommend you to use im module. See Also [[Special:MyLanguage/Input method related environment variables|Input method related environment variables]].

==== Telegram desktop ==== 
Some distribution enables Qt6 for telegram desktop. Just make sure you have the Qt6 im module (For fcitx4, it's fcitx-qt6 on archlinux).

=== Chromium or any other chromium based browser (E.g. Microsoft Edge) === 
For Chromium running under X11, if you are using startx to start your graphical user interface, you may hit [https://gitlab.freedesktop.org/xorg/app/xinit/-/issues/9 an issue] in startx that unset the DBUS_SESSION_BUS_ADDRESS, which prevent chromium based browser from using dbus correctly. To mitigate this, you may:


1. either export DBUS_SESSION_BUS_ADDRESS by yourself in your ~/.xinitrc (or simply change to use ~/.xsession if you are using debian based system).


2. or use a display manager like sddm, gdm, lightdm instead of startx.


For Chromium that runs natively under wayland, the only native wayland input method protocol it supports is text-input-v1, which is only supported by weston. Alternatively, it can also use Gtk4's im module, you can use following flag (---enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4) to make it use Gtk im module, but it doesn't fully work in terms of popup window position unless you are using kimpanel + GNOME.

=== Is it Java, Xterm, wine, or some other non-Gtk/Qt Application? === 
There are also some very rare case, that you're using a embedded linux or mini-linux distro, in which you must use XIM, the X server might missing some locale file. The file is usually needed to be under /usr/share/X11/locale/.


And When you must use XIM, please make sure, your locale '''must NOT''' be C or POSIX and need to be a valid locale (no matter which language), and need to be generated if you are using glibc (locale-gen). When you are using im module, there is no such limitation.

=== Is it a Qt application that bundles its own Qt library? === 
Bundled Qt library usually uses theirs own plugin directory, which is different from system's Qt. And commonly, they are also using Qt different on system Qt, which will also make it incompatible if you simply copy the system fcitx-qt files. But anyway, you can start to check whether it loads your copied files with following environment variable. Depending on how the XIM application is written, it may need to find specific font to make it work. On Archlinux xorg-mkfontscale is required to generate correct font dir files. After install it, you'll need to restart X Server to make it work.


QT_DEBUG_PLUGINS=1 QT_LOGGING_RULES="*.debug=true"


And try to resolve all incompatible errors. Usually, ubuntu's fcitx-frontend-qt5 and libfcitxqt5-1 are good source for fcitx-qt5 build against specific qt version. For example, DraftSight 2017S0 [https://groups.google.com/forum/#!topic/fcitx/9e4TI39_4sk] may work with xenial's fcitx-qt5.

=== Emacs === 
Try


LC_CTYPE=zh_CN.UTF-8 emacs


Don't forget to check your locale -a contains that. See also [[Special:MyLanguage/Input method related environment variables|Input method related environment variables]].


Emacs will use `-*-*-*-r-normal--<some font size>-*-*-*-*-*-*-*' as basefont(in src/xfns.c), if you do not have one matched, the code for input method won't run. Install some font package may help (For required fonts xorg-fonts-misc might be the right package but you can also try other xorg-fonts-* package.).

=== Non Gtk/Qt Wayland Application (Alacritty, kitty, etc) === 
It is possible that the application you use does not support input method at all, because they need to have relevant code to implement it. Even if they do, it is highly possible that compositor does not have the support for input method. Only GNOME Shell and KWin has full text-input-v3 support. As of 2022/05/07, sway still does not have full zwp_input_method_v2 support to support input surface. For KWin, you will need Plasma 5.24+ and Fcitx 5.0.14+ and make KWin to start Fcitx 5. You will need to go to Virtual Keyboard KCM and select Fcitx 5 in the KCM.

== Candidate window is blinking under wayland with Fcitx 5 == 
This is mainly due to the whole poor state of wayland input method. The existing wayland input method protocol is not widely supported by compositor. Even though fcitx 5 support those protocols, the poor support in application and compositor make them not usable. Not to mention certain design flaw within the protocol.


In order to make input method some what usable with '''CURRENTLY''' available and widely adopted techniques, Fcitx 5 implements a mechanism called "Client Side Input Panel", which basically asks client application to render the input window. This is done through dbus and IM Module for Gtk/Qt. The implementation requires using a underlying wayland protocol xdg_popup to show the window. Unfortunately, only new version of xdg_popup protocol supports '''moving''' a visible popup window, and this part is '''NOT''' implemented in Gtk3 and Qt5. What makes it even worse is that Gtk3 and Qt5 both comes to their end of life, which means it is not possible to get this new protocol support in Gtk3/Qt5. The issue is that input method requires to display a window that resizes and moves extremely frequently. To mitigate this issue, Fcitx 5 IM Module implement a hack that when we need to move the window, it will hide the window first and then show the window. Unfortunately, this would cause certain-level of blinking. It might looks bad in certain hardware and compositor combination.


Here is some possible workaround for this.


1. Use kimpanel under GNOME shell, which will make the candidate window to be rendered with a totally different mechanism, which won't cause any blinking.


2. Disable Fade-in and Fade-Out effect under KWin. KWin seems to tolerate such blink much better than certain compositor.

== Problem in Firefox and Google Docs == 


You might want to toggle preedit off temporarily, which is Ctrl+Alt+P.

== Cannot use Fcitx in flash == 


Please read [[Special:MyLanguage/Hall of Shame for Linux IME Support|Hall of Shame for Linux IME Support]], and use im module.

== Cannot type English after updating to fcitx newer than 4.2.4 == 


Make sure you have add "[[Special:myLanguage/Keyboard|Keyboard]]" to the input method list. You can use [[Special:myLanguage/Integrate with Desktop#Configuration tool|Configuration tool]].


And you may want to move "Keyboard" to the first one.

== Unexpected keyboard layout change == 


Use [[Special:myLanguage/Integrate with Desktop#Configuration tool|Configuration tool]], to bind specific keyboard layout to the specific input method.

== xmodmap settings being overwritten == 


Fcitx now control keyboard layout and when switch layout, xmodmap setting will be overwritten. So fcitx-xkb provides an option to specify the xmodmap script and let fcitx loads it for you whenever keyboard layout changes. Or disable fcitx-xkb addon is also a solution for you, or if your requirement is simply, for example, switching Caps Lock and Esc, which is provided by xkb option, you can just set it with your desktop keyboard configuration tool (Gnome and KDE all support such configuration).


For more detailed explanation, xmodmap is a very low level tool, that doesn't aware keyboard layout. For X11, keyboard layout is built on a set of profile, when such profile is loaded, anything you changed with xmodmap will be overwritten, this isn't specific to fcitx, but all tool that support keyboard layout configuration. Xkb option is a set of profile that can do some pre-defined change over keyboard layout, including many thing that people usually do with xmodmap, for example, defining where dead key is, switching Caps Lock and Esc, and so on. Unless you have special requirements, xkb layout and xkb option is recommended.


Since 4.2.7, Fcitx will try to load ~/.Xmodmap if it exists.

== Configure user interface, font, vertical list == 


Use [[Special:myLanguage/Integrate with Desktop#Configuration tool|Configuration tool]], Addon Configuration -> Classic UI.


If you are using [[Special:myLanguage/Configtool|fcitx-configtool]] newer than 0.4.5 or [[Special:myLanguage/Kcm|kcm-fcitx]] newer 0.4.1, you can directly configure those from the first level tab.

== Possible issue for GNOME 3.6 == 


[[Note for GNOME Later than 3.6]]

== [[Special:MyLanguage/ClassicUI|Classic UI]] is not transparent == 

* This problem might NOT exist any more since 4.2.6 with a different approach for detect composite manager.
* Restart Fcitx first, if it's ok then, it might be a bug in your Window manager. Gnome-Shell, xcompmgr is known to have this bug. You can try to set the delay start to walkaround this problem.
* If restart Fcitx doesn't solve this problem, you should check whether your window manager supports composite or it's enabled or not.
=== Kwin === 

Enable desktop effects.
=== Metacity before GNOME3 === 

gconftool-2 -s --type bool /apps/metacity/general/compositing_manager true
=== Xfce === 

Xfwm support composite, but need to be enabled by hand.
=== Compiz === 

0.9 series compiz can disable composite. You can use ccsm to configure it.
=== Other window manager === 


You can use xcompmgr, cairo-compmgr as composite manager for them.

== Minecraft == 


Original Minecraft under linux doesn't support input method, what make it worse is, XIM will conflict with its key event processing, one way to work around is, set a wrong environment variable on purpose for minecraft, then start up it. You can use following script to do that


<pre>#!/bin/sh
# set a wrong one
export XMODIFIERS="@im=null"
# start minecraft, this might change depends on you're mod, but simply its what you ARE using to start minecraft.
java -Xmx1024M -Xms512M -cp minecraft.jar net.minecraft.LauncherFrame</pre>


This way can be also used, if you don't want fcitx to work on some application which is using XIM.


There is a mod can be used to support input under Linux, called [http://forum.minecraftuser.jp/viewtopic.php?t=6279 NihongoMOD], 1.2.2 with minecraft 1.5.2 can work with Fcitx without upper hack.

== Root application under normal user X == 
Root application under X normal user session is always broken (in general, not specific to fcitx), due to the fact that dbus is a user session only process. The only way to type in root application with normal fcitx is to use XIM, set GTK_IM_MODULE=xim and QT_IM_MODULE=xim before you start your application.

== Cursor Following problem == 
There is a common misunderstanding that it's input method's fault that input window could not follow the cursor, which is simply wrong. This is how cursor following works: Application send the position to Input method, then input method move the input window. So if application do not send the position, the position would be wrong. This behavior is controlled by application, but not input method. So if you meet any problem, please ask application to fix it, don't ask input method to do anything. Actually, input method could do nothing with this.


Although there is some walkaround for specific problem, bug is still in application, not in input method.


* Opera, enable on the spot for [[Special:MyLanguage/XIM|XIM]].
* Firefox, enable preedit.
* Java program that uses swing or awt. There is a historical OpenJDK bug. But jetbrains patches there own JDK with the fix. https://youtrack.jetbrains.com/issue/JBR-2460/Wrong-position-of-input-window-and-no-input-preview-with-fcitx-and-ubuntu-13.04 You may want to try jetbrains jdk instead. Confirmed that 21.0.5b631.19 can work properly.

== Colored Emoji ==
The issue itself is usually not relevant to Fcitx itself, but the library used to render text. When using X11, or using native wayland input method protocol, the text is rendered by pango, which is the same as Gtk. You can also check if Gtk application is fine with such emoji character. A common issue is that, the embedded bitmap font is disabled by fontconfig, which is required to display color emoji.

As for Wayland that uses "Client side input panel" feature, the text is rendered natively by the toolkit. If it is a Qt application, which you may hit some Qt bugs: https://bugreports.qt.io/browse/QTBUG-80434 , https://bugreports.qt.io/browse/QTBUG-85744 , which does not have a resolution yet.


[[Category:How-to]]

</translate>

Template:GithubAtom

2024-06-14T07:03:13Z

Weng Xuetian:

'''===== {{{title}}} ====='''

: {{{content}}}

Template:GithubAtom

2024-06-14T07:02:34Z

Weng Xuetian:

===== {{{title}}} =====

: {{{content}}}

Template:GithubAtom

2024-06-14T07:01:14Z

Weng Xuetian:

{{{title}}}

: {{{content}}}

Template:GithubAtom

2024-06-14T07:00:04Z

Weng Xuetian:

{{{title}}}

<nowiki>{{{content}}}</nowiki>

Template:GithubAtom

2024-06-14T06:59:03Z

Weng Xuetian:

{{{title}}}

{{{content}}}

Fcitx 5

2024-06-14T00:36:34Z

Weng Xuetian:

<languages/>
<translate>


Fcitx [ˈfaɪtɪks] is an input method framework with extension support. Currently it supports Linux and Unix systems like freebsd. Fcitx supports typing with many languages all over the world with a large number of engines.


Fcitx has a slim core while provides powerful features with addons. It is easy to customize fcitx to satisfy your own needs.


[[Special:myLanguage/Fcitx|Looking for Old Wiki Page for Fcitx 4?]]

==== For Users ==== 


* [[Special:myLanguage/Install Fcitx 5|Install Fcitx 5]]
* [[Special:myLanguage/Setup Fcitx 5|Setup Fcitx 5]]
* Install [[Special:myLanguage/Input method engines|Input method engines]]
* [[Special:myLanguage/Theme Customization|Theme Customization]]
* [[Special:myLanguage/FAQ|FAQ]]
* [[Special:myLanguage/Using Fcitx 5 on Wayland|Using Fcitx 5 on Wayland]]
* [[Special:myLanguage/Tips and Tricks|Tips and Tricks]]
* [[Special:myLanguage/Upgrade from Fcitx 4|Upgrade from Fcitx 4]]

==== For Developers ==== 


* [[Special:myLanguage/Compiling fcitx5|Compiling fcitx5]]
* [[Special:myLanguage/Basic concept|Basic concept]]
* [[Special:myLanguage/Develop an simple input method|Develop an simple input method]]
* [[Special:myLanguage/Q&A for developer|Q&A for developer]]
* [[Special:myLanguage/Debug fcitx5|Debug fcitx5]]

==== News ==== 


<rss max=5 template="Template:GithubAtom">https://github.com/fcitx/fcitx5/releases.atom</rss>

== Help Fcitx == 
* Recommend Fcitx to your friend
* [[Special:myLanguage/Report Bug|Report Bug]]
* [[Special:myLanguage/Contribute to this Wiki|Contribute to this Wiki]] ('''Please read this before you request account''')
* [[Special:myLanguage/Donate|Donate]]

== About Fcitx == 
* [[Special:myLanguage/History|History]]

</translate>

Fcitx 5

2024-06-14T00:33:42Z

Weng Xuetian:

<languages/>
<translate>


Fcitx [ˈfaɪtɪks] is an input method framework with extension support. Currently it supports Linux and Unix systems like freebsd. Fcitx supports typing with many languages all over the world with a large number of engines.


Fcitx has a slim core while provides powerful features with addons. It is easy to customize fcitx to satisfy your own needs.


[[Special:myLanguage/Fcitx|Looking for Old Wiki Page for Fcitx 4?]]

==== For Users ==== 


* [[Special:myLanguage/Install Fcitx 5|Install Fcitx 5]]
* [[Special:myLanguage/Setup Fcitx 5|Setup Fcitx 5]]
* Install [[Special:myLanguage/Input method engines|Input method engines]]
* [[Special:myLanguage/Theme Customization|Theme Customization]]
* [[Special:myLanguage/FAQ|FAQ]]
* [[Special:myLanguage/Using Fcitx 5 on Wayland|Using Fcitx 5 on Wayland]]
* [[Special:myLanguage/Tips and Tricks|Tips and Tricks]]
* [[Special:myLanguage/Upgrade from Fcitx 4|Upgrade from Fcitx 4]]

==== For Developers ==== 


* [[Special:myLanguage/Compiling fcitx5|Compiling fcitx5]]
* [[Special:myLanguage/Basic concept|Basic concept]]
* [[Special:myLanguage/Develop an simple input method|Develop an simple input method]]
* [[Special:myLanguage/Q&A for developer|Q&A for developer]]
* [[Special:myLanguage/Debug fcitx5|Debug fcitx5]]

==== News ==== 


<rss max=5 templatename="Template:GithubAtom">https://github.com/fcitx/fcitx5/releases.atom</rss>

== Help Fcitx == 
* Recommend Fcitx to your friend
* [[Special:myLanguage/Report Bug|Report Bug]]
* [[Special:myLanguage/Contribute to this Wiki|Contribute to this Wiki]] ('''Please read this before you request account''')
* [[Special:myLanguage/Donate|Donate]]

== About Fcitx == 
* [[Special:myLanguage/History|History]]

</translate>

Fcitx 5

2024-06-14T00:33:27Z

Weng Xuetian:

<languages/>
<translate>


Fcitx [ˈfaɪtɪks] is an input method framework with extension support. Currently it supports Linux and Unix systems like freebsd. Fcitx supports typing with many languages all over the world with a large number of engines.


Fcitx has a slim core while provides powerful features with addons. It is easy to customize fcitx to satisfy your own needs.


[[Special:myLanguage/Fcitx|Looking for Old Wiki Page for Fcitx 4?]]

==== For Users ==== 


* [[Special:myLanguage/Install Fcitx 5|Install Fcitx 5]]
* [[Special:myLanguage/Setup Fcitx 5|Setup Fcitx 5]]
* Install [[Special:myLanguage/Input method engines|Input method engines]]
* [[Special:myLanguage/Theme Customization|Theme Customization]]
* [[Special:myLanguage/FAQ|FAQ]]
* [[Special:myLanguage/Using Fcitx 5 on Wayland|Using Fcitx 5 on Wayland]]
* [[Special:myLanguage/Tips and Tricks|Tips and Tricks]]
* [[Special:myLanguage/Upgrade from Fcitx 4|Upgrade from Fcitx 4]]

==== For Developers ==== 


* [[Special:myLanguage/Compiling fcitx5|Compiling fcitx5]]
* [[Special:myLanguage/Basic concept|Basic concept]]
* [[Special:myLanguage/Develop an simple input method|Develop an simple input method]]
* [[Special:myLanguage/Q&A for developer|Q&A for developer]]
* [[Special:myLanguage/Debug fcitx5|Debug fcitx5]]

==== News ==== 


<rss max=5 templatename="Template:GithubAtom">http://github.com/fcitx/fcitx5/releases.atom</rss>

== Help Fcitx == 
* Recommend Fcitx to your friend
* [[Special:myLanguage/Report Bug|Report Bug]]
* [[Special:myLanguage/Contribute to this Wiki|Contribute to this Wiki]] ('''Please read this before you request account''')
* [[Special:myLanguage/Donate|Donate]]

== About Fcitx == 
* [[Special:myLanguage/History|History]]

</translate>

Template:GithubAtom

2024-06-14T00:31:26Z

Weng Xuetian: Created page with "{{{title}}} {{{content}}}"

{{{title}}}

{{{content}}}

MediaWiki:Rss-feed

2024-06-14T00:25:31Z

Weng Xuetian:

; '''<span class='plainlinks'>[{{{link}}} {{{title}}}]</span>'''
: {{{description}}}

MediaWiki:Rss-feed

2024-06-14T00:22:57Z

Weng Xuetian:

; '''<span class='plainlinks'>[{{{link}}} {{{title}}}]</span>'''
: {{{content}}}

Fcitx 5

2024-06-13T23:10:20Z

Weng Xuetian:

<languages/>
<translate>


Fcitx [ˈfaɪtɪks] is an input method framework with extension support. Currently it supports Linux and Unix systems like freebsd. Fcitx supports typing with many languages all over the world with a large number of engines.


Fcitx has a slim core while provides powerful features with addons. It is easy to customize fcitx to satisfy your own needs.


[[Special:myLanguage/Fcitx|Looking for Old Wiki Page for Fcitx 4?]]

==== For Users ==== 


* [[Special:myLanguage/Install Fcitx 5|Install Fcitx 5]]
* [[Special:myLanguage/Setup Fcitx 5|Setup Fcitx 5]]
* Install [[Special:myLanguage/Input method engines|Input method engines]]
* [[Special:myLanguage/Theme Customization|Theme Customization]]
* [[Special:myLanguage/FAQ|FAQ]]
* [[Special:myLanguage/Using Fcitx 5 on Wayland|Using Fcitx 5 on Wayland]]
* [[Special:myLanguage/Tips and Tricks|Tips and Tricks]]
* [[Special:myLanguage/Upgrade from Fcitx 4|Upgrade from Fcitx 4]]

==== For Developers ==== 


* [[Special:myLanguage/Compiling fcitx5|Compiling fcitx5]]
* [[Special:myLanguage/Basic concept|Basic concept]]
* [[Special:myLanguage/Develop an simple input method|Develop an simple input method]]
* [[Special:myLanguage/Q&A for developer|Q&A for developer]]
* [[Special:myLanguage/Debug fcitx5|Debug fcitx5]]

==== News ==== 


<rss max=5>https://politepol.com/fd/hhM5BOjZLblk</rss>

== Help Fcitx == 
* Recommend Fcitx to your friend
* [[Special:myLanguage/Report Bug|Report Bug]]
* [[Special:myLanguage/Contribute to this Wiki|Contribute to this Wiki]] ('''Please read this before you request account''')
* [[Special:myLanguage/Donate|Donate]]

== About Fcitx == 
* [[Special:myLanguage/History|History]]

</translate>

Fcitx 5/zh-cn

2024-06-13T22:50:26Z

Weng Xuetian:

<languages/>

小企鹅输入法（Fcitx 读作[ˈfaɪtɪks]）是一个支持扩展的输入法框架。目前，它支持Linux操作系统，以及如freebsd这样的Unix操作系统。Fcitx 通过使用各种各样的输入法引擎来支持全世界大量不同种类的语言。

Fcitx本身的核心实现非常简单，它通过使用插件来提供强大的功能。fcitx可以非常容易的进行定制以满足不同的个性化需求。

[[Special:myLanguage/Fcitx|导航至旧版的 Fcitx 4 Wiki页面?]]

==== 用户 ====

* [[Special:myLanguage/Install Fcitx 5|如何安装 Fcitx 5]]
* [[Special:myLanguage/Setup Fcitx 5|设置 Fcitx 5]]
* 安装 [[Special:myLanguage/Input method engines|输入法引擎]]
* [[Special:myLanguage/Theme Customization|定制您的输入法主题]]
* [[Special:myLanguage/FAQ|常见问题]]
* [[Special:myLanguage/Using Fcitx 5 on Wayland|在 Wayland 上使用 Fcitx 5]]
* [[Special:myLanguage/Tips and Tricks|使用技巧]]
* [[Special:myLanguage/Upgrade from Fcitx 4|从 Fcitx 4 升级]]

==== 开发者 ====

* [[Special:myLanguage/Compiling fcitx5|如何编译 fcitx5]]
* [[Special:myLanguage/Basic concept|基本概念]]
* [[Special:myLanguage/Develop an simple input method|如何开发一个简单的输入法]]
* [[Special:myLanguage/Q&A for developer|开发者常见问题与解答]]
* [[Special:myLanguage/Debug fcitx5|调试 fcitx5]]

==== 新闻 ====

<rss max=5>https://github.com/fcitx/fcitx5/releases.atom</rss>

== 如何帮助 Fcitx ==
* 给你的朋友推荐Fcitx输入法
* [[Special:myLanguage/Report Bug|报告漏洞]]
* [[Special:myLanguage/Contribute to this Wiki|为Wiki做贡献]] ('''请在申请你的帐号之前仔细阅读此页面''')
* [[Special:myLanguage/Donate|捐助]]

== 关于 ==
* [[Special:myLanguage/History|Fcitx的历史]]

Translations:Fcitx 5/9/zh-cn

2024-06-13T22:50:26Z

Weng Xuetian:

<rss max=5>https://github.com/fcitx/fcitx5/releases.atom</rss>

Fcitx 5

2024-06-13T22:41:57Z

Weng Xuetian:

<languages/>
<translate>


Fcitx [ˈfaɪtɪks] is an input method framework with extension support. Currently it supports Linux and Unix systems like freebsd. Fcitx supports typing with many languages all over the world with a large number of engines.


Fcitx has a slim core while provides powerful features with addons. It is easy to customize fcitx to satisfy your own needs.


[[Special:myLanguage/Fcitx|Looking for Old Wiki Page for Fcitx 4?]]

==== For Users ==== 


* [[Special:myLanguage/Install Fcitx 5|Install Fcitx 5]]
* [[Special:myLanguage/Setup Fcitx 5|Setup Fcitx 5]]
* Install [[Special:myLanguage/Input method engines|Input method engines]]
* [[Special:myLanguage/Theme Customization|Theme Customization]]
* [[Special:myLanguage/FAQ|FAQ]]
* [[Special:myLanguage/Using Fcitx 5 on Wayland|Using Fcitx 5 on Wayland]]
* [[Special:myLanguage/Tips and Tricks|Tips and Tricks]]
* [[Special:myLanguage/Upgrade from Fcitx 4|Upgrade from Fcitx 4]]

==== For Developers ==== 


* [[Special:myLanguage/Compiling fcitx5|Compiling fcitx5]]
* [[Special:myLanguage/Basic concept|Basic concept]]
* [[Special:myLanguage/Develop an simple input method|Develop an simple input method]]
* [[Special:myLanguage/Q&A for developer|Q&A for developer]]
* [[Special:myLanguage/Debug fcitx5|Debug fcitx5]]

==== News ==== 


<rss max=5>https://github.com/fcitx/fcitx5/releases.atom</rss>

== Help Fcitx == 
* Recommend Fcitx to your friend
* [[Special:myLanguage/Report Bug|Report Bug]]
* [[Special:myLanguage/Contribute to this Wiki|Contribute to this Wiki]] ('''Please read this before you request account''')
* [[Special:myLanguage/Donate|Donate]]

== About Fcitx == 
* [[Special:myLanguage/History|History]]

</translate>

Fcitx 5/zh-cn

2024-05-01T21:01:45Z

Weng Xuetian:

<languages/>

小企鹅输入法（Fcitx 读作[ˈfaɪtɪks]）是一个支持扩展的输入法框架。目前，它支持Linux操作系统，以及如freebsd这样的Unix操作系统。Fcitx 通过使用各种各样的输入法引擎来支持全世界大量不同种类的语言。

Fcitx本身的核心实现非常简单，它通过使用插件来提供强大的功能。fcitx可以非常容易的进行定制以满足不同的个性化需求。

[[Special:myLanguage/Fcitx|导航至旧版的 Fcitx 4 Wiki页面?]]

==== 用户 ====

* [[Special:myLanguage/Install Fcitx 5|如何安装 Fcitx 5]]
* [[Special:myLanguage/Setup Fcitx 5|设置 Fcitx 5]]
* 安装 [[Special:myLanguage/Input method engines|输入法引擎]]
* [[Special:myLanguage/Theme Customization|定制您的输入法主题]]
* [[Special:myLanguage/FAQ|常见问题]]
* [[Special:myLanguage/Using Fcitx 5 on Wayland|在 Wayland 上使用 Fcitx 5]]
* [[Special:myLanguage/Tips and Tricks|使用技巧]]
* [[Special:myLanguage/Upgrade from Fcitx 4|从 Fcitx 4 升级]]

==== 开发者 ====

* [[Special:myLanguage/Compiling fcitx5|如何编译 fcitx5]]
* [[Special:myLanguage/Basic concept|基本概念]]
* [[Special:myLanguage/Develop an simple input method|如何开发一个简单的输入法]]
* [[Special:myLanguage/Q&A for developer|开发者常见问题与解答]]
* [[Special:myLanguage/Debug fcitx5|调试 fcitx5]]

==== 新闻 ====

<rss max=5>https://politepol.com/fd/hhM5BOjZLblk</rss>

== 如何帮助 Fcitx ==
* 给你的朋友推荐Fcitx输入法
* [[Special:myLanguage/Report Bug|报告漏洞]]
* [[Special:myLanguage/Contribute to this Wiki|为Wiki做贡献]] ('''请在申请你的帐号之前仔细阅读此页面''')
* [[Special:myLanguage/Donate|捐助]]

== 关于 ==
* [[Special:myLanguage/History|Fcitx的历史]]

Translations:Fcitx 5/5/zh-cn

2024-05-01T21:01:45Z

Weng Xuetian:

* [[Special:myLanguage/Install Fcitx 5|如何安装 Fcitx 5]]
* [[Special:myLanguage/Setup Fcitx 5|设置 Fcitx 5]]
* 安装 [[Special:myLanguage/Input method engines|输入法引擎]]
* [[Special:myLanguage/Theme Customization|定制您的输入法主题]]
* [[Special:myLanguage/FAQ|常见问题]]
* [[Special:myLanguage/Using Fcitx 5 on Wayland|在 Wayland 上使用 Fcitx 5]]
* [[Special:myLanguage/Tips and Tricks|使用技巧]]
* [[Special:myLanguage/Upgrade from Fcitx 4|从 Fcitx 4 升级]]

Using Fcitx 5 on Wayland

2024-04-07T05:08:53Z

Weng Xuetian:

[https://wayland.freedesktop.org/ Wayland] is the next generation of display server protocol. While the initial release of the protocol is in 2008, the support of input method is not really ideal.

Also, using input method on Wayland-based compositor may require different setup to make it work, and certain features of fcitx that works under X11 are not yet supported by Wayland.

This page will try to cover all the current information with some underlying details, and [[Special:MyLanguage/Setup Fcitx 5|Setup Fcitx 5]] is still generally useful.

== Applications ==
=== TL;DR Do we still need XMODIFIERS, GTK_IM_MODULE and QT_IM_MODULE? ===

==== XMODIFIERS ====
For XMODIFIERS, yes, we do. X11 application running under X11 and XWayland has nearly no difference.

==== GTK_IM_MODULE ====
In an ideal setup, you should use fcitx im module Gtk application running under X11, and Gtk's text-input-v3 for wayland. The way of doing this is:

1. Do NOT set GTK_IM_MODULE environment variable.

2. For Gtk2, Add following content to ~/.gtkrc-2.0

<nowiki>gtk-im-module="fcitx"</nowiki>
3. For Gtk 3, add following content to ~/.config/gtk-3.0/settings.ini

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

4. For Gtk 4, add following content to ~/.config/gtk-4.0/settings.ini

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

5. If you are using GNOME 3+, also run following command.

<nowiki>gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/IMModule':<'fcitx'>}"</nowiki>

For GTK_IM_MODULE, as for now, the modern Gtk 3/4 application should be able to use text-input-v3 which is supported almost by every compositor, except weston. There are a few different options in terms of setting the value of GTK_IM_MODULE. When it is unset, the Gtk built-in Wayland im module will be used for Gtk3 and Gtk4. While you can also enforce it by doing GTK_IM_MODULE=wayland, remember it will be also picked up by Gtk2. Setting GTK_IM_MODULE=fcitx can still work, and it is necessary if your compositor does not support Wayland input method frontend.

It is possible to force a certain im module with Gtk configuration file, so without GTK_IM_MODULE set, it will still be able to use different im module.

Per Gtk implementation (still valid for 3.24.41), the order of preferences is:

* X11
** GTK_IM_MODULE in the environment
** Value of Gtk/IMModule from XSettings
** Value from configuration file
** A locale based automatic selection
* Wayland
** GTK_IM_MODULE in the environment
** "wayland"

==== QT_IM_MODULE ====
For QT_IM_MODULE, as for now QT can only use its own text-input-v{2,4}, which is only supported by KWin. Which means, under KDE you should unset it, but under other desktop, you will need to set it to QT_IM_MODULE=fcitx. Also the proprietary Qt applications in the wild complicates the situation. Some do not work on Wayland, some do not bundle/provide Qt wayland. Most of them do not bundle fcitx im module because fcitx is only a third party application to Qt, but I also noticed some do bundle but not bundle all the required libraries. While fcitx 5 support ibus protocol, some of those applications do not even bundle ibus im module. There are a few different environment variables you can try for those proprietary Qt applications (WPS, Anki, DaVinci Resolve, Mathematica, etc...).

<nowiki>QT_IM_MODULE=fcitx # For those who bundle qt im module, e.g. WPS, Anki, you should find a .so file with fcitx in the file name
QT_IM_MODULE=ibus # For those who bundle ibus im module shipped with Qt, you should find libibusplatforminputcontextplugin.so in the package.
QT_QPA_PLATFORM=xcb QT_IM_MODULE=ibus # Enforce it to run on X11/XWayland and use ibus im module
</nowiki>

In Qt 6.7, there is a new environment variable called "QT_IM_MODULES", which allows you so specify a fallback order on im modules. You can set it to

<nowiki>QT_IM_MODULES="wayland;fcitx;ibus"</nowiki>

So it will be able pick up the most usable one even for application that bundles no fcitx/wayland. Remember, you may still need to set( or unset) QT_IM_MODULE (not "QT_IM_MODULES") in order to handle Qt 4/5 applications.

=== Legacy X11 application that runs under XWayland ===
In a word, XWayland support for input method is as good as normal X11 display server. As long as you set the same environment variable, using Xwayland should not be a issue. This category includes:

* Xlib-based (and also other toolkit based on Xlib, e.g. tk, SDL1, etc), e.g. xterm, rxvt. Make sure XMODIFIERS is set correctly.
* Gtk2-based applications, similar to Xlib, but can use fcitx im module. Set GTK_IM_MODULE to fcitx will give it best experience.
* SDL2-based applications that doesn't default to wayland. Set SDL_IM_MODULE to fcitx
* electron, chromium, these are still default to X11, similar to Gtk2 case.
* For Qt4 applcation, Qt 4 can only use X11. You will need to QT_IM_MODULE to fcitx. Same for Qt5+ that uses XCB (can be override with QT_QPA_PLATFORM=xcb).

=== Gtk3 / Gtk4 ===
Gtk3 and Gtk4 support text-input-v3 natively. At the same time, it's also possible to use fcitx im module under wayland. So, either GTK_IM_MODULE=wayland or GTK_IM_MODULE=fcitx works. There are some difference to it. text-input-v3

=== Qt5 / Qt6 ===
If your Qt application natively runs under Wayland, you can either unset QT_IM_MODULE to make it use text-input-v2, or set QT_IM_MODULE=fcitx to make it use fcitx im module.

text-input-v2 is not upstreamed to wayland-protocols, that is probably why only kwin support it. This means in non-kwin environment, you will need to use QT_IM_MODULE=fcitx to make the Qt applications work.

On Qt6, you may also use QT_IM_MODULE= (empty) or QT_IM_MODULE=wayland if your Qt vesion contains this https://codereview.qt-project.org/c/qt/qtwayland/+/416862.

=== Native wayland application (winit) ===
Most likely text-input-v3 is being used.

=== Chromium / Electron ===
{{warning|The information in this section may not be up to date to reflect upstream change, especially the default behavior when no option is changed.}}
TL;DR version, if you use XWayland to run Chromium or Electron application, just install Gtk im module and GTK_IM_MODULE=fcitx the same way like X11.

If you choose to run it natively under Wayland, for chromium you will need to use

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

Or

# You will get wrong position for the input method popup window, unless you use GNOME shell + kimpanel extension.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4

For electron, only the first option is avaiable (electron does NOT support to run internal chromium with gtk4), e.g. for vscode

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
code --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

By default it should run under Xwayland (As of 2023/02/25 on Archlinux/Chromium 110.0.5481.177), but some user also reports it is using wayland even the "Preferred Ozone Platform" is "Default". So to check whether it's really run with wayland, you can use xeyes or xwininfo. With xeyes, if it's an X11 window, the "eyes" will move with mouse, otherwise it's wayland. With xwininfo, if the mouse cursor changed to "+" shape, and click the window shows the window information, then it is a X11 window.

You may force it to run with Wayland, or X11 with the flag <code>--ozone-platform=wayland</code> and <code>--ozone-platform=x11</code>. You may persistent this by changing the option "Preferred Ozone Platform" in chrome://flags. It has four values, "Default", "X11", "Wayland", "Auto".

It's possible to make it use GTK_IM_MODULE if it runs with Gtk4 (only supported by chromium/chrome at this time, not electron) by passing <code>--gtk-version=4</code>.

It's also possible to make it use text-input-v1 by passing <code>--enable-wayland-ime</code> in addition to the flag above.

The Chromium support for text-input-v1 is not very stable and you may hit some random crash. E.g. in the past, version 112 has a crash bug: https://bugs.chromium.org/p/chromium/issues/detail?id=1431532 , which is fixed in version 115. In the bug comment, Chromium developer claims this text-input-v1 is only supposed to be used internally and not well supported, so use this at your own risk though it's currently the only out of box option.

You should only use one of <code>--enable-wayland-ime</code> or <code>--gtk-version=4</code>, depending on you want to use text-input-v1, or gtk4 im module. text-input-v1 works for kwin 5.27 and weston. Gtk4 im module works on all environment, but only GNOME with Kimpanel extension can display the popup window in the correct position.

== Support in Wayland Compositor ==

Even if you are using only native wayland applications, Xwayland is recommended to be enabled for following reason. If client side input panel in im module does not work, fcitx will fallback to a X11 window, instead of a wayland window. The reason for this is because wayland window can not be placed freely on the screen. On the contrary, even if im module can only pass a coordinate relative to the application window to fcitx, which make the coordinate position doesn't make much sense, if your application window size is "maximized", the coordinate may just be "right" if treated as the global coordinate. This makes X11 window a better option than a randomly placed wayland window.

=== KDE Plasma ===
Best setup:
* KDE Plasma 5.27
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Start fcitx5 by go to "System settings" -> "Virtual keyboard" -> Select Fcitx 5
** Do not set <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> & <code>SDL_IM_MODULE</code> . You could unset <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> by runing <code>im-config</code> and then selecting <code>do not set any IM from im-config and use desktop default"</code>
** Run chromium/electron application with <code>--enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime</code>
* Caveats:
** Certain Gtk/Qt application that only works under X11 may still need to set <code>GTK_IM_MODULE</code> or <code>QT_IM_MODULE</code> for them individually.
** If you set <code>GTK_IM_MODULE/QT_IM_MODULE</code> globally, you will hit this issue [[Special:MyLanguage/FAQ#Candidate_window_is_blinking_under_wayland_with_Fcitx_5|Candidate window is blinking under wayland with Fcitx 5]]

Support Information:
* App/Compositor supports text-input-v2 and text-input-v3.
* Comopositor/Application uses zwp_input_method_v1.
* 5.27 additionally supports text-input-v1.
* 5.24 usable zwp_input_method_v1 with fcitx5. Pre-5.24 there are lots of problems, always use fcitx im module instead.
* Use "Virtual keyboard" KCM to launch fcitx5. This is required to use text-input protocol. If you launch fcitx this way, make sure you do not use "restart" in the tray menu, since the socket passed from KWin can not be reused with the newly restarted fcitx.

=== GNOME ===
Best setup:
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Set <code>QT_IM_MODULE=fcitx</code> for Qt, since Qt5 would use XWayland by default.
** Run chrome with XWayland and <code>GTK_IM_MODULE=fcitx</code>

Support information:
* Application/Compositor uses text-input-v3
* Compositor/Input Method uses ibus dbus protocol, so ibus frontend is required to be used.
* Adding Fcitx 5 to autostart, it will replace any existing ibus-daemon upon start up so it will work out of box.
* Popup candidate window is not able to be displayed over gnome-shell UI. Only solution is to use [[Special:MyLanguage/Kimpanel|Kimpanel]], [https://extensions.gnome.org/extension/261/kimpanel/ link to extension].
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Sway ===
* Application/Compositor uses text-input-v3
* Comopositor/Application uses zwp_input_method_v2, but it's partially implemented. You will need [https://github.com/swaywm/sway/pull/7226 this pull request] to make it show the popup candidate window for text-input-v3 client.
* fcitx im module also works.
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Weston ===
* Application/Compositor uses text-input-v1
* Comopositor/Application uses zwp_input_method_v1.
* Since it has no text-input-v3, which is more commonly used, im module is the only solution for Gtk/Qt, need to set GTK_IM_MODULE=fcitx and QT_IM_MODULE=fcitx.
* Add following content to ~/.config/weston.ini to make it launch fcitx 5. (xwayland part is recommended to make fcitx work best, even if it's wayland)

<pre>
[core]
xwayland=true

[input-method]
path=/usr/bin/fcitx5
</pre>

=== Other compositors ===
Please check their upstream for more information. For wlroots based compositors, it is possible that they also support in the same way as Sway does, or zwp_input_method could also be unsupported.

== Known Issues ==
=== Fcitx managed XKB layout ===
Unlike X11, there is no generic way to set XKB layout to compositor, which means it can only be implemented for every individual desktop. Right now, Fcitx managed layout only works for KDE Plasma and GNOME.

As for other desktop, in order to make this "semi" work you'll need to ensure following:

* The XKB layout of the input method group should be the same as the actual xkb layout you configured for the compositor. Fcitx will "think" the layout is the same and bypass the key conversion logic.
* If you need other layout for text typing (e.g. Arabic), just add them to the Fcitx. As long as the key is forwarded to fcitx, it should work.

=== Popup candidate window ===
Wayland does not have a global coordinate system for regular client, so for native wayland client, it is impossible for Fcitx to place a wayland surface at a certain position. In order for popup window to be placed at the correct position, there are following cases:
* Xwayland have no problem and it should work as good as X11.
* If zwp_input_method protocol can be used, it has a surface role to allow compositor to place the popup window for input method. This only works if client uses text-input protocol.
* For GNOME, kimpanel extension can read window coordinate since it's running inside compositor. As long as im module can report relative coordinate, kimpanel extension can display the popup window at the correct position. As similar approach for Plasma kimpanel is planned, but not yet implemented.
* For Gtk/Qt, fcitx's im module implement a way to render the popup with in the client process. This has some limitation because implemenation of xdg_popup in Gtk3/Qt5 doesn't support reposition the window. So show/hide trick is used to mitigate this, but it may cause window blinking. Fcitx tries not to move window if possible. You may also disable popup animation if you're using KWin to help reduce the blinking.

=== Per-window input method state ===
When zwp_input_method is used, essentially there is only one input context visible to fcitx, and fcitx cannot distinguish what application is being used. Which means the input method "active"/"inactivate" state is now "global".

Now fcitx supports two protocol to figure out the focused window and the corresponding application name, including wlr-foreign-toplevel-management (used by wlroots based compositor) and plasma-window-management (used by kwin).

Using Fcitx 5 on Wayland

2024-04-07T05:03:57Z

Weng Xuetian: /* GTK_IM_MODULE */

[https://wayland.freedesktop.org/ Wayland] is the next generation of display server protocol. While the initial release of the protocol is in 2008, the support of input method is not really ideal.

Also, using input method on Wayland-based compositor may require different setup to make it work, and certain features of fcitx that works under X11 are not yet supported by Wayland.

This page will try to cover all the current information with some underlying details, and [[Special:MyLanguage/Setup Fcitx 5|Setup Fcitx 5]] is still generally useful.

== Applications ==
=== TL;DR Do we still need XMODIFIERS, GTK_IM_MODULE and QT_IM_MODULE? ===

==== XMODIFIERS ====
For XMODIFIERS, yes, we do. X11 application running under X11 and XWayland has nearly no difference.

==== GTK_IM_MODULE ====
In an ideal setup, you should use fcitx im module Gtk application running under X11, and Gtk's text-input-v3 for wayland. The way of doing this is:

1. Do NOT set GTK_IM_MODULE environment variable.

2. For Gtk2, Add following content to ~/.gtkrc-2.0

<nowiki>gtk-im-module="fcitx"</nowiki>
3. For Gtk 3, add following content to ~/.config/gtk-3.0/settings.ini

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

4. For Gtk 4, add following content to ~/.config/gtk-4.0/settings.ini

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

5. If you are using GNOME 3+, also run following command.

<nowiki>gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/IMModule':<'fcitx'>}"</nowiki>

For GTK_IM_MODULE, as for now, the modern Gtk 3/4 application should be able to use text-input-v3 which is supported almost by every compositor, except weston. There are a few different options in terms of setting the value of GTK_IM_MODULE. When it is unset, the Gtk built-in Wayland im module will be used for Gtk3 and Gtk4. While you can also enforce it by doing GTK_IM_MODULE=wayland, remember it will be also picked up by Gtk2. Setting GTK_IM_MODULE=fcitx can still work, and it is necessary if your compositor does not support Wayland input method frontend.

It is possible to force a certain im module with Gtk configuration file, so without GTK_IM_MODULE set, it will still be able to use different im module.

Per Gtk implementation (still valid for 3.24.41), this line is ignored on wayland if text input is available in compositor. This makes it an ideal option for setting gtk im module to force fcitx im module for X11 while using text-input for wayland.

==== QT_IM_MODULE ====
For QT_IM_MODULE, as for now QT can only use its own text-input-v{2,4}, which is only supported by KWin. Which means, under KDE you should unset it, but under other desktop, you will need to set it to QT_IM_MODULE=fcitx. Also the proprietary Qt applications in the wild complicates the situation. Some do not work on Wayland, some do not bundle/provide Qt wayland. Most of them do not bundle fcitx im module because fcitx is only a third party application to Qt, but I also noticed some do bundle but not bundle all the required libraries. While fcitx 5 support ibus protocol, some of those applications do not even bundle ibus im module. There are a few different environment variables you can try for those proprietary Qt applications (WPS, Anki, DaVinci Resolve, Mathematica, etc...).

<nowiki>QT_IM_MODULE=fcitx # For those who bundle qt im module, e.g. WPS, Anki, you should find a .so file with fcitx in the file name
QT_IM_MODULE=ibus # For those who bundle ibus im module shipped with Qt, you should find libibusplatforminputcontextplugin.so in the package.
QT_QPA_PLATFORM=xcb QT_IM_MODULE=ibus # Enforce it to run on X11/XWayland and use ibus im module
</nowiki>

In Qt 6.7, there is a new environment variable called "QT_IM_MODULES", which allows you so specify a fallback order on im modules. You can set it to

<nowiki>QT_IM_MODULES="wayland;fcitx;ibus"</nowiki>

So it will be able pick up the most usable one even for application that bundles no fcitx/wayland. Remember, you may still need to set( or unset) QT_IM_MODULE (not "QT_IM_MODULES") in order to handle Qt 4/5 applications.

=== Legacy X11 application that runs under XWayland ===
In a word, XWayland support for input method is as good as normal X11 display server. As long as you set the same environment variable, using Xwayland should not be a issue. This category includes:

* Xlib-based (and also other toolkit based on Xlib, e.g. tk, SDL1, etc), e.g. xterm, rxvt. Make sure XMODIFIERS is set correctly.
* Gtk2-based applications, similar to Xlib, but can use fcitx im module. Set GTK_IM_MODULE to fcitx will give it best experience.
* SDL2-based applications that doesn't default to wayland. Set SDL_IM_MODULE to fcitx
* electron, chromium, these are still default to X11, similar to Gtk2 case.
* For Qt4 applcation, Qt 4 can only use X11. You will need to QT_IM_MODULE to fcitx. Same for Qt5+ that uses XCB (can be override with QT_QPA_PLATFORM=xcb).

=== Gtk3 / Gtk4 ===
Gtk3 and Gtk4 support text-input-v3 natively. At the same time, it's also possible to use fcitx im module under wayland. So, either GTK_IM_MODULE=wayland or GTK_IM_MODULE=fcitx works. There are some difference to it. text-input-v3

=== Qt5 / Qt6 ===
If your Qt application natively runs under Wayland, you can either unset QT_IM_MODULE to make it use text-input-v2, or set QT_IM_MODULE=fcitx to make it use fcitx im module.

text-input-v2 is not upstreamed to wayland-protocols, that is probably why only kwin support it. This means in non-kwin environment, you will need to use QT_IM_MODULE=fcitx to make the Qt applications work.

On Qt6, you may also use QT_IM_MODULE= (empty) or QT_IM_MODULE=wayland if your Qt vesion contains this https://codereview.qt-project.org/c/qt/qtwayland/+/416862.

=== Native wayland application (winit) ===
Most likely text-input-v3 is being used.

=== Chromium / Electron ===
{{warning|The information in this section may not be up to date to reflect upstream change, especially the default behavior when no option is changed.}}
TL;DR version, if you use XWayland to run Chromium or Electron application, just install Gtk im module and GTK_IM_MODULE=fcitx the same way like X11.

If you choose to run it natively under Wayland, for chromium you will need to use

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

Or

# You will get wrong position for the input method popup window, unless you use GNOME shell + kimpanel extension.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4

For electron, only the first option is avaiable (electron does NOT support to run internal chromium with gtk4), e.g. for vscode

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
code --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

By default it should run under Xwayland (As of 2023/02/25 on Archlinux/Chromium 110.0.5481.177), but some user also reports it is using wayland even the "Preferred Ozone Platform" is "Default". So to check whether it's really run with wayland, you can use xeyes or xwininfo. With xeyes, if it's an X11 window, the "eyes" will move with mouse, otherwise it's wayland. With xwininfo, if the mouse cursor changed to "+" shape, and click the window shows the window information, then it is a X11 window.

You may force it to run with Wayland, or X11 with the flag <code>--ozone-platform=wayland</code> and <code>--ozone-platform=x11</code>. You may persistent this by changing the option "Preferred Ozone Platform" in chrome://flags. It has four values, "Default", "X11", "Wayland", "Auto".

It's possible to make it use GTK_IM_MODULE if it runs with Gtk4 (only supported by chromium/chrome at this time, not electron) by passing <code>--gtk-version=4</code>.

It's also possible to make it use text-input-v1 by passing <code>--enable-wayland-ime</code> in addition to the flag above.

The Chromium support for text-input-v1 is not very stable and you may hit some random crash. E.g. in the past, version 112 has a crash bug: https://bugs.chromium.org/p/chromium/issues/detail?id=1431532 , which is fixed in version 115. In the bug comment, Chromium developer claims this text-input-v1 is only supposed to be used internally and not well supported, so use this at your own risk though it's currently the only out of box option.

You should only use one of <code>--enable-wayland-ime</code> or <code>--gtk-version=4</code>, depending on you want to use text-input-v1, or gtk4 im module. text-input-v1 works for kwin 5.27 and weston. Gtk4 im module works on all environment, but only GNOME with Kimpanel extension can display the popup window in the correct position.

== Support in Wayland Compositor ==

Even if you are using only native wayland applications, Xwayland is recommended to be enabled for following reason. If client side input panel in im module does not work, fcitx will fallback to a X11 window, instead of a wayland window. The reason for this is because wayland window can not be placed freely on the screen. On the contrary, even if im module can only pass a coordinate relative to the application window to fcitx, which make the coordinate position doesn't make much sense, if your application window size is "maximized", the coordinate may just be "right" if treated as the global coordinate. This makes X11 window a better option than a randomly placed wayland window.

=== KDE Plasma ===
Best setup:
* KDE Plasma 5.27
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Start fcitx5 by go to "System settings" -> "Virtual keyboard" -> Select Fcitx 5
** Do not set <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> & <code>SDL_IM_MODULE</code> . You could unset <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> by runing <code>im-config</code> and then selecting <code>do not set any IM from im-config and use desktop default"</code>
** Run chromium/electron application with <code>--enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime</code>
* Caveats:
** Certain Gtk/Qt application that only works under X11 may still need to set <code>GTK_IM_MODULE</code> or <code>QT_IM_MODULE</code> for them individually.
** If you set <code>GTK_IM_MODULE/QT_IM_MODULE</code> globally, you will hit this issue [[Special:MyLanguage/FAQ#Candidate_window_is_blinking_under_wayland_with_Fcitx_5|Candidate window is blinking under wayland with Fcitx 5]]

Support Information:
* App/Compositor supports text-input-v2 and text-input-v3.
* Comopositor/Application uses zwp_input_method_v1.
* 5.27 additionally supports text-input-v1.
* 5.24 usable zwp_input_method_v1 with fcitx5. Pre-5.24 there are lots of problems, always use fcitx im module instead.
* Use "Virtual keyboard" KCM to launch fcitx5. This is required to use text-input protocol. If you launch fcitx this way, make sure you do not use "restart" in the tray menu, since the socket passed from KWin can not be reused with the newly restarted fcitx.

=== GNOME ===
Best setup:
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Set <code>QT_IM_MODULE=fcitx</code> for Qt, since Qt5 would use XWayland by default.
** Run chrome with XWayland and <code>GTK_IM_MODULE=fcitx</code>

Support information:
* Application/Compositor uses text-input-v3
* Compositor/Input Method uses ibus dbus protocol, so ibus frontend is required to be used.
* Adding Fcitx 5 to autostart, it will replace any existing ibus-daemon upon start up so it will work out of box.
* Popup candidate window is not able to be displayed over gnome-shell UI. Only solution is to use [[Special:MyLanguage/Kimpanel|Kimpanel]], [https://extensions.gnome.org/extension/261/kimpanel/ link to extension].
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Sway ===
* Application/Compositor uses text-input-v3
* Comopositor/Application uses zwp_input_method_v2, but it's partially implemented. You will need [https://github.com/swaywm/sway/pull/7226 this pull request] to make it show the popup candidate window for text-input-v3 client.
* fcitx im module also works.
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Weston ===
* Application/Compositor uses text-input-v1
* Comopositor/Application uses zwp_input_method_v1.
* Since it has no text-input-v3, which is more commonly used, im module is the only solution for Gtk/Qt, need to set GTK_IM_MODULE=fcitx and QT_IM_MODULE=fcitx.
* Add following content to ~/.config/weston.ini to make it launch fcitx 5. (xwayland part is recommended to make fcitx work best, even if it's wayland)

<pre>
[core]
xwayland=true

[input-method]
path=/usr/bin/fcitx5
</pre>

=== Other compositors ===
Please check their upstream for more information. For wlroots based compositors, it is possible that they also support in the same way as Sway does, or zwp_input_method could also be unsupported.

== Known Issues ==
=== Fcitx managed XKB layout ===
Unlike X11, there is no generic way to set XKB layout to compositor, which means it can only be implemented for every individual desktop. Right now, Fcitx managed layout only works for KDE Plasma and GNOME.

As for other desktop, in order to make this "semi" work you'll need to ensure following:

* The XKB layout of the input method group should be the same as the actual xkb layout you configured for the compositor. Fcitx will "think" the layout is the same and bypass the key conversion logic.
* If you need other layout for text typing (e.g. Arabic), just add them to the Fcitx. As long as the key is forwarded to fcitx, it should work.

=== Popup candidate window ===
Wayland does not have a global coordinate system for regular client, so for native wayland client, it is impossible for Fcitx to place a wayland surface at a certain position. In order for popup window to be placed at the correct position, there are following cases:
* Xwayland have no problem and it should work as good as X11.
* If zwp_input_method protocol can be used, it has a surface role to allow compositor to place the popup window for input method. This only works if client uses text-input protocol.
* For GNOME, kimpanel extension can read window coordinate since it's running inside compositor. As long as im module can report relative coordinate, kimpanel extension can display the popup window at the correct position. As similar approach for Plasma kimpanel is planned, but not yet implemented.
* For Gtk/Qt, fcitx's im module implement a way to render the popup with in the client process. This has some limitation because implemenation of xdg_popup in Gtk3/Qt5 doesn't support reposition the window. So show/hide trick is used to mitigate this, but it may cause window blinking. Fcitx tries not to move window if possible. You may also disable popup animation if you're using KWin to help reduce the blinking.

=== Per-window input method state ===
When zwp_input_method is used, essentially there is only one input context visible to fcitx, and fcitx cannot distinguish what application is being used. Which means the input method "active"/"inactivate" state is now "global".

Now fcitx supports two protocol to figure out the focused window and the corresponding application name, including wlr-foreign-toplevel-management (used by wlroots based compositor) and plasma-window-management (used by kwin).

Using Fcitx 5 on Wayland

2024-04-07T04:53:37Z

Weng Xuetian: /* TL;DR Do we still need XMODIFIERS, GTK_IM_MODULE and QT_IM_MODULE? */

[https://wayland.freedesktop.org/ Wayland] is the next generation of display server protocol. While the initial release of the protocol is in 2008, the support of input method is not really ideal.

Also, using input method on Wayland-based compositor may require different setup to make it work, and certain features of fcitx that works under X11 are not yet supported by Wayland.

This page will try to cover all the current information with some underlying details, and [[Special:MyLanguage/Setup Fcitx 5|Setup Fcitx 5]] is still generally useful.

== Applications ==
=== TL;DR Do we still need XMODIFIERS, GTK_IM_MODULE and QT_IM_MODULE? ===

==== XMODIFIERS ====
For XMODIFIERS, yes, we do. X11 application running under X11 and XWayland has nearly no difference.

==== GTK_IM_MODULE ====
For GTK_IM_MODULE, as for now, the modern Gtk 3/4 application should be able to use text-input-v3 which is supported almost by every compositor, except weston. There are a few different options in terms of setting the value of GTK_IM_MODULE. When it is unset, the Gtk built-in Wayland im module will be used for Gtk3 and Gtk4. While you can also enforce it by doing GTK_IM_MODULE=wayland, remember it will be also picked up by Gtk2. Setting GTK_IM_MODULE=fcitx can still work, and it is necessary if your compositor does not support Wayland input method frontend.

It is possible to force a certain im module with Gtk configuration file, so without GTK_IM_MODULE set, it will still be able to use different im module. For Gtk 2, you can write

<nowiki>gtk-im-module="fcitx"</nowiki>

in <code>~/.gtkrc-2.0</code>. For Gtk3, you can have gtk-im-module under "Settings" section in ~/.config/gtk-3.0/settings.ini

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

Per Gtk implementation (still valid for 3.24.41), this line is ignored on wayland if text input is available in compositor. This makes it an ideal option for setting gtk im module to force fcitx im module for X11 while using text-input for wayland.

==== QT_IM_MODULE ====
For QT_IM_MODULE, as for now QT can only use its own text-input-v{2,4}, which is only supported by KWin. Which means, under KDE you should unset it, but under other desktop, you will need to set it to QT_IM_MODULE=fcitx. Also the proprietary Qt applications in the wild complicates the situation. Some do not work on Wayland, some do not bundle/provide Qt wayland. Most of them do not bundle fcitx im module because fcitx is only a third party application to Qt, but I also noticed some do bundle but not bundle all the required libraries. While fcitx 5 support ibus protocol, some of those applications do not even bundle ibus im module. There are a few different environment variables you can try for those proprietary Qt applications (WPS, Anki, DaVinci Resolve, Mathematica, etc...).

<nowiki>QT_IM_MODULE=fcitx # For those who bundle qt im module, e.g. WPS, Anki, you should find a .so file with fcitx in the file name
QT_IM_MODULE=ibus # For those who bundle ibus im module shipped with Qt, you should find libibusplatforminputcontextplugin.so in the package.
QT_QPA_PLATFORM=xcb QT_IM_MODULE=ibus # Enforce it to run on X11/XWayland and use ibus im module
</nowiki>

In Qt 6.7, there is a new environment variable called "QT_IM_MODULES", which allows you so specify a fallback order on im modules. You can set it to

<nowiki>QT_IM_MODULES="wayland;fcitx;ibus"</nowiki>

So it will be able pick up the most usable one even for application that bundles no fcitx/wayland. Remember, you may still need to set( or unset) QT_IM_MODULE (not "QT_IM_MODULES") in order to handle Qt 4/5 applications.

=== Legacy X11 application that runs under XWayland ===
In a word, XWayland support for input method is as good as normal X11 display server. As long as you set the same environment variable, using Xwayland should not be a issue. This category includes:

* Xlib-based (and also other toolkit based on Xlib, e.g. tk, SDL1, etc), e.g. xterm, rxvt. Make sure XMODIFIERS is set correctly.
* Gtk2-based applications, similar to Xlib, but can use fcitx im module. Set GTK_IM_MODULE to fcitx will give it best experience.
* SDL2-based applications that doesn't default to wayland. Set SDL_IM_MODULE to fcitx
* electron, chromium, these are still default to X11, similar to Gtk2 case.
* For Qt4 applcation, Qt 4 can only use X11. You will need to QT_IM_MODULE to fcitx. Same for Qt5+ that uses XCB (can be override with QT_QPA_PLATFORM=xcb).

=== Gtk3 / Gtk4 ===
Gtk3 and Gtk4 support text-input-v3 natively. At the same time, it's also possible to use fcitx im module under wayland. So, either GTK_IM_MODULE=wayland or GTK_IM_MODULE=fcitx works. There are some difference to it. text-input-v3

=== Qt5 / Qt6 ===
If your Qt application natively runs under Wayland, you can either unset QT_IM_MODULE to make it use text-input-v2, or set QT_IM_MODULE=fcitx to make it use fcitx im module.

text-input-v2 is not upstreamed to wayland-protocols, that is probably why only kwin support it. This means in non-kwin environment, you will need to use QT_IM_MODULE=fcitx to make the Qt applications work.

On Qt6, you may also use QT_IM_MODULE= (empty) or QT_IM_MODULE=wayland if your Qt vesion contains this https://codereview.qt-project.org/c/qt/qtwayland/+/416862.

=== Native wayland application (winit) ===
Most likely text-input-v3 is being used.

=== Chromium / Electron ===
{{warning|The information in this section may not be up to date to reflect upstream change, especially the default behavior when no option is changed.}}
TL;DR version, if you use XWayland to run Chromium or Electron application, just install Gtk im module and GTK_IM_MODULE=fcitx the same way like X11.

If you choose to run it natively under Wayland, for chromium you will need to use

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

Or

# You will get wrong position for the input method popup window, unless you use GNOME shell + kimpanel extension.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4

For electron, only the first option is avaiable (electron does NOT support to run internal chromium with gtk4), e.g. for vscode

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
code --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

By default it should run under Xwayland (As of 2023/02/25 on Archlinux/Chromium 110.0.5481.177), but some user also reports it is using wayland even the "Preferred Ozone Platform" is "Default". So to check whether it's really run with wayland, you can use xeyes or xwininfo. With xeyes, if it's an X11 window, the "eyes" will move with mouse, otherwise it's wayland. With xwininfo, if the mouse cursor changed to "+" shape, and click the window shows the window information, then it is a X11 window.

You may force it to run with Wayland, or X11 with the flag <code>--ozone-platform=wayland</code> and <code>--ozone-platform=x11</code>. You may persistent this by changing the option "Preferred Ozone Platform" in chrome://flags. It has four values, "Default", "X11", "Wayland", "Auto".

It's possible to make it use GTK_IM_MODULE if it runs with Gtk4 (only supported by chromium/chrome at this time, not electron) by passing <code>--gtk-version=4</code>.

It's also possible to make it use text-input-v1 by passing <code>--enable-wayland-ime</code> in addition to the flag above.

The Chromium support for text-input-v1 is not very stable and you may hit some random crash. E.g. in the past, version 112 has a crash bug: https://bugs.chromium.org/p/chromium/issues/detail?id=1431532 , which is fixed in version 115. In the bug comment, Chromium developer claims this text-input-v1 is only supposed to be used internally and not well supported, so use this at your own risk though it's currently the only out of box option.

You should only use one of <code>--enable-wayland-ime</code> or <code>--gtk-version=4</code>, depending on you want to use text-input-v1, or gtk4 im module. text-input-v1 works for kwin 5.27 and weston. Gtk4 im module works on all environment, but only GNOME with Kimpanel extension can display the popup window in the correct position.

== Support in Wayland Compositor ==

Even if you are using only native wayland applications, Xwayland is recommended to be enabled for following reason. If client side input panel in im module does not work, fcitx will fallback to a X11 window, instead of a wayland window. The reason for this is because wayland window can not be placed freely on the screen. On the contrary, even if im module can only pass a coordinate relative to the application window to fcitx, which make the coordinate position doesn't make much sense, if your application window size is "maximized", the coordinate may just be "right" if treated as the global coordinate. This makes X11 window a better option than a randomly placed wayland window.

=== KDE Plasma ===
Best setup:
* KDE Plasma 5.27
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Start fcitx5 by go to "System settings" -> "Virtual keyboard" -> Select Fcitx 5
** Do not set <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> & <code>SDL_IM_MODULE</code> . You could unset <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> by runing <code>im-config</code> and then selecting <code>do not set any IM from im-config and use desktop default"</code>
** Run chromium/electron application with <code>--enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime</code>
* Caveats:
** Certain Gtk/Qt application that only works under X11 may still need to set <code>GTK_IM_MODULE</code> or <code>QT_IM_MODULE</code> for them individually.
** If you set <code>GTK_IM_MODULE/QT_IM_MODULE</code> globally, you will hit this issue [[Special:MyLanguage/FAQ#Candidate_window_is_blinking_under_wayland_with_Fcitx_5|Candidate window is blinking under wayland with Fcitx 5]]

Support Information:
* App/Compositor supports text-input-v2 and text-input-v3.
* Comopositor/Application uses zwp_input_method_v1.
* 5.27 additionally supports text-input-v1.
* 5.24 usable zwp_input_method_v1 with fcitx5. Pre-5.24 there are lots of problems, always use fcitx im module instead.
* Use "Virtual keyboard" KCM to launch fcitx5. This is required to use text-input protocol. If you launch fcitx this way, make sure you do not use "restart" in the tray menu, since the socket passed from KWin can not be reused with the newly restarted fcitx.

=== GNOME ===
Best setup:
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Set <code>QT_IM_MODULE=fcitx</code> for Qt, since Qt5 would use XWayland by default.
** Run chrome with XWayland and <code>GTK_IM_MODULE=fcitx</code>

Support information:
* Application/Compositor uses text-input-v3
* Compositor/Input Method uses ibus dbus protocol, so ibus frontend is required to be used.
* Adding Fcitx 5 to autostart, it will replace any existing ibus-daemon upon start up so it will work out of box.
* Popup candidate window is not able to be displayed over gnome-shell UI. Only solution is to use [[Special:MyLanguage/Kimpanel|Kimpanel]], [https://extensions.gnome.org/extension/261/kimpanel/ link to extension].
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Sway ===
* Application/Compositor uses text-input-v3
* Comopositor/Application uses zwp_input_method_v2, but it's partially implemented. You will need [https://github.com/swaywm/sway/pull/7226 this pull request] to make it show the popup candidate window for text-input-v3 client.
* fcitx im module also works.
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Weston ===
* Application/Compositor uses text-input-v1
* Comopositor/Application uses zwp_input_method_v1.
* Since it has no text-input-v3, which is more commonly used, im module is the only solution for Gtk/Qt, need to set GTK_IM_MODULE=fcitx and QT_IM_MODULE=fcitx.
* Add following content to ~/.config/weston.ini to make it launch fcitx 5. (xwayland part is recommended to make fcitx work best, even if it's wayland)

<pre>
[core]
xwayland=true

[input-method]
path=/usr/bin/fcitx5
</pre>

=== Other compositors ===
Please check their upstream for more information. For wlroots based compositors, it is possible that they also support in the same way as Sway does, or zwp_input_method could also be unsupported.

== Known Issues ==
=== Fcitx managed XKB layout ===
Unlike X11, there is no generic way to set XKB layout to compositor, which means it can only be implemented for every individual desktop. Right now, Fcitx managed layout only works for KDE Plasma and GNOME.

As for other desktop, in order to make this "semi" work you'll need to ensure following:

* The XKB layout of the input method group should be the same as the actual xkb layout you configured for the compositor. Fcitx will "think" the layout is the same and bypass the key conversion logic.
* If you need other layout for text typing (e.g. Arabic), just add them to the Fcitx. As long as the key is forwarded to fcitx, it should work.

=== Popup candidate window ===
Wayland does not have a global coordinate system for regular client, so for native wayland client, it is impossible for Fcitx to place a wayland surface at a certain position. In order for popup window to be placed at the correct position, there are following cases:
* Xwayland have no problem and it should work as good as X11.
* If zwp_input_method protocol can be used, it has a surface role to allow compositor to place the popup window for input method. This only works if client uses text-input protocol.
* For GNOME, kimpanel extension can read window coordinate since it's running inside compositor. As long as im module can report relative coordinate, kimpanel extension can display the popup window at the correct position. As similar approach for Plasma kimpanel is planned, but not yet implemented.
* For Gtk/Qt, fcitx's im module implement a way to render the popup with in the client process. This has some limitation because implemenation of xdg_popup in Gtk3/Qt5 doesn't support reposition the window. So show/hide trick is used to mitigate this, but it may cause window blinking. Fcitx tries not to move window if possible. You may also disable popup animation if you're using KWin to help reduce the blinking.

=== Per-window input method state ===
When zwp_input_method is used, essentially there is only one input context visible to fcitx, and fcitx cannot distinguish what application is being used. Which means the input method "active"/"inactivate" state is now "global".

Now fcitx supports two protocol to figure out the focused window and the corresponding application name, including wlr-foreign-toplevel-management (used by wlroots based compositor) and plasma-window-management (used by kwin).

Tips and Tricks

2024-04-04T22:05:40Z

Weng Xuetian: Created page with "This page is mainly focusing on some not well known feature that Fcitx 5 provides. If you need help on how to setup, please check Special:MyLanguage/Setup Fcitx 5|Setup Fci..."

This page is mainly focusing on some not well known feature that Fcitx 5 provides.

If you need help on how to setup, please check [[Special:MyLanguage/Setup Fcitx 5|Setup Fcitx 5]] instead.

= Type special characters =
== Quick phrase ==
Quick phrase is a built-in addon that allows you to type something to search and match the text that usually requires more effort to type.

It can be triggered globally with default hotkey <code>Meta + `</code>.

It has some a few built-in tables, which can be browsed on [https://github.com/fcitx/fcitx5/tree/master/src/modules/quickphrase/quickphrase.d Github], or locally with the quickphrase editor GUI (launched from quickphrase setting in Configtool).

The built in tables contain:
1. Latex, which allows you type math/other symbol in latex syntax. For example "\alpha" will produce "α".
2. Emoji Ascii Code, which allows you type Unicode emoji character leading with ":", which you commonly see in instant messaging software. For example, ":smile:" will produce 😄.
3. Emoji, which contains a list of "Kaomoji-like" phrase, e.g. "smile" for "(・∀・)".

Quick phrase can also be extended with Lua or C++.

== Type with Unicode ==
Fcitx 5 also provides a Unicode addon, that allows you to type Unicode with hex number, or search with description.

<code>Ctrl + Shift + U</code> gives you a similar experience like Gtk's built-in Unicode feature, that you just simply type the Hex number and press space. E.g. type
<code>Ctrl + Shift + U, 2, 6, 3, a, space</code> will give you the Unicode character ☺.

Or with <code>Ctrl + Shift + Alt + U</code>, you will be able to search with description. If you just press <code>Ctrl + Shift + Alt + U</code>, it will show you the Unicode of string in your clipboard and current selection.

If you want to search with description, you just simply type the description, for example, you can search eggplant for Unicode character 🍆.

== Type with compose ==
This is the old-school X11 feature, but also works anywhere that Fcitx supports. You can find some description of the file syntax at [https://xkbcommon.org/doc/current/group__compose.html xkbcommon documentation].

It allows you to convert a sequence of key press to any string. But be aware this feature is global that you can't easily disable it.

== Use long press in keyboard engine ==
When long press option is enabled in keyboard engine, you can get a list of candidate text that's mapping to the key you pressed. The mapping is fully customizable and allows you to disable it in certain applications.

== Type Emoji ==
If you are using layout engine (input method named as "Keyboard - Layout name"), you can use quick phrase to search Unicode CLDR annotation. E.g. using "Keyboard - English (US)" allows you to search apple for 🍎 & 🍏. The language that can be used for searching is associated with layout language.

You can also use other methods like Quick phrase built-in table method, or with Unicode addon, or compose that are described above.

Fcitx 5

2024-04-04T21:37:58Z

Weng Xuetian:

<languages/>
<translate>


Fcitx [ˈfaɪtɪks] is an input method framework with extension support. Currently it supports Linux and Unix systems like freebsd. Fcitx supports typing with many languages all over the world with a large number of engines.


Fcitx has a slim core while provides powerful features with addons. It is easy to customize fcitx to satisfy your own needs.


[[Special:myLanguage/Fcitx|Looking for Old Wiki Page for Fcitx 4?]]

==== For Users ==== 


* [[Special:myLanguage/Install Fcitx 5|Install Fcitx 5]]
* [[Special:myLanguage/Setup Fcitx 5|Setup Fcitx 5]]
* Install [[Special:myLanguage/Input method engines|Input method engines]]
* [[Special:myLanguage/Theme Customization|Theme Customization]]
* [[Special:myLanguage/FAQ|FAQ]]
* [[Special:myLanguage/Using Fcitx 5 on Wayland|Using Fcitx 5 on Wayland]]
* [[Special:myLanguage/Tips and Tricks|Tips and Tricks]]
* [[Special:myLanguage/Upgrade from Fcitx 4|Upgrade from Fcitx 4]]

==== For Developers ==== 


* [[Special:myLanguage/Compiling fcitx5|Compiling fcitx5]]
* [[Special:myLanguage/Basic concept|Basic concept]]
* [[Special:myLanguage/Develop an simple input method|Develop an simple input method]]
* [[Special:myLanguage/Q&A for developer|Q&A for developer]]
* [[Special:myLanguage/Debug fcitx5|Debug fcitx5]]

==== News ==== 


<rss max=5>https://politepol.com/fd/hhM5BOjZLblk</rss>

== Help Fcitx == 
* Recommend Fcitx to your friend
* [[Special:myLanguage/Report Bug|Report Bug]]
* [[Special:myLanguage/Contribute to this Wiki|Contribute to this Wiki]] ('''Please read this before you request account''')
* [[Special:myLanguage/Donate|Donate]]

== About Fcitx == 
* [[Special:myLanguage/History|History]]

</translate>

Using Fcitx 5 on Wayland

2024-03-28T10:59:48Z

Weng Xuetian: /* TL;DR Do we still need XMODIFIERS, GTK_IM_MODULE and QT_IM_MODULE? */

[https://wayland.freedesktop.org/ Wayland] is the next generation of display server protocol. While the initial release of the protocol is in 2008, the support of input method is not really ideal.

Also, using input method on Wayland-based compositor may require different setup to make it work, and certain features of fcitx that works under X11 are not yet supported by Wayland.

This page will try to cover all the current information with some underlying details, and [[Special:MyLanguage/Setup Fcitx 5|Setup Fcitx 5]] is still generally useful.

== Applications ==
=== TL;DR Do we still need XMODIFIERS, GTK_IM_MODULE and QT_IM_MODULE? ===
For XMODIFIERS, yes, we do. X11 application running under X11 and XWayland has nearly no difference.

For GTK_IM_MODULE, as for now, the modern Gtk 3/4 application should be able to use text-input-v3 which is supported almost by every compositor, except weston. There are a few different options in terms of setting the value of GTK_IM_MODULE. When it is unset, the Gtk built-in Wayland im module will be used for Gtk3 and Gtk4. While you can also enforce it by doing GTK_IM_MODULE=wayland, remember it will be also picked up by Gtk2. Setting GTK_IM_MODULE=fcitx can still work, and it is necessary if your compositor does not support Wayland input method frontend.

It is possible to force a certain im module with Gtk configuration file, so without GTK_IM_MODULE set, it will still be able to use different im module. For Gtk 2, you can write

<nowiki>gtk-im-module="fcitx"</nowiki>

in <code>~/.gtkrc-2.0</code>. For Gtk3, you can have gtk-im-module under "Settings" section in ~/.config/gtk-3.0/settings.ini

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

Per Gtk implementation (still valid for 3.24.41), this line is ignored on wayland if text input is available in compositor. This makes it an ideal option for setting gtk im module to force fcitx im module for X11 while using text-input for wayland.

For QT_IM_MODULE, as for now QT can only use its own text-input-v{2,4}, which is only supported by KWin. Which means, under KDE you should unset it, but under other desktop, you will need to set it to QT_IM_MODULE=fcitx. Also the proprietary Qt applications in the wild complicates the situation. Some do not work on Wayland, some do not bundle/provide Qt wayland. Most of them do not bundle fcitx im module because fcitx is only a third party application to Qt, but I also noticed some do bundle but not bundle all the required libraries. While fcitx 5 support ibus protocol, some of those applications do not even bundle ibus im module. There are a few different environment variables you can try for those proprietary Qt applications (WPS, Anki, DaVinci Resolve, Mathematica, etc...).

<nowiki>QT_IM_MODULE=fcitx # For those who bundle qt im module, e.g. WPS, Anki, you should find a .so file with fcitx in the file name
QT_IM_MODULE=ibus # For those who bundle ibus im module shipped with Qt, you should find libibusplatforminputcontextplugin.so in the package.
QT_QPA_PLATFORM=xcb QT_IM_MODULE=ibus # Enforce it to run on X11/XWayland and use ibus im module
</nowiki>

=== Legacy X11 application that runs under XWayland ===
In a word, XWayland support for input method is as good as normal X11 display server. As long as you set the same environment variable, using Xwayland should not be a issue. This category includes:

* Xlib-based (and also other toolkit based on Xlib, e.g. tk, SDL1, etc), e.g. xterm, rxvt. Make sure XMODIFIERS is set correctly.
* Gtk2-based applications, similar to Xlib, but can use fcitx im module. Set GTK_IM_MODULE to fcitx will give it best experience.
* SDL2-based applications that doesn't default to wayland. Set SDL_IM_MODULE to fcitx
* electron, chromium, these are still default to X11, similar to Gtk2 case.
* For Qt4 applcation, Qt 4 can only use X11. You will need to QT_IM_MODULE to fcitx. Same for Qt5+ that uses XCB (can be override with QT_QPA_PLATFORM=xcb).

=== Gtk3 / Gtk4 ===
Gtk3 and Gtk4 support text-input-v3 natively. At the same time, it's also possible to use fcitx im module under wayland. So, either GTK_IM_MODULE=wayland or GTK_IM_MODULE=fcitx works. There are some difference to it. text-input-v3

=== Qt5 / Qt6 ===
If your Qt application natively runs under Wayland, you can either unset QT_IM_MODULE to make it use text-input-v2, or set QT_IM_MODULE=fcitx to make it use fcitx im module.

text-input-v2 is not upstreamed to wayland-protocols, that is probably why only kwin support it. This means in non-kwin environment, you will need to use QT_IM_MODULE=fcitx to make the Qt applications work.

On Qt6, you may also use QT_IM_MODULE= (empty) or QT_IM_MODULE=wayland if your Qt vesion contains this https://codereview.qt-project.org/c/qt/qtwayland/+/416862.

=== Native wayland application (winit) ===
Most likely text-input-v3 is being used.

=== Chromium / Electron ===
{{warning|The information in this section may not be up to date to reflect upstream change, especially the default behavior when no option is changed.}}
TL;DR version, if you use XWayland to run Chromium or Electron application, just install Gtk im module and GTK_IM_MODULE=fcitx the same way like X11.

If you choose to run it natively under Wayland, for chromium you will need to use

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

Or

# You will get wrong position for the input method popup window, unless you use GNOME shell + kimpanel extension.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4

For electron, only the first option is avaiable (electron does NOT support to run internal chromium with gtk4), e.g. for vscode

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
code --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

By default it should run under Xwayland (As of 2023/02/25 on Archlinux/Chromium 110.0.5481.177), but some user also reports it is using wayland even the "Preferred Ozone Platform" is "Default". So to check whether it's really run with wayland, you can use xeyes or xwininfo. With xeyes, if it's an X11 window, the "eyes" will move with mouse, otherwise it's wayland. With xwininfo, if the mouse cursor changed to "+" shape, and click the window shows the window information, then it is a X11 window.

You may force it to run with Wayland, or X11 with the flag <code>--ozone-platform=wayland</code> and <code>--ozone-platform=x11</code>. You may persistent this by changing the option "Preferred Ozone Platform" in chrome://flags. It has four values, "Default", "X11", "Wayland", "Auto".

It's possible to make it use GTK_IM_MODULE if it runs with Gtk4 (only supported by chromium/chrome at this time, not electron) by passing <code>--gtk-version=4</code>.

It's also possible to make it use text-input-v1 by passing <code>--enable-wayland-ime</code> in addition to the flag above.

The Chromium support for text-input-v1 is not very stable and you may hit some random crash. E.g. in the past, version 112 has a crash bug: https://bugs.chromium.org/p/chromium/issues/detail?id=1431532 , which is fixed in version 115. In the bug comment, Chromium developer claims this text-input-v1 is only supposed to be used internally and not well supported, so use this at your own risk though it's currently the only out of box option.

You should only use one of <code>--enable-wayland-ime</code> or <code>--gtk-version=4</code>, depending on you want to use text-input-v1, or gtk4 im module. text-input-v1 works for kwin 5.27 and weston. Gtk4 im module works on all environment, but only GNOME with Kimpanel extension can display the popup window in the correct position.

== Support in Wayland Compositor ==

Even if you are using only native wayland applications, Xwayland is recommended to be enabled for following reason. If client side input panel in im module does not work, fcitx will fallback to a X11 window, instead of a wayland window. The reason for this is because wayland window can not be placed freely on the screen. On the contrary, even if im module can only pass a coordinate relative to the application window to fcitx, which make the coordinate position doesn't make much sense, if your application window size is "maximized", the coordinate may just be "right" if treated as the global coordinate. This makes X11 window a better option than a randomly placed wayland window.

=== KDE Plasma ===
Best setup:
* KDE Plasma 5.27
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Start fcitx5 by go to "System settings" -> "Virtual keyboard" -> Select Fcitx 5
** Do not set <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> & <code>SDL_IM_MODULE</code> . You could unset <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> by runing <code>im-config</code> and then selecting <code>do not set any IM from im-config and use desktop default"</code>
** Run chromium/electron application with <code>--enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime</code>
* Caveats:
** Certain Gtk/Qt application that only works under X11 may still need to set <code>GTK_IM_MODULE</code> or <code>QT_IM_MODULE</code> for them individually.
** If you set <code>GTK_IM_MODULE/QT_IM_MODULE</code> globally, you will hit this issue [[Special:MyLanguage/FAQ#Candidate_window_is_blinking_under_wayland_with_Fcitx_5|Candidate window is blinking under wayland with Fcitx 5]]

Support Information:
* App/Compositor supports text-input-v2 and text-input-v3.
* Comopositor/Application uses zwp_input_method_v1.
* 5.27 additionally supports text-input-v1.
* 5.24 usable zwp_input_method_v1 with fcitx5. Pre-5.24 there are lots of problems, always use fcitx im module instead.
* Use "Virtual keyboard" KCM to launch fcitx5. This is required to use text-input protocol. If you launch fcitx this way, make sure you do not use "restart" in the tray menu, since the socket passed from KWin can not be reused with the newly restarted fcitx.

=== GNOME ===
Best setup:
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Set <code>QT_IM_MODULE=fcitx</code> for Qt, since Qt5 would use XWayland by default.
** Run chrome with XWayland and <code>GTK_IM_MODULE=fcitx</code>

Support information:
* Application/Compositor uses text-input-v3
* Compositor/Input Method uses ibus dbus protocol, so ibus frontend is required to be used.
* Adding Fcitx 5 to autostart, it will replace any existing ibus-daemon upon start up so it will work out of box.
* Popup candidate window is not able to be displayed over gnome-shell UI. Only solution is to use [[Special:MyLanguage/Kimpanel|Kimpanel]], [https://extensions.gnome.org/extension/261/kimpanel/ link to extension].
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Sway ===
* Application/Compositor uses text-input-v3
* Comopositor/Application uses zwp_input_method_v2, but it's partially implemented. You will need [https://github.com/swaywm/sway/pull/7226 this pull request] to make it show the popup candidate window for text-input-v3 client.
* fcitx im module also works.
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Weston ===
* Application/Compositor uses text-input-v1
* Comopositor/Application uses zwp_input_method_v1.
* Since it has no text-input-v3, which is more commonly used, im module is the only solution for Gtk/Qt, need to set GTK_IM_MODULE=fcitx and QT_IM_MODULE=fcitx.
* Add following content to ~/.config/weston.ini to make it launch fcitx 5. (xwayland part is recommended to make fcitx work best, even if it's wayland)

<pre>
[core]
xwayland=true

[input-method]
path=/usr/bin/fcitx5
</pre>

=== Other compositors ===
Please check their upstream for more information. For wlroots based compositors, it is possible that they also support in the same way as Sway does, or zwp_input_method could also be unsupported.

== Known Issues ==
=== Fcitx managed XKB layout ===
Unlike X11, there is no generic way to set XKB layout to compositor, which means it can only be implemented for every individual desktop. Right now, Fcitx managed layout only works for KDE Plasma and GNOME.

As for other desktop, in order to make this "semi" work you'll need to ensure following:

* The XKB layout of the input method group should be the same as the actual xkb layout you configured for the compositor. Fcitx will "think" the layout is the same and bypass the key conversion logic.
* If you need other layout for text typing (e.g. Arabic), just add them to the Fcitx. As long as the key is forwarded to fcitx, it should work.

=== Popup candidate window ===
Wayland does not have a global coordinate system for regular client, so for native wayland client, it is impossible for Fcitx to place a wayland surface at a certain position. In order for popup window to be placed at the correct position, there are following cases:
* Xwayland have no problem and it should work as good as X11.
* If zwp_input_method protocol can be used, it has a surface role to allow compositor to place the popup window for input method. This only works if client uses text-input protocol.
* For GNOME, kimpanel extension can read window coordinate since it's running inside compositor. As long as im module can report relative coordinate, kimpanel extension can display the popup window at the correct position. As similar approach for Plasma kimpanel is planned, but not yet implemented.
* For Gtk/Qt, fcitx's im module implement a way to render the popup with in the client process. This has some limitation because implemenation of xdg_popup in Gtk3/Qt5 doesn't support reposition the window. So show/hide trick is used to mitigate this, but it may cause window blinking. Fcitx tries not to move window if possible. You may also disable popup animation if you're using KWin to help reduce the blinking.

=== Per-window input method state ===
When zwp_input_method is used, essentially there is only one input context visible to fcitx, and fcitx cannot distinguish what application is being used. Which means the input method "active"/"inactivate" state is now "global".

Now fcitx supports two protocol to figure out the focused window and the corresponding application name, including wlr-foreign-toplevel-management (used by wlroots based compositor) and plasma-window-management (used by kwin).

Using Fcitx 5 on Wayland

2024-03-28T10:58:37Z

Weng Xuetian:

[https://wayland.freedesktop.org/ Wayland] is the next generation of display server protocol. While the initial release of the protocol is in 2008, the support of input method is not really ideal.

Also, using input method on Wayland-based compositor may require different setup to make it work, and certain features of fcitx that works under X11 are not yet supported by Wayland.

This page will try to cover all the current information with some underlying details, and [[Special:MyLanguage/Setup Fcitx 5|Setup Fcitx 5]] is still generally useful.

== Applications ==
=== TL;DR Do we still need XMODIFIERS, GTK_IM_MODULE and QT_IM_MODULE? ===
For XMODIFIERS, yes, we do. X11 application running under X11 and XWayland has nearly no difference.

For GTK_IM_MODULE, as for now, the modern Gtk 3/4 application should be able to use text-input-v3 which is supported almost by every compositor, except weston. There are a few different options in terms of setting the value of GTK_IM_MODULE. When it is unset, the Gtk built-in Wayland im module will be used for Gtk3 and Gtk4. While you can also enforce it by doing GTK_IM_MODULE=wayland, remember it will be also picked up by Gtk2. Setting GTK_IM_MODULE=fcitx can still work, and it is necessary if your compositor does not support Wayland input method frontend.

It is possible to force a certain im module with Gtk configuration file, so without GTK_IM_MODULE set, it will still be able to use different im module. For Gtk 2, you can write

<nowiki>gtk-im-module="fcitx"</nowiki>

in <code>~/.gtkrc-2.0</code>. For Gtk3, you can have gtk-im-module under "Settings" section in ~/.config/gtk-3.0/settings.ini

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

Per Gtk implementation (still valid for 3.24.41), this line is ignored on wayland if text input is available in compositor.

For QT_IM_MODULE, as for now QT can only use its own text-input-v{2,4}, which is only supported by KWin. Which means, under KDE you should unset it, but under other desktop, you will need to set it to QT_IM_MODULE=fcitx. Also the proprietary Qt applications in the wild complicates the situation. Some do not work on Wayland, some do not bundle/provide Qt wayland. Most of them do not bundle fcitx im module because fcitx is only a third party application to Qt, but I also noticed some do bundle but not bundle all the required libraries. While fcitx 5 support ibus protocol, some of those applications do not even bundle ibus im module. There are a few different environment variables you can try for those proprietary Qt applications (WPS, Anki, DaVinci Resolve, Mathematica, etc...).

<nowiki>QT_IM_MODULE=fcitx # For those who bundle qt im module, e.g. WPS, Anki, you should find a .so file with fcitx in the file name
QT_IM_MODULE=ibus # For those who bundle ibus im module shipped with Qt, you should find libibusplatforminputcontextplugin.so in the package.
QT_QPA_PLATFORM=xcb QT_IM_MODULE=ibus # Enforce it to run on X11/XWayland and use ibus im module
</nowiki>

=== Legacy X11 application that runs under XWayland ===
In a word, XWayland support for input method is as good as normal X11 display server. As long as you set the same environment variable, using Xwayland should not be a issue. This category includes:

* Xlib-based (and also other toolkit based on Xlib, e.g. tk, SDL1, etc), e.g. xterm, rxvt. Make sure XMODIFIERS is set correctly.
* Gtk2-based applications, similar to Xlib, but can use fcitx im module. Set GTK_IM_MODULE to fcitx will give it best experience.
* SDL2-based applications that doesn't default to wayland. Set SDL_IM_MODULE to fcitx
* electron, chromium, these are still default to X11, similar to Gtk2 case.
* For Qt4 applcation, Qt 4 can only use X11. You will need to QT_IM_MODULE to fcitx. Same for Qt5+ that uses XCB (can be override with QT_QPA_PLATFORM=xcb).

=== Gtk3 / Gtk4 ===
Gtk3 and Gtk4 support text-input-v3 natively. At the same time, it's also possible to use fcitx im module under wayland. So, either GTK_IM_MODULE=wayland or GTK_IM_MODULE=fcitx works. There are some difference to it. text-input-v3

=== Qt5 / Qt6 ===
If your Qt application natively runs under Wayland, you can either unset QT_IM_MODULE to make it use text-input-v2, or set QT_IM_MODULE=fcitx to make it use fcitx im module.

text-input-v2 is not upstreamed to wayland-protocols, that is probably why only kwin support it. This means in non-kwin environment, you will need to use QT_IM_MODULE=fcitx to make the Qt applications work.

On Qt6, you may also use QT_IM_MODULE= (empty) or QT_IM_MODULE=wayland if your Qt vesion contains this https://codereview.qt-project.org/c/qt/qtwayland/+/416862.

=== Native wayland application (winit) ===
Most likely text-input-v3 is being used.

=== Chromium / Electron ===
{{warning|The information in this section may not be up to date to reflect upstream change, especially the default behavior when no option is changed.}}
TL;DR version, if you use XWayland to run Chromium or Electron application, just install Gtk im module and GTK_IM_MODULE=fcitx the same way like X11.

If you choose to run it natively under Wayland, for chromium you will need to use

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

Or

# You will get wrong position for the input method popup window, unless you use GNOME shell + kimpanel extension.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4

For electron, only the first option is avaiable (electron does NOT support to run internal chromium with gtk4), e.g. for vscode

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
code --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

By default it should run under Xwayland (As of 2023/02/25 on Archlinux/Chromium 110.0.5481.177), but some user also reports it is using wayland even the "Preferred Ozone Platform" is "Default". So to check whether it's really run with wayland, you can use xeyes or xwininfo. With xeyes, if it's an X11 window, the "eyes" will move with mouse, otherwise it's wayland. With xwininfo, if the mouse cursor changed to "+" shape, and click the window shows the window information, then it is a X11 window.

You may force it to run with Wayland, or X11 with the flag <code>--ozone-platform=wayland</code> and <code>--ozone-platform=x11</code>. You may persistent this by changing the option "Preferred Ozone Platform" in chrome://flags. It has four values, "Default", "X11", "Wayland", "Auto".

It's possible to make it use GTK_IM_MODULE if it runs with Gtk4 (only supported by chromium/chrome at this time, not electron) by passing <code>--gtk-version=4</code>.

It's also possible to make it use text-input-v1 by passing <code>--enable-wayland-ime</code> in addition to the flag above.

The Chromium support for text-input-v1 is not very stable and you may hit some random crash. E.g. in the past, version 112 has a crash bug: https://bugs.chromium.org/p/chromium/issues/detail?id=1431532 , which is fixed in version 115. In the bug comment, Chromium developer claims this text-input-v1 is only supposed to be used internally and not well supported, so use this at your own risk though it's currently the only out of box option.

You should only use one of <code>--enable-wayland-ime</code> or <code>--gtk-version=4</code>, depending on you want to use text-input-v1, or gtk4 im module. text-input-v1 works for kwin 5.27 and weston. Gtk4 im module works on all environment, but only GNOME with Kimpanel extension can display the popup window in the correct position.

== Support in Wayland Compositor ==

Even if you are using only native wayland applications, Xwayland is recommended to be enabled for following reason. If client side input panel in im module does not work, fcitx will fallback to a X11 window, instead of a wayland window. The reason for this is because wayland window can not be placed freely on the screen. On the contrary, even if im module can only pass a coordinate relative to the application window to fcitx, which make the coordinate position doesn't make much sense, if your application window size is "maximized", the coordinate may just be "right" if treated as the global coordinate. This makes X11 window a better option than a randomly placed wayland window.

=== KDE Plasma ===
Best setup:
* KDE Plasma 5.27
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Start fcitx5 by go to "System settings" -> "Virtual keyboard" -> Select Fcitx 5
** Do not set <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> & <code>SDL_IM_MODULE</code> . You could unset <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> by runing <code>im-config</code> and then selecting <code>do not set any IM from im-config and use desktop default"</code>
** Run chromium/electron application with <code>--enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime</code>
* Caveats:
** Certain Gtk/Qt application that only works under X11 may still need to set <code>GTK_IM_MODULE</code> or <code>QT_IM_MODULE</code> for them individually.
** If you set <code>GTK_IM_MODULE/QT_IM_MODULE</code> globally, you will hit this issue [[Special:MyLanguage/FAQ#Candidate_window_is_blinking_under_wayland_with_Fcitx_5|Candidate window is blinking under wayland with Fcitx 5]]

Support Information:
* App/Compositor supports text-input-v2 and text-input-v3.
* Comopositor/Application uses zwp_input_method_v1.
* 5.27 additionally supports text-input-v1.
* 5.24 usable zwp_input_method_v1 with fcitx5. Pre-5.24 there are lots of problems, always use fcitx im module instead.
* Use "Virtual keyboard" KCM to launch fcitx5. This is required to use text-input protocol. If you launch fcitx this way, make sure you do not use "restart" in the tray menu, since the socket passed from KWin can not be reused with the newly restarted fcitx.

=== GNOME ===
Best setup:
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Set <code>QT_IM_MODULE=fcitx</code> for Qt, since Qt5 would use XWayland by default.
** Run chrome with XWayland and <code>GTK_IM_MODULE=fcitx</code>

Support information:
* Application/Compositor uses text-input-v3
* Compositor/Input Method uses ibus dbus protocol, so ibus frontend is required to be used.
* Adding Fcitx 5 to autostart, it will replace any existing ibus-daemon upon start up so it will work out of box.
* Popup candidate window is not able to be displayed over gnome-shell UI. Only solution is to use [[Special:MyLanguage/Kimpanel|Kimpanel]], [https://extensions.gnome.org/extension/261/kimpanel/ link to extension].
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Sway ===
* Application/Compositor uses text-input-v3
* Comopositor/Application uses zwp_input_method_v2, but it's partially implemented. You will need [https://github.com/swaywm/sway/pull/7226 this pull request] to make it show the popup candidate window for text-input-v3 client.
* fcitx im module also works.
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Weston ===
* Application/Compositor uses text-input-v1
* Comopositor/Application uses zwp_input_method_v1.
* Since it has no text-input-v3, which is more commonly used, im module is the only solution for Gtk/Qt, need to set GTK_IM_MODULE=fcitx and QT_IM_MODULE=fcitx.
* Add following content to ~/.config/weston.ini to make it launch fcitx 5. (xwayland part is recommended to make fcitx work best, even if it's wayland)

<pre>
[core]
xwayland=true

[input-method]
path=/usr/bin/fcitx5
</pre>

=== Other compositors ===
Please check their upstream for more information. For wlroots based compositors, it is possible that they also support in the same way as Sway does, or zwp_input_method could also be unsupported.

== Known Issues ==
=== Fcitx managed XKB layout ===
Unlike X11, there is no generic way to set XKB layout to compositor, which means it can only be implemented for every individual desktop. Right now, Fcitx managed layout only works for KDE Plasma and GNOME.

As for other desktop, in order to make this "semi" work you'll need to ensure following:

* The XKB layout of the input method group should be the same as the actual xkb layout you configured for the compositor. Fcitx will "think" the layout is the same and bypass the key conversion logic.
* If you need other layout for text typing (e.g. Arabic), just add them to the Fcitx. As long as the key is forwarded to fcitx, it should work.

=== Popup candidate window ===
Wayland does not have a global coordinate system for regular client, so for native wayland client, it is impossible for Fcitx to place a wayland surface at a certain position. In order for popup window to be placed at the correct position, there are following cases:
* Xwayland have no problem and it should work as good as X11.
* If zwp_input_method protocol can be used, it has a surface role to allow compositor to place the popup window for input method. This only works if client uses text-input protocol.
* For GNOME, kimpanel extension can read window coordinate since it's running inside compositor. As long as im module can report relative coordinate, kimpanel extension can display the popup window at the correct position. As similar approach for Plasma kimpanel is planned, but not yet implemented.
* For Gtk/Qt, fcitx's im module implement a way to render the popup with in the client process. This has some limitation because implemenation of xdg_popup in Gtk3/Qt5 doesn't support reposition the window. So show/hide trick is used to mitigate this, but it may cause window blinking. Fcitx tries not to move window if possible. You may also disable popup animation if you're using KWin to help reduce the blinking.

=== Per-window input method state ===
When zwp_input_method is used, essentially there is only one input context visible to fcitx, and fcitx cannot distinguish what application is being used. Which means the input method "active"/"inactivate" state is now "global".

Now fcitx supports two protocol to figure out the focused window and the corresponding application name, including wlr-foreign-toplevel-management (used by wlroots based compositor) and plasma-window-management (used by kwin).

Lua

2024-03-21T00:23:49Z

Weng Xuetian: Created page with "Fcitx can be easily extended with lua. API documentation is available on [https://fcitx.github.io/fcitx5-lua/ Github]. = Make Fcitx load lua script = == Single file lua scr..."

Fcitx can be easily extended with lua.

API documentation is available on [https://fcitx.github.io/fcitx5-lua/ Github].

= Make Fcitx load lua script =

== Single file lua script with imeapi support ==
Sometimes, you may have a simple lua script that you want to use. If that's the case, you can simple put it under <code>~/.local/share/fcitx5/lua/imeapi/extensions/[name].lua</code>. IME API will just load it upon start up.

In addition to the standard fcitx module, there is also "ime" module available if you load it this way. The API follows the Google Pinyin's lua API that was once available on Windows. If you have some scripts that was designed at that time, you may simple drop the script in without modification.

== Stand alone lua addon ==
You may also create an standard lua addon like any other Fcitx addon. You will still need a file under <code>XDG_DATA/fcitx5/addon/[addon name].conf</code>.

<nowiki>
[Addon]
Name[da]=Lua IME-API
Name[fr]=API IME Lua
Name[ja]=Lua IME API
Name[ko]=Lua IME API
Name[ru]=Lua IME API
Name[zh_CN]=Lua IME API
Name[zh_TW]=Lua 輸入法 API
Name=Lua IME API
Comment[da]=Understøttelse af Lua IME-API
Comment[fr]=Prise en charge de l'API IME Lua
Comment[ja]=Lua IME API サポート
Comment[ko]=Lua IME API 지원
Comment[ru]=Поддержка Lua IME API
Comment[zh_CN]=Lua IME API 支持
Comment[zh_TW]=Lua 輸入法 API 支援
Comment=Lua IME API support
Category=Module
Version=5.0.12
Type=Lua
OnDemand=False
Configurable=False
Library=imeapi.lua

[Addon/Dependencies]
0=luaaddonloader
</nowiki>

At this point, only <code>Category=Module</code> is supported. And unlike the regular shared library addon, the <code>Library</code> field should be the entry file, which is placed under <code>XDG_DATA/fcitx5/lua/[addon name]/[file name].lua</code>.

And the addon dependency is required to contain <code>luaaddonloader</code>.

= Use Fcitx Lua API =

Simply use <code>require("fcitx")</code> to load fcitx module.

There are many API that allows you to register a callback function. In most case, the callback function needs to be global and is passed with function name as string, not as a function variable.

Develop an simple input method

2024-03-21T00:16:36Z

Weng Xuetian:

<languages />
<translate>

This is a step-by-step instruction for writing a Fcitx 5 input method. The same instruction can be used for developing other types of addons, just input method engine is the most complex ones.

= Understand the file structure for a Fcitx shared library addon = 
Fcitx 5 provides a extensible framework for adding new addon types, but shared library support is built in and is the base of all other addon types. So we will only cover shared library addon in this document.


<nowiki>
[fcitx install prefix]
|
|- share/fcitx5
| |
| |- addon/[addon name].conf
| |- inputmethod/[input method name 1].conf
| | ...
| |- inputmethod/[input method name n].conf
|
|- lib/fcitx5
|
|- [library name].so
</nowiki>


Above is the file structure for an input method addon. For other types of addons, files under <code>inputmethod/</code> is not needed. The file name of <code>[addon name].conf</code> matters and will be used to uniquely reference this specific addon. Fcitx also follows XDG directory standard, so the files under XDG_DATA_DIR/fcitx5 will also be checked. Similarly, file name of configuration file under <code>inputmethod/</code> also matters and will be the unique name of a certain input method.


Example of <code>[addon name].conf</code>


<nowiki>[Addon]
Name[ca]=Pinyin
Name[da]=Pinyin
Name[de]=Pinyin
Name[he]=פיניין:
Name[ko]=병음
Name[ru]=Пиньинь
Name[zh_CN]=拼音
Name=Pinyin
Category=InputMethod
Version=5.0.8
Library=pinyin
Type=SharedLibrary
OnDemand=True
Configurable=True


[Addon/Dependencies]
0=punctuation


[Addon/OptionalDependencies]
0=fullwidth
1=quickphrase
2=cloudpinyin
3=notifications
4=spell
5=pinyinhelper
6=chttrans
7=imeapi
</nowiki>


Example of <code>[input method name].conf</code>


<nowiki>[InputMethod]
Name[ca]=Pinyin
Name[da]=Pinyin
Name[de]=Pinyin
Name[he]=פיניין:
Name[ko]=병음
Name[ru]=Пиньинь
Name[zh_CN]=拼音
Name=Pinyin
Icon=fcitx-pinyin
Label=拼
LangCode=zh_CN
Addon=pinyin
Configurable=True
</nowiki>


The file is in a ini-like format, with certain fcitx specific extensions and rules. It also supports XDG Desktop file style I18N for translation.

= Use CMake build system = 
It is your own freedom to pick whatever build system you would d like to use, as long as you produce the correct files. Fcitx 5 provides lots of support with CMake, so using CMake would be the most convenient way to build a Fcitx project. In this document, we will only cover using CMake as build system.

= A quick start: Quwei = 
[[wikipedia:区位码_(国标)|Quwei]] input method is an input method that basically allow you type the digit of GB2312 and produce the Chinese Character that matches this code. It used to be supported by Fcitx 4, but not included by Fcitx 5 anymore. Though it is hard to use, it can serve as a good example on how to implement a simple input method for Fcitx 5.

== Project skeleton == 
So let we start with a skeleton of this project.


<nowiki>├── CMakeLists.txt
├── LICENSES
│   └── BSD-3-Clause.txt # License for this project
├── po # Optional I18n
│   ├── CMakeLists.txt
│   ├── fcitx5-quwei.pot
│   ├── LINGUAS
│   └── zh_CN.po
└── src
├── CMakeLists.txt
├── quwei-addon.conf.in.in # Addon registration file
├── quwei.conf.in # Input method registration file
├── quwei.cpp # Engine implementation
└── quwei.h # Engine implementation
</nowiki>


You may want to check some CMake tutorial to understand some basic CMake usage.


The CMakeLists.txt in the root directory lookup for the dependency.


<nowiki>
cmake_minimum_required(VERSION 3.21)
project(fcitx5-quwei)


find_package(Fcitx5Core REQUIRED)
# Setup some compiler option that is generally useful and compatible with Fcitx 5 (C++17)
include("${FCITX_INSTALL_CMAKECONFIG_DIR}/Fcitx5Utils/Fcitx5CompilerSettings.cmake")


add_subdirectory(src)</nowiki>


The src/CMakeLists.txt would looks like


<nowiki># Make sure it produce quwei.so instead of libquwei.so
add_library(quwei SHARED quwei.cpp)
target_link_libraries(quwei PRIVATE Fcitx5::Core)
set_target_properties(quwei PROPERTIES PREFIX "")
install(TARGETS quwei DESTINATION "${FCITX_INSTALL_LIBDIR}/fcitx5")


# Addon config file
# We need additional layer of conversion because we want PROJECT_VERSION in it.
configure_file(quwei-addon.conf.in quwei-addon.conf)
install(FILES "${CMAKE_CURRENT_BINARY_DIR}/quwei-addon.conf" RENAME quwei.conf DESTINATION "${FCITX_INSTALL_PKGDATADIR}/addon")


# Input Method registration file
install(FILES "quwei.conf" DESTINATION "${FCITX_INSTALL_PKGDATADIR}/inputmethod")</nowiki>


quwei.conf.in would look like


<nowiki>[InputMethod]
# Translatable name of the input method
Name=Quwei
# Icon name
Icon=fcitx-quwei
# A short label that present the name of input method
Label=区
# ISO 639 language code
LangCode=zh_CN
# Match addon name
Addon=quwei
# Whether this input method support customization
# Configurable=True</nowiki>


This file will be loaded as an [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputMethodEntry.html InputMethodEntry] object.


quwei-addon.conf.in looks like


<nowiki>[Addon]
Name=Quwei
Category=InputMethod
Version=@PROJECT_VERSION@
Library=quwei
Type=SharedLibrary
OnDemand=True
Configurable=True


[Addon/Dependencies]
0=punctuation


[Addon/OptionalDependencies]
0=fullwidth
1=quickphrase
2=chttrans</nowiki>


This file will be loaded as an [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1AddonInfo.html AddonInfo] object.

== Basic implementation of InputMethodEngine == 
You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/02c32b07e47e0e75db4f248dbb33c31137d8df74 first commit] in the github.


Version 1 of quwei.h
<nowiki>/*
* SPDX-FileCopyrightText: 2021~2021 CSSlayer <wengxt@gmail.com>
*
* SPDX-License-Identifier: BSD-3-Clause
*
*/
#ifndef _FCITX5_QUWEI_QUWEI_H_
#define _FCITX5_QUWEI_QUWEI_H_


#include <fcitx/inputmethodengine.h>
#include <fcitx/addonfactory.h>


class QuweiEngine : public fcitx::InputMethodEngineV2 {
void keyEvent(const fcitx::InputMethodEntry & entry, fcitx::KeyEvent & keyEvent) override;
};


class QuweiEngineFactory : public fcitx::AddonFactory {
fcitx::AddonInstance * create(fcitx::AddonManager * manager) override {
FCITX_UNUSED(manager);
return new QuweiEngine;
}
};


#endif // _FCITX5_QUWEI_QUWEI_H_</nowiki>


Version 1 of quwei.cpp


<nowiki>/*
* SPDX-FileCopyrightText: 2021~2021 CSSlayer <wengxt@gmail.com>
*
* SPDX-License-Identifier: BSD-3-Clause
*
*/
#include "quwei.h"


void QuweiEngine::keyEvent(const fcitx::InputMethodEntry& entry, fcitx::KeyEvent& keyEvent)
{
FCITX_UNUSED(entry);
FCITX_INFO() << keyEvent.key() << " isRelease=" << keyEvent.isRelease();
}


FCITX_ADDON_FACTORY(QuweiEngineFactory);</nowiki>


When implement a Fcitx addon, it should be a sub-class of [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1AddonInstance.html AddonInstance]. The instantiation of AddonInstance is done via a [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1AddonFactory.html AddonFactory]. [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputMethodEngineV2.html InputMethodEngineV2] is a sub-class of AddonInstance. This class needs to be used when implementing an input method addon.


The minimum implantation of an input method engine only need to contain the implementation of the keyEvent function.


Here, we use a iostream like macro <code>FCITX_INFO()</code> to write every key we pressed to the log.


Assume the prefix your fcitx installation is /usr. The command to build this project would be:


<nowiki>
mkdir -p build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug # use Debug for easy debugging with gdb
make # or ninja, depending on your system
sudo make install # or sudo ninja install</nowiki>


If everything works fine, the install command should print out something like:


<nowiki>-- Install configuration: "Debug"
-- Installing: /usr/lib/fcitx5/quwei.so
-- Installing: /usr/share/fcitx5/addon/quwei.conf
-- Installing: /usr/share/fcitx5/inputmethod/quwei.conf</nowiki>


Now you can restart fcitx5 with <code>fcitx5 -rd</code> and add Quwei to the your configuration with [[Special:myLanguage/Configtool (Fcitx 5)|Configtool (Fcitx 5)]].


After switching to Quwei, the key press in application will make Fcitx 5 print out something like:


<nowiki>I2021-11-16 12:29:32.352702 quwei.cpp:12] Key(f states=0) isRelease=1
I2021-11-16 12:29:32.389935 quwei.cpp:12] Key(s states=0) isRelease=0
I2021-11-16 12:29:32.413689 quwei.cpp:12] Key(d states=0) isRelease=0
I2021-11-16 12:29:32.497661 quwei.cpp:12] Key(s states=0) isRelease=1
I2021-11-16 12:29:32.498021 quwei.cpp:12] Key(f states=0) isRelease=0
I2021-11-16 12:29:32.523816 quwei.cpp:12] Key(a states=0) isRelease=1
I2021-11-16 12:29:32.524051 quwei.cpp:12] Key(d states=0) isRelease=1
I2021-11-16 12:29:32.704919 quwei.cpp:12] Key(f states=0) isRelease=1
I2021-11-16 12:29:32.705006 quwei.cpp:12] Key(d states=0) isRelease=0
I2021-11-16 12:29:32.833024 quwei.cpp:12] Key(d states=0) isRelease=1
I2021-11-16 12:29:34.633936 quwei.cpp:12] Key(Control_L states=0) isRelease=0
I2021-11-16 12:29:35.053817 quwei.cpp:12] Key(Control+C states=4) isRelease=0
I2021-11-16 12:29:35.165617 quwei.cpp:12] Key(Control+C states=4) isRelease=1
I2021-11-16 12:29:35.348654 quwei.cpp:12] Key(Control+Control_L states=4) isRelease=1</nowiki>


So you know your input method engine is now working.

= Implement Input Method logic = 
Quwei is basically typing 4 digit number of Quwei code. Quwei code can be treated as Qu code xx and Wei code yy. The mapping from Quwei to GB2312 is (0xA0 + Qu, 0xA0 + Wei). When user type 3 digits of Quwei, input method will display a candidate list of 10 possible character with given quwei prefix.


You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/b9b047abb46fa0f9c42a0be82941b65b35b277eb second commit] in the github.

== Store the state for different input contexts == 
Fcitx allows different input context to held a different state. The state usually refers to the partially typed text and all other associated data structures. In Quwei case, the state is the digits that user already typed. To represent this, Fcitx provides a convenient class [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputBuffer.html InputBuffer] to allow engine to use this class conveniently to edit the internal state. In order to automatically construct the state when an input context getting constructed, Fcitx provides a framework called InputContextProperty. In order to use this, you first need to register a factory class to [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputContextManager.html InputContextManager], via registerProperty. Each property need to have a global unique name. The name can be something human-understandable. In Quwei case, I just use "quweiState". The benefit of using a nicer name is just in case you're developing something cross addon (Another addon need to access certain internal state of this addon), you can use this common name to load it in a different addon. If you do not need access from outside, the name does not really matter.


The factory class comes with a handy C++ template, [https://codedocs.xyz/fcitx/fcitx5/group__FcitxCore.html#ga9e60042d1f671a6fa31ea04bb4961ec9 FactoryFor]. This is actually an type alias to [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1LambdaInputContextPropertyFactory.html LambdaInputContextPropertyFactory]. This class simply accepts a lambda function as the factory implementation. This can save you sometime from creating your own subclass of [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1InputContextPropertyFactory.html InputContextPropertyFactory].


In order to get the state object from input context, you can simply use the factory object like this:


<nowiki>
auto *state = ic->propertyFor(&factory_);</nowiki>


In certain cases, it is also possible to un-register the factory and re-register it again in order to "refresh" all the internal state.

== Candidate List == 
In Fcitx 5, a candidate list is a part of the InputPanel class, stored as shared_ptr to avoid life time issue when selecting candidate triggers the User interface update. There's different capability provided by candidate list via certain interfaces. The helper class [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1CommonCandidateList.html CommonCandidateList] would provide most common functionality for a candidate list. It implements BulkCandidateList interface, and that is why it is not suitable for Quwei case. Because we want to have a semi-infinite candidate list for Quwei.


In Quwei, QuweiCandidateList gonna implement a PageableCandidate interface, which allows a prev/next page button to be displayed in the input method panel.

== Preedit == 
Preedit can refer to two different user interface element, one is the preedit embedded within the application, usually referred as "client preedit" in Fcitx. Another one is displayed with in the input method panel window. Usually, input method engine would only use one of them because there is only 1 form of preedit that need to be displayed. Whether the input context supports it or not can be checked via the capabilityFlags property.


Also there's something you may want to consider when using client preedit. Due to the different implementation in toolkit, toolkit may choose to commit the client preedit right away when application loses focus. For certain input methods, it might be designed to work in a way that typing does not need extra confirmation, for example, the word completion mode in keyboard engine. In such case, even though the preedit is used, user would expect the text it to be committed even if it is still in a preedit mode. In that sense, the preedit text should be exact same of the text that will be committed after confirmation.


In some version of iOS, its Pinyin input method using its client preedit in a way that may causes confusion: user types "nihao", and client preedit is displayed as segmented pinyin "ni hao". When text box loses focus, "ni hao" (extra space) would be committed into the application, and such outcome would never happen in regular usage of Pinyin.


Another thing to consider is where to put the cursor. While it might be natural to display the cursor at the its actual place within preedit, the input panel window will also be displayed at the client preedit cursor position. That means along with user regular typing, when cursor moves, the candidate window would also moves. In some cases, this is not desirable because it causes candidate window to be moved frequently when user types. An alternative way to handle this is to set the client cursor always to be 0. If you need to support display the position of actual cursor, you may use highlight style instead. For example, when you have "ABCD" in preedit and the cursor is between B and C. You may set client cursor to 0, and make "AB" displayed with highlight style to indicate the position of cursor.

== Key event handling == 
The most common use case is to call filterAndAccept() for all the key event that you intends to handle. Also, for most input method, key release is not relevant and should be pass-through to application. To make input method engine to work with any user input, be sure to consider all the possible key event that may be typed by user. For example, a common error is forgetting to block certain irrelevant key in composing mode and leaking the key into the application. Also, be careful for key event with modifier, you may want to pass through such key to make application specific hotkey still accessible even when user is composing.


Also, a key event has 3 different form of the Key objects. Normally a input method engine may only want to consider only the key() property. origKey() and rawKey() properties are less used. Key property is in a normalized form of key event. That removes "Shift" modifier for certain cases, which makes it easier to handle by the input method engine. For example, upper case A produced by Shift+A and Capslocked A will be the same after normalization. You may refer to the implementation to learn about how this normalization works.

= Reuse features from other addons = 
You may refer to the code at the [https://github.com/fcitx/fcitx5-quwei/commit/b01bf8c4344b50b496593b4d9cf8be49cd1ce9c2 third commit] in the github.


Fcitx provides a mechanism to invoking functions from other addons without having the need of directly linking to them. And also some easy to use CMake macro to look up the addon dependencies.


<nowiki>find_package(Fcitx5Module REQUIRED COMPONENTS Punctuation QuickPhrase)</nowiki>


We add the find_package line above to look up dependencies for Punctuation and QuickPhrase module.


If you want to implement such a module, you can use the following CMake macro


<nowiki>fcitx5_export_module(QuickPhrase TARGET quickphrase BUILD_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_SOURCE_DIR}" HEADERS quickphrase_public.h INSTALL)</nowiki>


And it will automatically generate the required CMake config for your addon.


When using other addons in the code, there is a handy macro <code>FCITX_ADDON_DEPENDENCY_LOADER</code> that will handle the addon loading at the runtime. When it is called for the first time, the dependent addon will be loaded automatically. Here we defines four different dependency in the code:


<nowiki> FCITX_ADDON_DEPENDENCY_LOADER(quickphrase, instance_->addonManager());
FCITX_ADDON_DEPENDENCY_LOADER(punctuation, instance_->addonManager());


private:
FCITX_ADDON_DEPENDENCY_LOADER(chttrans, instance_->addonManager());
FCITX_ADDON_DEPENDENCY_LOADER(fullwidth, instance_->addonManager());</nowiki>


The first parameter should be same as the addon name, second parameter is the expression to get the AddonManager object.


This mechanism make it easy to reuse the functionality implemented by other addons and shared the code. For example, classicui queries the X11/wayland connection from xcb addon and wayland addon.

= Configuration = 
While Quwei does not really need this feature, since it is a really common use case so it will be covered in this section. The addon has a few different interface relevant to configuration, such as getConfig, setConfig, getConfigForInputMethod, setConfigForInputMethod, reloadConfig. The getter function would need to return a [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1Configuration.html Configuration] object, while setConfig accepts a [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1RawConfig.html RawConfig] object. reloadConfig will be called to reload the configuration from disk, you may want to call reloadConfig() in the constructor of the addon too.


If Configurable field is set to True in the addon registration file, such method would be called to retrieve the information and Configtool would generate UI for it.


<nowiki>FCITX_CONFIGURATION(
ClipboardConfig, KeyListOption triggerKey{this,
"TriggerKey",
_("Trigger Key"),
{Key("Control+semicolon")},
KeyListConstrain()};
KeyListOption pastePrimaryKey{
this, "PastePrimaryKey", _("Paste Primary"), {}, KeyListConstrain()};
Option<int, IntConstrain> numOfEntries{this, "Number of entries",
_("Number of entries"), 5,
IntConstrain(3, 30)};);</nowiki>


Usually, you will define a sub class of Configuration with the FCITX_CONFIGURATION macro. First argument is the name of the class, and then you just simply add [https://codedocs.xyz/fcitx/fcitx5/classfcitx_1_1Option.html Option] as member. Following is a common implemenation of setConfig/getConfig/reloadConfig.


<nowiki> static constexpr char configFile[] = "conf/clipboard.conf";
void reloadConfig() override { readAsIni(config_, configFile); }


const Configuration *getConfig() const override { return &config_; }
void setConfig(const RawConfig &config) override {
config_.load(config, true);
safeSaveAsIni(config_, configFile);
}</nowiki>


readAsIni and safeSaveAsIni are helper functions to read/save Configuration object from/to the Fcitx ini-format. The file is saved under $XDG_CONFIG_HOME.

</translate>

Upgrade from Fcitx 4

2024-01-10T18:54:32Z

Weng Xuetian:

= Where is my data? =
Almost all Fcitx 4 data are stored under <code>~/.config/fcitx</code>.

For Fcitx 5, the paths follow more closely to XDG standard, which are <code>~/.local/share/fcitx5</code> and <code>~/.config/fcitx5</code>.

Specifically, Rime data was located at <code>~/.config/fcitx/rime</code> with Fcitx 4, while it is <code>~/.local/share/fcitx5/rime</code> in Fcitx 5.

= What package do I need to install? =
The distribution may have there own way to split package, I'll only talk about it on the source package how they mapped.

{| class="wikitable"
|-
! Fcitx 4 !! Fcitx 5
|-
| fcitx || fcitx5, fcitx5-gtk (Gtk IM Module), fcitx5-qt (Qt IM Module), fcitx5-chinese-addons (Pinyin & Table)
|-
| fcitx-qt5 || fcitx5-qt
|-
| fcitx-configtool || fcitx5-configtool
|-
| kcm-fcitx || fcitx5-configtool
|-
| fcitx-anthy || fcitx5-anthy
|-
| fcitx-chewing || fcitx5-chewing
|-
| fcitx-cloudpinyin || fcitx5-chinese-addons
|-
| fcitx-fbterm || fcitx5-fbterm
|-
| fcitx-hangul || fcitx5-hangul
|-
| fcitx-kkc || fcitx5-kkc
|-
| fcitx-libpinyin || Please use fcitx5-chinese-addons Pinyin instead.
|-
| fcitx-m17n || fcitx5-m17n
|-
| fcitx-rime || fcitx5-rime
|-
| fcitx-sayura || fcitx5-sayura
|-
| fcitx-skk || fcitx5-skk
|-
| fcitx-sunpinyin || Please use fcitx5-chinese-addons Pinyin instead.
|-
| fcitx-table-extra || fcitx5-table-extra
|-
| fcitx-table-other || fcitx5-table-other
|-
| fcitx-unikey || fcitx5-unikey
|-
| fcitx-zhuyin || fcitx5-zhuyin
|}

= Can I keep my old data? =
You'll need to reconfigure the input method list, migrating configuration file is not supported.

Certain engine does not store the data in fcitx's path, so they can be reused directly, e.g. Mozc, Anthy.

There are certain data can be migrated. fcitx5-migrator in fcitx5-configtool will help you do that. The supported Engine includes Pinyin, Rime, Table, SKK, KKC.

Upgrade from Fcitx 4

2024-01-10T18:53:00Z

Weng Xuetian:

= Where is my data? =
Almost all Fcitx 4 data are stored under ~/.config/fcitx.

For Fcitx 5, the paths follow more closely to XDG standard, which are ~/.local/share/fcitx5 and ~/.config/fcitx5.

Specifically, Rime data was located at ~/.config/fcitx/rime with Fcitx 4, while it is ~/.local/share/fcitx5/rime in Fcitx 5.

= What package do I need to install? =
The distribution may have there own way to split package, I'll only talk about it on the source package how they mapped.

{| class="wikitable"
|-
! Fcitx 4 !! Fcitx 5
|-
| fcitx || fcitx5, fcitx5-gtk (Gtk IM Module), fcitx5-qt (Qt IM Module), fcitx5-chinese-addons (Pinyin & Table)
|-
| fcitx-qt5 || fcitx5-qt
|-
| fcitx-configtool || fcitx5-configtool
|-
| kcm-fcitx || fcitx5-configtool
|-
| fcitx-anthy || fcitx5-anthy
|-
| fcitx-chewing || fcitx5-chewing
|-
| fcitx-cloudpinyin || fcitx5-chinese-addons
|-
| fcitx-fbterm || fcitx5-fbterm
|-
| fcitx-hangul || fcitx5-hangul
|-
| fcitx-kkc || fcitx5-kkc
|-
| fcitx-libpinyin || Please use fcitx5-chinese-addons Pinyin instead.
|-
| fcitx-m17n || fcitx5-m17n
|-
| fcitx-rime || fcitx5-rime
|-
| fcitx-sayura || fcitx5-sayura
|-
| fcitx-skk || fcitx5-skk
|-
| fcitx-sunpinyin || Please use fcitx5-chinese-addons Pinyin instead.
|-
| fcitx-table-extra || fcitx5-table-extra
|-
| fcitx-table-other || fcitx5-table-other
|-
| fcitx-unikey || fcitx5-unikey
|-
| fcitx-zhuyin || fcitx5-zhuyin
|}

= Can I keep my old data? =
You'll need to reconfigure the input method list, migrating configuration file is not supported.

Certain engine does not store the data in fcitx's path, so they can be reused directly, e.g. Mozc, Anthy.

There are certain data can be migrated. fcitx5-migrator in fcitx5-configtool will help you do that. The supported Engine includes Pinyin, Rime, Table, SKK, KKC.

Fcitx 5/zh-cn

2024-01-10T18:51:45Z

Weng Xuetian:

<languages/>

小企鹅输入法（Fcitx 读作[ˈfaɪtɪks]）是一个支持扩展的输入法框架。目前，它支持Linux操作系统，以及如freebsd这样的Unix操作系统。Fcitx 通过使用各种各样的输入法引擎来支持全世界大量不同种类的语言。

Fcitx本身的核心实现非常简单，它通过使用插件来提供强大的功能。fcitx可以非常容易的进行定制以满足不同的个性化需求。

[[Special:myLanguage/Fcitx|导航至旧版的 Fcitx 4 Wiki页面?]]

==== 用户 ====

* [[Special:myLanguage/Install Fcitx 5|如何安装 Fcitx 5]]
* [[Special:myLanguage/Setup Fcitx 5|设置 Fcitx 5]]
* 安装 [[Special:myLanguage/Input method engines|输入法引擎]]
* [[Special:myLanguage/Theme Customization|定制您的输入法主题]]
* [[Special:myLanguage/FAQ|常见问题]]
* [[Special:myLanguage/Using Fcitx 5 on Wayland|在 Wayland 上使用 Fcitx 5]]
* [[Special:myLanguage/Upgrade from Fcitx 4|从 Fcitx 4 升级]]

==== 开发者 ====

* [[Special:myLanguage/Compiling fcitx5|如何编译 fcitx5]]
* [[Special:myLanguage/Basic concept|基本概念]]
* [[Special:myLanguage/Develop an simple input method|如何开发一个简单的输入法]]
* [[Special:myLanguage/Q&A for developer|开发者常见问题与解答]]
* [[Special:myLanguage/Debug fcitx5|调试 fcitx5]]

==== 新闻 ====

<rss max=5>https://politepol.com/fd/hhM5BOjZLblk</rss>

== 如何帮助 Fcitx ==
* 给你的朋友推荐Fcitx输入法
* [[Special:myLanguage/Report Bug|报告漏洞]]
* [[Special:myLanguage/Contribute to this Wiki|为Wiki做贡献]] ('''请在申请你的帐号之前仔细阅读此页面''')
* [[Special:myLanguage/Donate|捐助]]

== 关于 ==
* [[Special:myLanguage/History|Fcitx的历史]]

Translations:Fcitx 5/5/zh-cn

2024-01-10T18:51:45Z

Weng Xuetian:

Upgrade from Fcitx 4

2024-01-10T18:35:43Z

Weng Xuetian: Created page with "= Where is my data? = Almost all Fcitx 4 data are stored under ~/.config/fcitx. For Fcitx 5, the paths follow more closely to XDG standard, which are ~/.local/share/fcitx5 an..."

= Where is my data? =
Almost all Fcitx 4 data are stored under ~/.config/fcitx.

For Fcitx 5, the paths follow more closely to XDG standard, which are ~/.local/share/fcitx5 and ~/.config/fcitx5.

= What package do I need to install? =
The distribution may have there own way to split package, I'll only talk about it on the source package how they mapped.

{| class="wikitable"
|-
! Fcitx 4 !! Fcitx 5
|-
| fcitx || fcitx5, fcitx5-gtk (Gtk IM Module), fcitx5-qt (Qt IM Module), fcitx5-chinese-addons (Pinyin & Table)
|-
| fcitx-qt5 || fcitx5-qt
|-
| fcitx-configtool || fcitx5-configtool
|-
| kcm-fcitx || fcitx5-configtool
|-
| fcitx-anthy || fcitx5-anthy
|-
| fcitx-chewing || fcitx5-chewing
|-
| fcitx-cloudpinyin || fcitx5-chinese-addons
|-
| fcitx-fbterm || fcitx5-fbterm
|-
| fcitx-hangul || fcitx5-hangul
|-
| fcitx-kkc || fcitx5-kkc
|-
| fcitx-libpinyin || Please use fcitx5-chinese-addons Pinyin instead.
|-
| fcitx-m17n || fcitx5-m17n
|-
| fcitx-rime || fcitx5-rime
|-
| fcitx-sayura || fcitx5-sayura
|-
| fcitx-skk || fcitx5-skk
|-
| fcitx-sunpinyin || Please use fcitx5-chinese-addons Pinyin instead.
|-
| fcitx-table-extra || fcitx5-table-extra
|-
| fcitx-table-other || fcitx5-table-other
|-
| fcitx-unikey || fcitx5-unikey
|-
| fcitx-zhuyin || fcitx5-zhuyin
|}

= Can I keep my old data? =
You'll need to reconfigure the input method list, migrating configuration file is not supported.

Certain engine does not store the data in fcitx's path, so they can be reused directly, e.g. Mozc, Anthy.

There are certain data can be migrated. fcitx5-migrator in fcitx5-configtool will help you do that. The supported Engine includes Pinyin, Rime, Table, SKK, KKC.

Fcitx 5

2024-01-10T18:19:57Z

Weng Xuetian:

<languages/>
<translate>


Fcitx [ˈfaɪtɪks] is an input method framework with extension support. Currently it supports Linux and Unix systems like freebsd. Fcitx supports typing with many languages all over the world with a large number of engines.


Fcitx has a slim core while provides powerful features with addons. It is easy to customize fcitx to satisfy your own needs.


[[Special:myLanguage/Fcitx|Looking for Old Wiki Page for Fcitx 4?]]

==== For Users ==== 


* [[Special:myLanguage/Install Fcitx 5|Install Fcitx 5]]
* [[Special:myLanguage/Setup Fcitx 5|Setup Fcitx 5]]
* Install [[Special:myLanguage/Input method engines|Input method engines]]
* [[Special:myLanguage/Theme Customization|Theme Customization]]
* [[Special:myLanguage/FAQ|FAQ]]
* [[Special:myLanguage/Using Fcitx 5 on Wayland|Using Fcitx 5 on Wayland]]
* [[Special:myLanguage/Upgrade from Fcitx 4|Upgrade from Fcitx 4]]

==== For Developers ==== 


* [[Special:myLanguage/Compiling fcitx5|Compiling fcitx5]]
* [[Special:myLanguage/Basic concept|Basic concept]]
* [[Special:myLanguage/Develop an simple input method|Develop an simple input method]]
* [[Special:myLanguage/Q&A for developer|Q&A for developer]]
* [[Special:myLanguage/Debug fcitx5|Debug fcitx5]]

==== News ==== 


<rss max=5>https://politepol.com/fd/hhM5BOjZLblk</rss>

== Help Fcitx == 
* Recommend Fcitx to your friend
* [[Special:myLanguage/Report Bug|Report Bug]]
* [[Special:myLanguage/Contribute to this Wiki|Contribute to this Wiki]] ('''Please read this before you request account''')
* [[Special:myLanguage/Donate|Donate]]

== About Fcitx == 
* [[Special:myLanguage/History|History]]

</translate>

FAQ

2024-01-06T16:13:20Z

Weng Xuetian:

<languages/>
<translate>


When you want to complain about input method cannot work correctly, please read this first.


Since 4.2.7, fcitx provides a command called fcitx-diagnose, it will try to detect some common problem and give some advice.


[[Special:MyLanguage/Hall of Shame for Linux IME Support|Hall of Shame for Linux IME Support]]

== When use Ctrl + Space, Fcitx cannot be triggered on == 


Check the application you want to type into.

=== Wayland === 


See [[Special:MyLanguage/Using Fcitx 5 on Wayland|Using Fcitx 5 on Wayland]].

=== Only one specific app has problem? === 
* The most possible reason for this is Ctrl+Space occupied by some hotkey, please change to another trigger key and try again. This usually happens in some editor, since many ide use Ctrl+Space as default key binding for Completion.

=== All Gtk Apps have problem? === 
* Please open a traditional Gtk App (traditional Gtk App means, it cannot be Firefox, Libreoffice, which only use Gtk as a UI style). Gedit is a good choice. Right click at the input box, there will be a menu named "Input Method", please make sure there is "Fcitx" in it and being choosed.


* If there is "Fcitx", but it still not works. Please try to restart Fcitx, if it will works at this time, please check your DBus settings, or make Fcitx start later. You can read [[Special:MyLanguage/Configure (Other)|Configure (Other)]] if you're using a custom startup script.


* If there is Fcitx but not being choosed by default, and please select it and you can immediately try again in this app. If not works, please read the entry above. For permanent fix (To use Fcitx by default), please read Configure part in [[Special:MyLanguage/Install And Configure|Install And Configure]].


* If there is no Fcitx, you should check your install first. Usually, the package name contains fcitx and gtk. If you [[Special:MyLanguage/Compile from source|compile fcitx from source]], please make sure you have enable GTK{2,3}_IM_MODULE option. If you're sure about this, please read [[Special:MyLanguage/Input method related environment variables|Input method related environment variables]] for how to update some cached file for gtk.


* If you are using Ubuntu and upgrade to 12.04 recently, or something werid happens to your system (Due to packager careless, or buggy package manager which can not do upgrade in correct order, for example, [https://bugs.archlinux.org/task/32764 pacman]), you might notice that gtk.immodules related files doesn't generate correctly during upgrade. Try uninstall {{package ubuntu|fcitx-frontend-gtk2}}, {{package ubuntu|fcitx-frontend-gtk3}} or coressponding package on your system and re-install them to trigger the file generate. Then recheck the input method menu to see whether it have "Fcitx" in the menu or not.

=== All Qt Apps have problem? === 
* Run qtconfig (might have different name on your distribution, it might be qtconfig-qt4), and go to the third tab, make sure fcitx is in the "Default Input Method" combo-box. If not, please check your install.
* Above solution can also applies if you want use XIM, but still we highly recommend you to use im module. See Also [[Special:MyLanguage/Input method related environment variables|Input method related environment variables]].

==== Telegram desktop ==== 
Some distribution enables Qt6 for telegram desktop. Just make sure you have the Qt6 im module (For fcitx4, it's fcitx-qt6 on archlinux).

=== Chromium or any other chromium based browser (E.g. Microsoft Edge) === 
For Chromium running under X11, if you are using startx to start your graphical user interface, you may hit [https://gitlab.freedesktop.org/xorg/app/xinit/-/issues/9 an issue] in startx that unset the DBUS_SESSION_BUS_ADDRESS, which prevent chromium based browser from using dbus correctly. To mitigate this, you may:


1. either export DBUS_SESSION_BUS_ADDRESS by yourself in your ~/.xinitrc (or simply change to use ~/.xsession if you are using debian based system).


2. or use a display manager like sddm, gdm, lightdm instead of startx.


For Chromium that runs natively under wayland, the only native wayland input method protocol it supports is text-input-v1, which is only supported by weston. Alternatively, it can also use Gtk4's im module, you can use following flag (---enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4) to make it use Gtk im module, but it doesn't fully work in terms of popup window position unless you are using kimpanel + GNOME.

=== Is it Java, Xterm, wine, or some other non-Gtk/Qt Application? === 
There are also some very rare case, that you're using a embedded linux or mini-linux distro, in which you must use XIM, the X server might missing some locale file. The file is usually needed to be under /usr/share/X11/locale/.


And When you must use XIM, please make sure, your locale '''must NOT''' be C or POSIX and need to be a valid locale (no matter which language), and need to be generated if you are using glibc (locale-gen). When you are using im module, there is no such limitation.

=== Is it a Qt application that bundles its own Qt library? === 
Bundled Qt library usually uses theirs own plugin directory, which is different from system's Qt. And commonly, they are also using Qt different on system Qt, which will also make it incompatible if you simply copy the system fcitx-qt files. But anyway, you can start to check whether it loads your copied files with following environment variable. Depending on how the XIM application is written, it may need to find specific font to make it work. On Archlinux xorg-mkfontscale is required to generate correct font dir files. After install it, you'll need to restart X Server to make it work.


QT_DEBUG_PLUGINS=1 QT_LOGGING_RULES="*.debug=true"


And try to resolve all incompatible errors. Usually, ubuntu's fcitx-frontend-qt5 and libfcitxqt5-1 are good source for fcitx-qt5 build against specific qt version. For example, DraftSight 2017S0 [https://groups.google.com/forum/#!topic/fcitx/9e4TI39_4sk] may work with xenial's fcitx-qt5.

=== Emacs === 
Try


LC_CTYPE=zh_CN.UTF-8 emacs


Don't forget to check your locale -a contains that. See also [[Special:MyLanguage/Input method related environment variables|Input method related environment variables]].


Emacs will use `-*-*-*-r-normal--<some font size>-*-*-*-*-*-*-*' as basefont(in src/xfns.c), if you do not have one matched, the code for input method won't run. Install some font package may help (For required fonts xorg-fonts-misc might be the right package but you can also try other xorg-fonts-* package.).

=== Non Gtk/Qt Wayland Application (Alacritty, kitty, etc) === 
It is possible that the application you use does not support input method at all, because they need to have relevant code to implement it. Even if they do, it is highly possible that compositor does not have the support for input method. Only GNOME Shell and KWin has full text-input-v3 support. As of 2022/05/07, sway still does not have full zwp_input_method_v2 support to support input surface. For KWin, you will need Plasma 5.24+ and Fcitx 5.0.14+ and make KWin to start Fcitx 5. You will need to go to Virtual Keyboard KCM and select Fcitx 5 in the KCM.

== Candidate window is blinking under wayland with Fcitx 5 == 
This is mainly due to the whole poor state of wayland input method. The existing wayland input method protocol is not widely supported by compositor. Even though fcitx 5 support those protocols, the poor support in application and compositor make them not usable. Not to mention certain design flaw within the protocol.


In order to make input method some what usable with '''CURRENTLY''' available and widely adopted techniques, Fcitx 5 implements a mechanism called "Client Side Input Panel", which basically asks client application to render the input window. This is done through dbus and IM Module for Gtk/Qt. The implementation requires using a underlying wayland protocol xdg_popup to show the window. Unfortunately, only new version of xdg_popup protocol supports '''moving''' a visible popup window, and this part is '''NOT''' implemented in Gtk3 and Qt5. What makes it even worse is that Gtk3 and Qt5 both comes to their end of life, which means it is not possible to get this new protocol support in Gtk3/Qt5. The issue is that input method requires to display a window that resizes and moves extremely frequently. To mitigate this issue, Fcitx 5 IM Module implement a hack that when we need to move the window, it will hide the window first and then show the window. Unfortunately, this would cause certain-level of blinking. It might looks bad in certain hardware and compositor combination.


Here is some possible workaround for this.


1. Use kimpanel under GNOME shell, which will make the candidate window to be rendered with a totally different mechanism, which won't cause any blinking.


2. Disable Fade-in and Fade-Out effect under KWin. KWin seems to tolerate such blink much better than certain compositor.

== Problem in Firefox and Google Docs == 


You might want to toggle preedit off temporarily, which is Ctrl+Alt+P.

== Cannot use Fcitx in flash == 


Please read [[Special:MyLanguage/Hall of Shame for Linux IME Support|Hall of Shame for Linux IME Support]], and use im module.

== Cannot type English after updating to fcitx newer than 4.2.4 == 


Make sure you have add "[[Special:myLanguage/Keyboard|Keyboard]]" to the input method list. You can use [[Special:myLanguage/Integrate with Desktop#Configuration tool|Configuration tool]].


And you may want to move "Keyboard" to the first one.

== Unexpected keyboard layout change == 


Use [[Special:myLanguage/Integrate with Desktop#Configuration tool|Configuration tool]], to bind specific keyboard layout to the specific input method.

== xmodmap settings being overwritten == 


Fcitx now control keyboard layout and when switch layout, xmodmap setting will be overwritten. So fcitx-xkb provides an option to specify the xmodmap script and let fcitx loads it for you whenever keyboard layout changes. Or disable fcitx-xkb addon is also a solution for you, or if your requirement is simply, for example, switching Caps Lock and Esc, which is provided by xkb option, you can just set it with your desktop keyboard configuration tool (Gnome and KDE all support such configuration).


For more detailed explanation, xmodmap is a very low level tool, that doesn't aware keyboard layout. For X11, keyboard layout is built on a set of profile, when such profile is loaded, anything you changed with xmodmap will be overwritten, this isn't specific to fcitx, but all tool that support keyboard layout configuration. Xkb option is a set of profile that can do some pre-defined change over keyboard layout, including many thing that people usually do with xmodmap, for example, defining where dead key is, switching Caps Lock and Esc, and so on. Unless you have special requirements, xkb layout and xkb option is recommended.


Since 4.2.7, Fcitx will try to load ~/.Xmodmap if it exists.

== Configure user interface, font, vertical list == 


Use [[Special:myLanguage/Integrate with Desktop#Configuration tool|Configuration tool]], Addon Configuration -> Classic UI.


If you are using [[Special:myLanguage/Configtool|fcitx-configtool]] newer than 0.4.5 or [[Special:myLanguage/Kcm|kcm-fcitx]] newer 0.4.1, you can directly configure those from the first level tab.

== Possible issue for GNOME 3.6 == 


[[Note for GNOME Later than 3.6]]

== [[Special:MyLanguage/ClassicUI|Classic UI]] is not transparent == 

* This problem might NOT exist any more since 4.2.6 with a different approach for detect composite manager.
* Restart Fcitx first, if it's ok then, it might be a bug in your Window manager. Gnome-Shell, xcompmgr is known to have this bug. You can try to set the delay start to walkaround this problem.
* If restart Fcitx doesn't solve this problem, you should check whether your window manager supports composite or it's enabled or not.
=== Kwin === 

Enable desktop effects.
=== Metacity before GNOME3 === 

gconftool-2 -s --type bool /apps/metacity/general/compositing_manager true
=== Xfce === 

Xfwm support composite, but need to be enabled by hand.
=== Compiz === 

0.9 series compiz can disable composite. You can use ccsm to configure it.
=== Other window manager === 


You can use xcompmgr, cairo-compmgr as composite manager for them.

== Minecraft == 


Original Minecraft under linux doesn't support input method, what make it worse is, XIM will conflict with its key event processing, one way to work around is, set a wrong environment variable on purpose for minecraft, then start up it. You can use following script to do that


<pre>#!/bin/sh
# set a wrong one
export XMODIFIERS="@im=null"
# start minecraft, this might change depends on you're mod, but simply its what you ARE using to start minecraft.
java -Xmx1024M -Xms512M -cp minecraft.jar net.minecraft.LauncherFrame</pre>


This way can be also used, if you don't want fcitx to work on some application which is using XIM.


There is a mod can be used to support input under Linux, called [http://forum.minecraftuser.jp/viewtopic.php?t=6279 NihongoMOD], 1.2.2 with minecraft 1.5.2 can work with Fcitx without upper hack.

== Root application under normal user X == 
Root application under X normal user session is always broken (in general, not specific to fcitx), due to the fact that dbus is a user session only process. The only way to type in root application with normal fcitx is to use XIM, set GTK_IM_MODULE=xim and QT_IM_MODULE=xim before you start your application.

== Cursor Following problem == 
There is a common misunderstanding that it's input method's fault that input window could not follow the cursor, which is simply wrong. This is how cursor following works: Application send the position to Input method, then input method move the input window. So if application do not send the position, the position would be wrong. This behavior is controlled by application, but not input method. So if you meet any problem, please ask application to fix it, don't ask input method to do anything. Actually, input method could do nothing with this.


Although there is some walkaround for specific problem, bug is still in application, not in input method.


* Opera, enable on the spot for [[Special:MyLanguage/XIM|XIM]].
* Firefox, enable preedit.

== Colored Emoji ==
The issue itself is usually not relevant to Fcitx itself, but the library used to render text. When using X11, or using native wayland input method protocol, the text is rendered by pango, which is the same as Gtk. You can also check if Gtk application is fine with such emoji character. A common issue is that, the embedded bitmap font is disabled by fontconfig, which is required to display color emoji.

As for Wayland that uses "Client side input panel" feature, the text is rendered natively by the toolkit. If it is a Qt application, which you may hit some Qt bugs: https://bugreports.qt.io/browse/QTBUG-80434 , https://bugreports.qt.io/browse/QTBUG-85744 , which does not have a resolution yet.


[[Category:How-to]]

</translate>

Donate

2024-01-05T20:50:08Z

Weng Xuetian:

<languages/>

<translate>


All Fcitx developers are using their spare time to develop Fcitx. So some money will be a great encourage for them.


Currently, we don't have a concentrated account to raise money, so the only way to donate to Fcitx is to donate to individual developer.

== Developer == 

=== CSSlayer === 
Check this page on my personal blog: [https://www.csslayer.info/wordpress/donation/]

</translate>

Setup Fcitx 5/zh-cn

2023-12-07T13:06:23Z

Weng Xuetian:

<languages />
= 开机自启动 =

== 特定发行版中的工具 ==

特定的发行版可能会提供一些用于自动启动 Fcitx 的工具，并且这些工具通常也会设置环境变量。

=== im-config (Debian/Debian-based/Ubuntu) ===
这是一个用于 Debian 和 Debian-based 发行版的工具。在登录到 GUI 之后，从命令行执行 <code>im-config</code>，应该会弹出一个向导程序，在其中选择 fcitx5 即可。

=== imsettings (Fedora) ===
这是一个与 im-config 类似的程序，它也提供了 GUI 来选择要使用的输入法框架。imsettings 应该是被默认安装的，如果没有，你可以手动安装它。imsettings 可以设置环境变量并且启动相应的输入法，它还提供了一个图形化的前端用于修改配置。你需要做的就是简单地执行<code>im-chooser</code>，log-out 然后再次 log-in。

[https://www.youtube.com/watch?v=FwqTtGEN4vQ 针对 Fedora 36 KDE 的操作说明]。这个操作说明应该适用于除 GNOME 外的 XDG 兼容桌面。

=== fcitx5-autostart (Fedora) ===
这是一个 [fedora 软件包]，打包了一个用于设置环境变量和 XDG autostart file 的 /etc/profile.d 脚本，可用于自启动。

== XDG Autostart ==

特定的发行版可能没有提供这个文件，如未提供，你可以直接复制 <code>/usr/share/applications/org.fcitx.Fcitx5.desktop</code> 到 <code>~/.config/autostart</code>

<nowiki>mkdir -p ~/.config/autostart && cp /usr/share/applications/org.fcitx.Fcitx5.desktop ~/.config/autostart</nowiki>

== KWin Wayland 5.24+ ==
如果你只使用 Gtk/Qt/Xwayland 应用，那么你不需要这里的操作。如果你希望使用支持 text-input-v3 的原生 wayland 应用，则需要让 KWin 将输入法作为一个特殊的客户端启动。

打开 systemsettings，转到 "Virtual Keyboard" 部分，将输入法从 "None" 改为 "Fcitx 5"

== 非 XDG 兼容的窗口管理器/Wayland Compoistor ==

在不支持 XDG Autostart 的场景中，请检查你的窗口管理器的手册中关于如何在系统启动时自动运行应用程序的方法。

=== Weston ===
Weston 是一个 wayland compositor 的参考实现，并不是普通用户的常规配置。

如果你希望使用 westons zwp_input_method_v1 实现，你需要确保以下内容存在 ~/.config/weston.ini 文件中（如果路径不是 /usr/bin/fcitx5 请做相应修改）。

<nowiki>[input-method]
path=/usr/bin/fcitx5</nowiki>

如果你已经在同一个会话中运行 fcitx5，当你为了调试和 fcitx5 尝试在 nested mode 中使用 weston 时，会存在特定的问题。

如果你出于调试目的只在 X11 中运行 weston，最简单的方法是在启动 weston 前退出 fcitx5.

另请注意，weston 有一个 bug，在首次运行时不会正确设置 DISPLAY 为输入法。您可能需要终止 fcitx5 一次才能使其正确设置 DISPLAY，或使用 OpenX11Connection dbus 调用来连接 fcitx。

= Environment variables =

Due to the transition phase in a lot of different places, there is no perfect solution that works for every one. Please choose your own solution based on your environment. Basically what you want to do is to set following environment variables for your desktop session.
<nowiki>
XMODIFIERS=@im=fcitx
GTK_IM_MODULE=fcitx
QT_IM_MODULE=fcitx</nowiki>
Though it looks like valid shell script, please *NOTE* that the snippet above is just to demonstrate what these value gonna be. Please check the section below for concrete syntax for different methods.

== Login shell profile ==
If you are using Bash as your login shell, <code>~/.bash_profile</code> is the best user-level thing you can rely on. It is widely supported by different DMs and will also work if you start graphics from TTY.

* Supported by mainstream Display manager, including GDM/SDDM/LightDM
* TTY login

If you are not using bash, you may want to double check if your shell profile can be used as a place to set environment variables, especially you are using some uncommon login shells.

The snippet that you need to add to <code>~/.bash_profile</code> would be
<nowiki>
export XMODIFIERS=@im=fcitx
export GTK_IM_MODULE=fcitx
export QT_IM_MODULE=fcitx</nowiki>

Some may argue that <code>~/.profile</code> is a shell agnostic solution, which is wrong. While GDM always source this file, SDDM/Bash would not source this file if <code>~/.bash_profile</code> presents. This makes <code>~/.bash_profile</code> a better solution because bash is quite widely used. But check your login shell before proceeding, some distribution may not use bash as default shell.

此[https://youtu.be/8XDmLr6wb4M 视频]演示了如何在 Archlinux 上手动设置环境变量

== /etc/profile ==
Best option if you does not care about modifying a file with root. This file is generally supported by all distribution. The code snippet that you need to append to the end of <code>/etc/profile</code> is same as [[Special:myLanguage/Setup Fcitx 5#Login in shell profile|login shell]].

== ~/.xprofile ==
An old perfect option if you are using X11 and display manager. But there is no counterpart for Wayland, so it is not ideal if you want to set environment variable for Wayland. The code that you want to add is same as [[Special:myLanguage/Setup Fcitx 5#Login in shell profile|login shell]].

== environment.d ==
This is a new configuration that introduced by system.d, but not widely used supported by desktop environment or display manager. It is basically the environment configuration for systemd user unit. Currently, it is only supported by GDM or Plasma 5.22+. As GDM, it means any session that login with GDM will work. As for Plasma, it means it works for Plasma regardless what DM you are using.

This configuration is applied upon your first user session login and persist afterwards unless you manually stop the systemd user. So after you modifies this configuration, the easiest way to make it effective is to reboot your system.

The syntax is similar to shell, but no <code>export</code> is required. For example, you can create a file <code>~/.config/environment.d/im.conf</code> with following content:
<nowiki>
XMODIFIERS=@im=fcitx
GTK_IM_MODULE=fcitx
QT_IM_MODULE=fcitx</nowiki>

== pam_env.so ==
This is an obsolete solution for following reasons:
* pam deprecate user level configuration <code>~/.pam_environment</code> since 1.5.0.
* Some distribution does not enable pam_env in their pam configuration.

If you know it works for your system, you can put following snippet to your <code>~/.pam_environment</code>.
<nowiki>XMODIFIERS DEFAULT=\@im=fcitx
GTK_IM_MODULE DEFAULT=fcitx
QT_IM_MODULE DEFAULT=fcitx</nowiki>.

Please '''NOTE''' that the syntax is different from shell script.

== ~/.config/plasma-workspace/env/*.sh ==
A env script location that only works for Plasma desktop, you need to create your own .sh file, e.g. <code>~/.config/plasma-workspace/env/im.sh</code> and put the code snippet same as [[Special:myLanguage/Setup Fcitx 5#Login in shell profile|login shell]].

== Other less common setup ==
There are some other variable that might be useful certain applications.
=== SDL_IM_MODULE ===
Set the value to fcitx. Only SDL2 requires this. SDL1 uses XIM.
=== GLFW_IM_MODULE ===
This is a variable only used by [https://github.com/kovidgoyal/kitty/ kitty]. You need to set it to `GLFW_IM_MODULE=ibus`.
=== Binary Qt application ===
Due to Qt 5 does not support XIM, and it only bundles ibus im module, you may want to set `QT_IM_MODULE=ibus` for Qt application that does not use your system Qt library. (It may still not work because certain Qt application does not even bundle any im module).

= DBus =
On most distribution that ships with systemd, this should no longer be an issue. But if you are using some so called "systemd" free distribution, you may need to start DBus yourself and set the relevant environment variables. Usually, this can be done by adding a line in like this in your start up script. E.g. ~/.xprofile if you are using X11. Also you need to make sure this syntax works for your login shell.

<nowiki>eval `dbus-launch --sh-syntax --exit-with-session`</nowiki>

= Configure Fcitx 5 =

See [[Special:myLanguage/Configtool (Fcitx 5)|Configtool (Fcitx 5)]].

Translations:Setup Fcitx 5/6/zh-cn

2023-12-07T13:06:23Z

Weng Xuetian:

[https://www.youtube.com/watch?v=FwqTtGEN4vQ 针对 Fedora 36 KDE 的操作说明]。这个操作说明应该适用于除 GNOME 外的 XDG 兼容桌面。

Setup Fcitx 5/zh-cn

2023-12-07T12:54:32Z

Weng Xuetian: Created page with "此[https://youtu.be/8XDmLr6wb4M 视频]演示了如何在 Archlinux 上手动设置环境变量"

<languages />
= 开机自启动 =

== 特定发行版中的工具 ==

特定的发行版可能会提供一些用于自动启动 Fcitx 的工具，并且这些工具通常也会设置环境变量。

=== im-config (Debian/Debian-based/Ubuntu) ===
这是一个用于 Debian 和 Debian-based 发行版的工具。在登录到 GUI 之后，从命令行执行 <code>im-config</code>，应该会弹出一个向导程序，在其中选择 fcitx5 即可。

=== imsettings (Fedora) ===
这是一个与 im-config 类似的程序，它也提供了 GUI 来选择要使用的输入法框架。imsettings 应该是被默认安装的，如果没有，你可以手动安装它。imsettings 可以设置环境变量并且启动相应的输入法，它还提供了一个图形化的前端用于修改配置。你需要做的就是简单地执行<code>im-chooser</code>，log-out 然后再次 log-in。

[Video instruction for Fedora 36 KDE]. 这个向导应该适用于除 GNOME 外的 XDG 兼容桌面。

=== fcitx5-autostart (Fedora) ===
这是一个 [fedora 软件包]，打包了一个用于设置环境变量和 XDG autostart file 的 /etc/profile.d 脚本，可用于自启动。

== XDG Autostart ==

特定的发行版可能没有提供这个文件，如未提供，你可以直接复制 <code>/usr/share/applications/org.fcitx.Fcitx5.desktop</code> 到 <code>~/.config/autostart</code>

<nowiki>mkdir -p ~/.config/autostart && cp /usr/share/applications/org.fcitx.Fcitx5.desktop ~/.config/autostart</nowiki>

== KWin Wayland 5.24+ ==
如果你只使用 Gtk/Qt/Xwayland 应用，那么你不需要这里的操作。如果你希望使用支持 text-input-v3 的原生 wayland 应用，则需要让 KWin 将输入法作为一个特殊的客户端启动。

打开 systemsettings，转到 "Virtual Keyboard" 部分，将输入法从 "None" 改为 "Fcitx 5"

== 非 XDG 兼容的窗口管理器/Wayland Compoistor ==

在不支持 XDG Autostart 的场景中，请检查你的窗口管理器的手册中关于如何在系统启动时自动运行应用程序的方法。

=== Weston ===
Weston 是一个 wayland compositor 的参考实现，并不是普通用户的常规配置。

如果你希望使用 westons zwp_input_method_v1 实现，你需要确保以下内容存在 ~/.config/weston.ini 文件中（如果路径不是 /usr/bin/fcitx5 请做相应修改）。

<nowiki>[input-method]
path=/usr/bin/fcitx5</nowiki>

如果你已经在同一个会话中运行 fcitx5，当你为了调试和 fcitx5 尝试在 nested mode 中使用 weston 时，会存在特定的问题。

如果你出于调试目的只在 X11 中运行 weston，最简单的方法是在启动 weston 前退出 fcitx5.

另请注意，weston 有一个 bug，在首次运行时不会正确设置 DISPLAY 为输入法。您可能需要终止 fcitx5 一次才能使其正确设置 DISPLAY，或使用 OpenX11Connection dbus 调用来连接 fcitx。

= Environment variables =

Due to the transition phase in a lot of different places, there is no perfect solution that works for every one. Please choose your own solution based on your environment. Basically what you want to do is to set following environment variables for your desktop session.
<nowiki>
XMODIFIERS=@im=fcitx
GTK_IM_MODULE=fcitx
QT_IM_MODULE=fcitx</nowiki>
Though it looks like valid shell script, please *NOTE* that the snippet above is just to demonstrate what these value gonna be. Please check the section below for concrete syntax for different methods.

== Login shell profile ==
If you are using Bash as your login shell, <code>~/.bash_profile</code> is the best user-level thing you can rely on. It is widely supported by different DMs and will also work if you start graphics from TTY.

* Supported by mainstream Display manager, including GDM/SDDM/LightDM
* TTY login

If you are not using bash, you may want to double check if your shell profile can be used as a place to set environment variables, especially you are using some uncommon login shells.

The snippet that you need to add to <code>~/.bash_profile</code> would be
<nowiki>
export XMODIFIERS=@im=fcitx
export GTK_IM_MODULE=fcitx
export QT_IM_MODULE=fcitx</nowiki>

Some may argue that <code>~/.profile</code> is a shell agnostic solution, which is wrong. While GDM always source this file, SDDM/Bash would not source this file if <code>~/.bash_profile</code> presents. This makes <code>~/.bash_profile</code> a better solution because bash is quite widely used. But check your login shell before proceeding, some distribution may not use bash as default shell.

此[https://youtu.be/8XDmLr6wb4M 视频]演示了如何在 Archlinux 上手动设置环境变量

== /etc/profile ==
Best option if you does not care about modifying a file with root. This file is generally supported by all distribution. The code snippet that you need to append to the end of <code>/etc/profile</code> is same as [[Special:myLanguage/Setup Fcitx 5#Login in shell profile|login shell]].

== ~/.xprofile ==
An old perfect option if you are using X11 and display manager. But there is no counterpart for Wayland, so it is not ideal if you want to set environment variable for Wayland. The code that you want to add is same as [[Special:myLanguage/Setup Fcitx 5#Login in shell profile|login shell]].

== environment.d ==
This is a new configuration that introduced by system.d, but not widely used supported by desktop environment or display manager. It is basically the environment configuration for systemd user unit. Currently, it is only supported by GDM or Plasma 5.22+. As GDM, it means any session that login with GDM will work. As for Plasma, it means it works for Plasma regardless what DM you are using.

This configuration is applied upon your first user session login and persist afterwards unless you manually stop the systemd user. So after you modifies this configuration, the easiest way to make it effective is to reboot your system.

The syntax is similar to shell, but no <code>export</code> is required. For example, you can create a file <code>~/.config/environment.d/im.conf</code> with following content:
<nowiki>
XMODIFIERS=@im=fcitx
GTK_IM_MODULE=fcitx
QT_IM_MODULE=fcitx</nowiki>

== pam_env.so ==
This is an obsolete solution for following reasons:
* pam deprecate user level configuration <code>~/.pam_environment</code> since 1.5.0.
* Some distribution does not enable pam_env in their pam configuration.

If you know it works for your system, you can put following snippet to your <code>~/.pam_environment</code>.
<nowiki>XMODIFIERS DEFAULT=\@im=fcitx
GTK_IM_MODULE DEFAULT=fcitx
QT_IM_MODULE DEFAULT=fcitx</nowiki>.

Please '''NOTE''' that the syntax is different from shell script.

== ~/.config/plasma-workspace/env/*.sh ==
A env script location that only works for Plasma desktop, you need to create your own .sh file, e.g. <code>~/.config/plasma-workspace/env/im.sh</code> and put the code snippet same as [[Special:myLanguage/Setup Fcitx 5#Login in shell profile|login shell]].

== Other less common setup ==
There are some other variable that might be useful certain applications.
=== SDL_IM_MODULE ===
Set the value to fcitx. Only SDL2 requires this. SDL1 uses XIM.
=== GLFW_IM_MODULE ===
This is a variable only used by [https://github.com/kovidgoyal/kitty/ kitty]. You need to set it to `GLFW_IM_MODULE=ibus`.
=== Binary Qt application ===
Due to Qt 5 does not support XIM, and it only bundles ibus im module, you may want to set `QT_IM_MODULE=ibus` for Qt application that does not use your system Qt library. (It may still not work because certain Qt application does not even bundle any im module).

= DBus =
On most distribution that ships with systemd, this should no longer be an issue. But if you are using some so called "systemd" free distribution, you may need to start DBus yourself and set the relevant environment variables. Usually, this can be done by adding a line in like this in your start up script. E.g. ~/.xprofile if you are using X11. Also you need to make sure this syntax works for your login shell.

<nowiki>eval `dbus-launch --sh-syntax --exit-with-session`</nowiki>

= Configure Fcitx 5 =

See [[Special:myLanguage/Configtool (Fcitx 5)|Configtool (Fcitx 5)]].

Translations:Setup Fcitx 5/28/zh-cn

2023-12-07T12:54:32Z

Weng Xuetian: Created page with "此[https://youtu.be/8XDmLr6wb4M 视频]演示了如何在 Archlinux 上手动设置环境变量"

此[https://youtu.be/8XDmLr6wb4M 视频]演示了如何在 Archlinux 上手动设置环境变量