fcitx5-m3ui/README.en.md

# fcitx5-m3ui

A Material 3 styled candidate window for [Fcitx5](https://github.com/fcitx/fcitx5),
built as a user interface addon (`m3ui`) that replaces `classicui`.

[简体中文](README.md)

## 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](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](NOTICE.md).