WaylandでFcitx 5を使用する（翻訳）

nogajun
nogajun

これは、Fcitx WikiにあるWaylandでFcitx5を使うための資料「WaylandでFcitx 5を使用する」（Using Fcitx 5 on Wayland）をAIでざっくり翻訳したあとに、文章の流れなどを修正したものです。

WaylandとFcitx5の設定が都市伝説みたいに流れているのを見て苦々しく思ったので、日本語の情報を転がしておきます。

WaylandでFcitx 5を使用する

Wayland は次世代のディスプレイサーバープロトコルです。Waylandは2008年にリリースされましたが、入力メソッド（インプットメソッド）のサポートはまだ理想的とは言えない状態です。

また、Waylandベースのコンポジター上で入力メソッドを使用する場合、動作させるために通常とは異なる設定が必要になることがあり、X11で動作していたFcitxの特定の機能がWaylandでは未サポートの場合もあります。

このページでは、基礎となる詳細構造を含め、現時点での情報を総合的に説明します。なお、基本的な設定については Fcitx 5のセットアップ も参照してください。

アプリケーション

概要: XMODIFIERS、GTK_IM_MODULE、QT_IM_MODULE は、まだ必要ですか？

XMODIFIERS

XMODIFIERS については、必要です。X11環境とXWayland環境のどちらで動作するX11アプリケーションであっても挙動の違いは、ほとんどありません。

GTK_IM_MODULE

理想的な設定は、X11上で動作するGTKアプリケーションには、Fcitx IMモジュールを使用し、Wayland上で動作するGTKアプリケーションにはGTKのtext-input-v3を使用します。 設定は、以下のとおりです。

  1. 環境変数 GTK_IM_MODULE を設定しない。
  2. GTK 2 の場合、~/.gtkrc-2.0 に以下の内容を追加する。
gtk-im-module="fcitx"
  1. GTK 3 の場合、以下の内容を~/.config/gtk-3.0/settings.ini に追加する。
[Settings]
gtk-im-module=fcitx
  1. GTK 4 の場合、以下の内容を~/.config/gtk-4.0/settings.ini に追加する。
[Settings]
gtk-im-module=fcitx
  1. GNOME 3以降を使用している場合は、以下のコマンドも実行する。
gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/IMModule':<'fcitx'>}"

GTK_IM_MODULEについて、現時点でのモダンなGTK 3/4アプリケーションは、Westonを除くほぼすべてのコンポジターでサポートされているtext-input-v3が使用できます。

GTK_IM_MODULEの設定には、いくつかの選択肢があります。未設定の場合、GTK3およびGTK4ではGTK組み込みのWayland IMモジュールが使われます。設定は、GTK_IM_MODULE=waylandと指定して強制的に設定もできますが、この設定は、GTK2にも適用される点も注意してください。 コンポジターがWayland入力メソッドのフロントエンドをサポートしていない場合には、 GTK_IM_MODULE=fcitxの設定が必要になります。

環境変数 GTK_IM_MODULE を設定しない場合でも、GTKの設定ファイルを利用して特定のIMモジュールを強制的に使用できるので適切なIMモジュールを使い分けられます。

GTKの実装（バージョン3.24.41時点）におけるモジュール選択の優先順位は次の通りです。

  • X11環境
    1. 環境変数 GTK_IM_MODULE
    2. XSettingsの Gtk/IMModule の値
    3. 設定ファイル（settings.ini 等）の値
    4. ロケールに基づく自動選択
  • Wayland環境
    1. 環境変数 GTK_IM_MODULE
    2. wayland

QT_IM_MODULE

QT_IM_MODULE については、現時点で Qt < 6.7 は独自の text-input-v{2,4} しか利用できず、これはKWinでしかサポートされていません。つまり、KDE環境下では環境変数を解除（unset）すべきですが、その他のデスクトップ環境では QT_IM_MODULE=fcitx に設定する必要があります。

さらにサードパーティ製の独自仕様Qtアプリケーションの存在も状況を複雑にしています。それは、Waylandで動作しないものやQt Waylandを同梱/提供していないものがあるからです。

Fcitxは、Qtにとってサードパーティ製アプリにすぎず、大部分のアプリではFcitx IMモジュールを同梱していません。また、同梱していても必要なライブラリが不足しているケースも見受けられます。Fcitx 5はIBusプロトコルもサポートしていますが、これらのアプリの中にはIBus IMモジュールすら同梱していないものもあります。

このような独自仕様のQtアプリケーション（WPSオフィスやAnki、DaVinci Resolve、Mathematicaなど）に対しては、以下の環境変数の設定を試してみてください。

# Qt im module を同梱しているアプリ向け（WPS、Ankiなど）。ファイル名に "fcitx" が含まれる .so ファイルが存在するか確認してください。
QT_IM_MODULE=fcitx

# Qtに付属する IBus im module を同梱しているアプリ向け。パッケージ内に libibusplatforminputcontextplugin.so が存在するか確認してください。
QT_IM_MODULE=ibus

# 強制的に X11/XWayland 上で実行し、IBus im module を使用させる設定
QT_QPA_PLATFORM=xcb QT_IM_MODULE=ibus

Qt 6.7 では、QT_IM_MODULESという新しい環境変数が導入され、IMモジュールのフォールバックする順番を指定できるようになりました。その設定は、以下です。

QT_IM_MODULES="wayland;fcitx;ibus"

この設定を行うことにより、FcitxやWaylandを同梱していないアプリケーションでも利用可能なモジュールを選択できます。ですが、Qt 4/5アプリケーションで適切に処理するためには、依然としてQT_IM_MODULE（S が付かない方）を設定（または解除）しておく必要がある点に注意してください。

また、Qt 6.7では、text-input-v3のサポートが追加され、Qt 6.8シリーズでは text-input-v3に関する重要なバグ修正が行われました。text-input-v3のみをサポートするコンポジターを使用している場合、Qt 6.8.2以降であれば、text-input-v3を使用して問題なく動作するはずです。

XWayland上で動作するレガシーX11アプリケーション

一言でいうと、XWaylandの入力メソッドサポートは通常のX11ディスプレイサーバーと同等に良好です。同じ環境変数を設定している限り、XWaylandの使用が問題になることはありません。このカテゴリには以下が含まれます。

  • Xlibベース（およびXlibをベースとした他のツールキット（tk、SDL1など））: 例: xterm、rxvtなど。XMODIFIERS が正しく設定されていることを確認してください。
  • GTK 2ベース: Xlibと同様ですが、Fcitx IMモジュールが使用できます。GTK_IM_MODULE=fcitx に設定すると快適に使用できます。
  • Waylandにデフォルト設定されていないSDL2ベース: SDL_IM_MODULE=fcitx に設定します。
  • Electron、Chromium: これらはGTK 2の場合と同様に、依然としてデフォルトでX11動作になります。
  • Qt 4アプリケーション: Qt 4はX11でしか動作しません。QT_IM_MODULE=fcitx の設定が必要です。XCBを使用するQt 5以降も同様です（QT_QPA_PLATFORM=xcb でオーバーライド可能）。

GTK 3 / GTK 4

GTK 3およびGTK 4はネイティブで、text-input-v3をサポートしています。同時に、Wayland上で、Fcitx IMモジュールが使用できます。ですので、GTK_IM_MODULE=waylandと GTK_IM_MODULE=fcitx のどちらでも動作します。

Qt 5 / Qt 6

詳細については QT_IM_MODULE を参照してください。

Wayland上でQtアプリケーションがネイティブ動作している場合、QT_IM_MODULE を解除してtext-input-v2を使わせるか、QT_IM_MODULE=fcitx に設定してFcitx IMモジュールを使わせることができます。

text-input-v2は、開発元のWaylandプロトコルに統合されていないため、KWinでのみサポートされていると考えられます。つまり、KWin以外の環境でQtアプリケーションを動作させるには、QT_IM_MODULE=fcitx の設定が必要です。

Qt 6において、使用しているQtバージョンに該当の修正（https://codereview.qt-project.org/c/qt/qtwayland/+/416862）が含まれている場合は、QT_IM_MODULE=（空値）または QT_IM_MODULE=wayland を使用することも可能です。

Waylandネイティブアプリケーション（winitなど）

多くの場合、text-input-v3が使用されます。

Chromium / Electron

警告: このセクションの情報は、開発元の変更、とくにオプションを変更しない場合のデフォルトの挙動を完全に反映できていない可能性があります。

要約: XWaylandを使用してChromiumやElectronアプリケーションを実行する場合は、GTK IMモジュールをインストールし、X11の時と同様にGTK_IM_MODULE=fcitxを設定してください。

Wayland上でネイティブに実行させる場合、Chromiumでは以下のオプションを使用する必要があります。

# コンポジタが、text-input-v1プロトコルをサポートしている場合（下記のコンポジタのセクションを参照）
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

# コンポジタおよびChromiumが、text-input-v3プロトコルをサポートしている場合
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=3

# ただし、text-input-v3プロトコルの解釈の違いにより、KWinと併用した際に問題が発生する場合があります。
# KWinを使用している場合は、text-input-v1を推奨します。
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=1

# または以下（GNOME Shell + Kimpanel 拡張機能を使用しない限り、入力メソッドのポップアップウィンドウの表示位置がずれます）
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4

Electronの場合、利用可能なのは最初のオプションのみです（Electronは内部のChromiumをGTK 4で実行することをサポートしていません）。以下はVS Codeの例です。

# コンポジタが、text-input-v1プロトコルをサポートしている場合
code --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

デフォルトではXWayland下で動作するはずですが（Arch Linux / Chromium 110.0.5481.177時点）、Preferred Ozone PlatformがDefaultであってもWaylandが使用されているという報告もあります。

Waylandで動作しているかを確認するには、xeyes、またはxwininfo が利用できます。xeyesは、X11であれば「目」がマウスポインターを追いかけますが、Waylandでは追いかけません。xwininfoは、X11であればマウスポインターが「+」型に変わり、クリックしてウィンドウ情報が表示されます。

--ozone-platform=wayland、または--ozone-platform=x11フラグを使用して強制的にWayland、またはX11で動作させることもできます。chrome://flagsのPreferred Ozone Platformオプションを変更して設定を永続化できます。選択肢は、Default、X11、Wayland、Autoの4つです。

--gtk-version=4オプションを渡すことで、GTK 4で動作している場合に GTK_IM_MODULEを使用させることが可能です（現時点ではElectronではなくChromium/Chromeのみサポート）。

また、上記のフラグに加えて --enable-wayland-ime を渡すことで、text-input-v1 を使用させることもできます。

Chromiumのtext-input-v1サポートはあまり安定しておらず、ランダムなクラッシュに遭遇する可能性があります。過去には、バージョン112にクラッシュするバグ https://issues.chromium.org/issues/40263583 があり、バージョン115で修正されました。Chromiumの開発者は、バグのコメント欄で、このtext-input-v1は内部利用のみを想定しており十分なサポートは提供していないと述べているので、現状では唯一の導入しやすい選択肢ではあるものの利用は自己責任で行ってください。

--enable-wayland-ime と --gtk-version=4 のどちらを使用するかは、text-input-v1を使いたいのかGTK 4 IMモジュールを使いたいのかに応じて、いずれか一方のみを選択してください。text-input-v1は、KWin 5.27やWestonで動作します。GTK 4 IMモジュールは、すべての環境で動作しますが、ポップアップウィンドウを正しい位置に表示できるのはKimpanel拡張機能を導入したGNOMEのみです。

Waylandコンポジターにおけるサポート状況

Waylandネイティブなアプリケーションしか使用しない場合であっても、以下の理由から Xwayland は有効にしておくことを推奨します。

IMモジュール内のクライアント側入力パネルが動作しない場合、Fcitxは、WaylandウィンドウではなくX11ウィンドウへフォールバックします。その理由は、Waylandウィンドウは画面上に自由な配置ができないためです。これに対して、IMモジュールがアプリケーションウィンドウに対する相対座標しかFcitxに渡せず、その座標位置自体にあまり意味がない場合であっても、アプリのウィンドウサイズが「最大化」されていれば全体のグローバル座標として扱っても結果的に位置が「正しく」なることがあります。このため、無作為な位置に配置されるWaylandウィンドウよりも、X11ウィンドウの方が適した選択肢となります。

KDE Plasma

推奨セットアップ:

  • KDE Plasma 5.27以降
  • 環境変数:
    • XWaylandアプリケーション用に XMODIFIERS=@im=fcitx を設定
    • Fcitx 5の起動は「システム設定」->「仮想キーボード」から「Fcitx 5」を選択して行う
    • GTK_IM_MODULE、QT_IM_MODULE、SDL_IM_MODULE は設定しない。im-config を実行し、「im-configからのIM設定を行わずデスクトップのデフォルトを使用する」を選択することで、GTK_IM_MODULE と QT_IM_MODULE の設定を解除できます。
    • Chromium/Electronアプリケーションは --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime を付与して実行する
  • 注意事項:
    • X11下でしか正しく動作しない一部のGTK/Qtアプリケーションについては、個別に GTK_IM_MODULE や QT_IM_MODULE の設定が必要になる場合があります。
    • GTK_IM_MODULE/QT_IM_MODULE をグローバルに設定してしまうと、Wayland上のFcitx 5で候補ウィンドウが点滅する問題に遭遇します。

サポート情報:

  • アプリ/コンポジターは、text-input-v2、およびtext-input-v3をサポート。
  • コンポジター/アプリは、zwp_input_method_v1を使用。
  • 5.27ではさらにtext-input-v1をサポート。
  • 5.24以降では、Fcitx 5で実用的なzwp_input_method_v1が利用可能。5.24より前のバージョンでは多数の問題が存在するため、常にFcitx IMモジュールを使用してください。
  • Fcitx 5の起動には「仮想キーボード」KCMを使用します。これはtext-inputプロトコルを使用するために必須です。この方法でFcitxを起動した場合、トレイメニューの「再起動」は使用しないでください。KWinから渡されたソケットは、再起動した新しいFcitxプロセスで再利用できないためです。

GNOME

推奨セットアップ:

  • 環境変数:
    • XWaylandアプリケーション用に XMODIFIERS=@im=fcitx を設定
    • Qt5はデフォルトでXWaylandを使用するため、Qt用に QT_IM_MODULE=fcitx を設定
    • Qt >= 6.7, < 6.8.2を使用していない場合、Qt 6.8.2+ 向けに QT_IM_MODULES="wayland;fcitx" を設定
    • Chromeは、XWaylandとGTK_IM_MODULE=fcitx を指定して実行

サポート情報:

  • アプリケーション/コンポジターは text-input-v3を使用。
  • コンポジター/入力メソッドは、ibus dbusプロトコルを使用するため、ibusフロントエンドの使用が必須。
  • Fcitx 5を自動起動に追加すると、起動時に既存のibus-daemonが置き換わるため、特別な設定なしでそのまま動作します。
  • ポップアップの候補ウィンドウはgnome-shell UIの上に重ねて表示することができません。唯一の解決策は Kimpanel Extension を使用することです。
  • Mutterが text-input-v2をサポートしていないため、Qt < 6.8.2では QT_IM_MODULE=fcitx を使用する必要があります。

Sway

推奨セットアップ:

  • Sway 1.10以降
  • 環境変数:
    • XWaylandアプリケーション用に XMODIFIERS=@im=fcitx を設定
    • Qt5用に QT_IM_MODULE=fcitx を設定
    • Qt >= 6.7, < 6.8.2を使用していない場合、Qt 6.8.2+ 向けに QT_IM_MODULES="wayland;fcitx" を設定

サポート情報:

  • アプリケーション/コンポジターは、text-input-v3を使用。
  • コンポジター/アプリケーションは、zwp_input_method_v2を使用。text-input-v3クライアントでポップアップ候補ウィンドウを表示させるには、Sway 1.10以上（Pull Request #7226が含まれるもの）が必要です。
  • fcitx IMモジュールも動作します。
  • Swayが、text-input-v2をサポートしていないため、Qt < 6.8.2では QT_IM_MODULE=fcitx を使用する必要があります。

Weston

  • アプリケーション/コンポジターは、text-input-v1を使用。
  • コンポジター/アプリケーションは、zwp_input_method_v1を使用。
  • より一般的に使われている text-input-v3には対応していないため、GTK/Qtにおける唯一の解決策は、IMモジュールの使用となります。GTK_IM_MODULE=fcitx および QT_IM_MODULE=fcitx を設定する必要があります。
  • Fcitx 5を自動起動するには、~/.config/weston.ini に以下の内容を追加します（Wayland環境であっても、Fcitxを最良の状態で動作させるために xwayland の有効化を推奨します）。
[core]
xwayland=true

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

その他のコンポジター

詳細については、各コンポジター開発元の情報を確認してください。wlrootsベースのコンポジターの場合、Swayと同様の方式でサポートされている可能性がありますが、zwp_input_methodが非対応の可能性もあります。

既知の問題

Fcitx管理下のXKBレイアウト

X11とは異なり、Waylandにはコンポジターに対してXKBレイアウトを設定する共通の方法が存在しないため、デスクトップ環境ごとに個別実装する必要があります。現在、Fcitx管理によるレイアウト変更が動作するのはKDE PlasmaとGNOMEのみです。

その他のデスクトップでこれを「ある程度」動作させるには、以下の点を確保する必要があります。

  • 入力メソッドグループのXKBレイアウトを、コンポジターに実際に設定したXKBレイアウトと同一にする必要があります。Fcitxはレイアウトが同一であると「判断」し、キー変換ロジックをスキップします。
  • 文字入力用に他のレイアウト（アラビア語など）が必要な場合は、それらを直接Fcitxに追加してください。キーがFcitxへ転送されている限り、正しく動作するはずです。

ポップアップ候補ウィンドウの表示位置

Waylandには通常のクライアント向けグローバル座標系が存在しないため、ネイティブWaylandクライアントの場合、FcitxがWaylandサーフェスを特定の任意位置に配置することは不可能です。ポップアップウィンドウを正しい位置に配置するには、以下のケースが存在します。

  • XWayland: とくに問題はなく、X11と同等に良好に動作します。
  • zwp_input_methodプロトコルが利用可能な場合: 入力メソッド用にコンポジターがポップアップウィンドウを配置できるようにするサーフェスロールが存在します。これはクライアントが text-inputプロトコルを使用している場合にのみ機能します。
  • GNOME: Kimpanel拡張機能がコンポジター内部で動作しているため、ウィンドウの座標を読み取ることができます。IMモジュール側から相対座標さえ報告されれば、Kimpanel拡張機能が正しい位置にポップアップウィンドウを表示できます。Plasma向けKimpanelでも同様のアプローチが計画されていますが、まだ実装されていません。
  • GTK / Qt: FcitxのIMモジュールには、クライアントプロセス内部でポップアップを描画する実装が含まれています。ただし、GTK3/Qt5における xdg_popup の実装がウィンドウの位置変更（再配置）をサポートしていないという制限があります。そのため非表示/再表示のテクニックを使って緩和していますが、これによりウィンドウの点滅が発生する場合があります。Fcitx側も可能な限りウィンドウを移動させないよう試みています。KWinを使用している場合は、ポップアップのアニメーション効果を無効化することで点滅を軽減できる場合があります。

ウィンドウごとの入力メソッド状態保持

zwp_input_methodを使用する場合、実質的にFcitxから参照できる入力コンテキストは1つしかなく、Fcitx側でどのアプリケーションが使用されているかを区別できません。これは、入力メソッドの「有効（ON）/無効（OFF）」の状態が「グローバル（システム全体で共通）」になることを意味します。

現在Fcitxでは、フォーカスされているウィンドウと対応するアプリケーション名を特定するために、wlr-foreign-toplevel-management（wlrootsベースのコンポジターで使用）およびplasma-window-management（KWinで使用）の2つのプロトコルをサポートしています。