Using Fcitx 5 on Wayland

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 Setup Fcitx 5 is still generally useful.

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

By default it runs under Xwayland, to make it runs natively under wayland, you can enforce ozone platform to wayland (in some about: or by command line --enable-features=UseOzonePlatform --ozone-platform=wayland).

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).

It's also possible to make it use text-input-v1 by pass --enable-wayland-ime.

Desktop environment

KDE Plasma

• 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 instead of XDG autostart.

GNOME

• 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 Kimpanel, link to extension.

Sway

• Application/Compositor uses text-input-v3
• Comopositor/Application uses zwp_input_method_v2, but it's partially implemented. You will need this pull request to make it show the popup candidate window for text-input-v3 client.
• fcitx im module also works.

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.

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.

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

• The system layout in the group should be the same as the actual xkb layout you configured for the compositor.
• Configure only one layout.
• 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".

There is planned change to obtain the active application name and use "virtual" input context for wayland frontend. It's not yet in the stable version of Fcitx.