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

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.
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.
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 --ozone-platform=wayland and --ozone-platform=x11. 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 --gtk-version=4.

It's also possible to make it use text-input-v1 by passing --enable-wayland-ime 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 --enable-wayland-ime or --gtk-version=4, 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.

Desktop environment

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

• 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

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

[core]
xwayland=true

[input-method]
path=/usr/bin/fcitx5

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.

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.