fcitx5-m3ui

A Material 3 styled candidate window for Fcitx5, built as a user interface addon (m3ui) that replaces classicui.

简体中文

Features

• Rounded Material 3 panel with light and dark themes that follow the system.
• Spring based animations: the panel slides in with a small bounce and fades in, the highlight pill glides between candidates. Stiffness and damping are configurable.
• Right click a candidate to open an action menu. It shows whatever actions the input method offers, for Pinyin that is Forget candidate, Pin to top as custom phrase and Delete from custom phrase.
• A forgotten candidate stays gone, also words from read only dictionaries (see Block list below).
• Works on Wayland and X11 (Xwayland) input contexts, positioning and pointer handling are inherited from classicui.
• Optional KWin helper that shortens KWin's own fade out for the candidate window only.

Status

Personal project, only tried on Fedora 44, KDE Plasma 6.7 on Wayland, NVIDIA GPU, Fcitx5 5.1.23 with the Pinyin engine. Animations, the right click menu, forgetting candidates and starting at login have been used on that setup.

scripts/build.sh has not been run from scratch in a clean environment, and no other distribution or desktop has been tried. Please open an issue if something breaks.

The addon is a fork of classicui and is built inside the Fcitx5 source tree, because Fcitx5's Wayland protocol wrappers are not installed by fcitx5-devel. The Fcitx5 source version used for the build must match the installed Fcitx5.

There is no fade out animation of its own: on Wayland the window is destroyed as soon as the panel has nothing to show.

Build

Needs the Fcitx5 development files and the dependencies of classicui (cairo, pango, librsvg, gdk-pixbuf, wayland-protocols, xcb libraries). On Fedora:

sudo dnf install fcitx5-devel extra-cmake-modules cairo-devel pango-devel \
    gdk-pixbuf2-devel librsvg2-devel wayland-protocols-devel \
    plasma-wayland-protocols-devel systemd-devel libuuid-devel fmt-devel \
    expat-devel iso-codes-devel json-devel xkeyboard-config-devel \
    xcb-util-devel xcb-util-keysyms-devel xcb-util-wm-devel \
    xcb-util-image-devel xcb-imdkit-devel libxkbfile-devel libxkbcommon-x11-devel

then

scripts/build.sh      # downloads Fcitx5 + yoga, overlays src/, builds m3ui
scripts/install.sh    # installs into ~/.local, nothing outside $HOME

build.sh picks the Fcitx5 version from pkg-config, override it with FCITX_VERSION.

Use

FCITX_ADDON_DIRS=$HOME/.local/m3ui/lib64/fcitx5:/usr/lib64/fcitx5 fcitx5 -r -u m3ui

FCITX_ADDON_DIRS is how Fcitx5 finds addons outside the system directory. fcitx5 -r (no arguments) brings the stock interface back.

Start with m3ui at every login:

scripts/enable-autostart.sh
systemctl --user daemon-reload && systemctl --user restart app-org.fcitx.Fcitx5@autostart.service

It writes two user level overrides (the XDG autostart entry and D-Bus activation) and changes only the Exec line. If the addon fails to load Fcitx5 falls back to classicui. To undo, delete the two files the script prints.

Settings live in ~/.config/fcitx5/conf/m3ui.conf, see config/m3ui.conf.example.

Key	Default	Meaning
Animations	True	Master switch for animations
Bounce	True	Off makes movement critically damped (no overshoot)
SpatialStiffness	2000	Spring stiffness for movement, higher is faster
SpatialDamping	62	Damping ratio in percent, lower bounces more
EffectsStiffness	3800	Spring stiffness for fading
SlideDistance	22	Slide in distance in px
SlideDirection	0	0 from left, 1 from right, 2 from below
Theme / DarkTheme	m3ui-light / m3ui-dark	Themes in themes/

Themes are classicui themes with extra keys in [InputPanel]: SurfaceColor, OutlineColor, HighlightFillColor, PanelRadius, ItemRadius. A transparent SurfaceColor falls back to the classic image based drawing, so classic themes still work (without animation).

Block list

The Pinyin engine's Forget candidate only removes words you have learned while typing. Words from the read only system dictionary (sc.dict) or from extra dictionaries come back when you type the same input again, also in the current composition.

When you pick Forget candidate, m3ui therefore also records the word in ~/.local/share/fcitx5/m3ui/blocked-words.txt (one word per line) and removes those words from the candidate list before every refresh.

• Matching is exact on the full text of the candidate.
• To bring a word back, delete its line and restart Fcitx5.
• This is a layer on top of the engine. With the stock classicui the words show up again.

KWin fade out (optional, KDE Plasma)

KWin's Fading Popups effect fades popups out over 600 ms and the candidate window counts as a popup. kwin/install-fadingpopups-override.sh copies the effect from your system into ~/.local/share/kwin-wayland/effects/ and patches the copy so only the window class fcitx fcitx is affected. The script fails if the upstream effect source no longer matches what it patches.

License

LGPL-2.1-or-later, see NOTICE.md.