Qt関連の設定¶

概要 ¶

ChoreonoidはGUIの実装にQt（キュート）というフレームワークを使用しています。QtはWindows、X11、Waylandなどの違いを吸収しながら、各環境の画面スケーリング、フォント、配色などをGUIに反映します。

通常はQt固有の設定を行う必要はありません。まず、次の方針で調整してください。

Choreonoidを含む画面全体が小さすぎる、または大きすぎる場合は、WindowsまたはUbuntuの ディスプレイスケーリング を変更します。これが最も推奨される方法です。
Choreonoidだけを拡大または縮小したい場合は、環境変数 QT_SCALE_FACTOR を使用します。
ボタンなどの外観を変えたい場合は、Qtの「スタイル」を変更します。
フォントだけを変更することもできますが、アイコンやボタンとの大きさのバランスは変わります。GUI全体の大きさを調整する目的には、フォントサイズではなくディスプレイスケーリングを使用してください。

WindowsではQtがWindowsの設定を利用します。Ubuntuでも、現在Choreonoidが標準で使用するQt 5およびQt 6のHigh DPIスケーリング機能によって、GNOMEのディスプレイスケーリングがChoreonoid全体に反映されます。

以降では、まず通常の調整方法を説明し、その後にスタイルやQt固有の詳細設定を解説します。デフォルトの表示で問題がなければ、詳細設定を行う必要はありません。

GUI全体の大きさの調整 ¶

OSのディスプレイスケーリングを使用する ¶

GUI全体の大きさを調整するときは、OSのディスプレイスケーリングを使用するのが基本です。フォント、アイコン、ボタン、余白、3D表示に重ねて表示される要素などが同じ倍率で調整されるため、外観のバランスが保たれます。複数のディスプレイで異なる倍率を設定した場合も、OSとQtが対応していれば、ウィンドウを移動したときに倍率が切り替わります。

Windows ¶

Windows 11では、「設定」の「システム」-「ディスプレイ」にある「拡大/縮小」で倍率を設定します。通常はWindowsが推奨する倍率を選択してください。ChoreonoidはWindowsから通知された倍率を使用するため、Qt固有の設定は不要です。

設定変更後の表示が更新されない場合は、Choreonoidを一度終了してから再起動してください。

Ubuntu ¶

Ubuntuでは、「設定」の「ディスプレイ」で倍率を設定します。100%、125%、150%、200%など、利用可能な倍率はUbuntuのバージョン、ログインセッション、ディスプレイ構成によって異なります。

Choreonoidの標準的な構成は次のようになっています。

UbuntuとQtの標準構成¶
Ubuntu	Qt	スケーリング
22.04	Qt 5	ChoreonoidがQt 5のHigh DPIスケーリングを有効にし、OSの倍率をGUI全体に反映します。
24.04	Qt 6	Qt 6で標準となっているHigh DPIスケーリングを使用します。
26.04	Qt 6	Qt 6で標準となっているHigh DPIスケーリングを使用します。

このため、現在のChoreonoidでは、Ubuntu 22.04でも通常は QT_ENABLE_HIGHDPI_SCALING を設定する必要はありません。古いChoreonoidをQt 5で使用していて、100%以外の倍率でフォントとアイコンの大きさが合わない場合は、暫定的に次のように起動すると改善することがあります。

QT_ENABLE_HIGHDPI_SCALING=1 choreonoid

この設定は、Qt 5の自動High DPIスケーリングを有効にするものです。

X11、Wayland、グラフィックスドライバとの関係 ¶

UbuntuのログインセッションにはX11とWaylandがあります。使用中のセッションは次のコマンドで確認できます。

echo $XDG_SESSION_TYPE

x11 または wayland と表示されます。NVIDIAドライバを使用している場合を含め、Ubuntuのバージョンやドライバ構成によって利用されるセッションが変わることがあります。

グラフィックスボードやドライバがフォントサイズやQtスタイルを直接決めるわけではありません。ただし、利用可能なログインセッションやウィンドウシステムが変わることにより、Qtが使用する描画経路、ウィンドウ枠、影、端数倍率の扱いなどが間接的に変わることがあります。通常はセッションに応じたバックエンドをQtに自動選択させてください。

Choreonoidだけを拡大または縮小する ¶

OS全体の倍率を変えず、Choreonoidだけを調整したい場合は、環境変数 QT_SCALE_FACTOR を指定して起動します。例えば1.25倍で起動する場合は、Ubuntuでは次のようにします。

QT_SCALE_FACTOR=1.25 choreonoid

Windowsのコマンドプロンプトでは次のようにします。

set QT_SCALE_FACTOR=1.25
choreonoid

PowerShellを使用する場合は次のようにします。

$env:QT_SCALE_FACTOR = "1.25"
choreonoid

QT_SCALE_FACTOR はフォントだけでなく、アイコンやボタンを含むQtのGUI全体とデバイスピクセル比に作用します。ただし、この値はOSの倍率を置き換えるものではなく、OSから取得した倍率に掛け合わされます。例えばOS側が200%で QT_SCALE_FACTOR=1.25 とすると、実効倍率は250%に相当します。

この環境変数は、上記の例のようにChoreonoidの起動時だけ指定することを推奨します。.profile などで常時設定すると、他のQtアプリケーションにも影響します。

注釈

Qtの公式ドキュメントでは、QT_SCALE_FACTOR は主にHigh DPI対応のテスト用として位置付けられています。通常はOSの設定を使用し、Choreonoidだけを補正したい場合や問題を切り分ける場合に使用してください。

フォントの変更 ¶

フォントだけを変更すると、アイコンやボタンの大きさは同じままになる場合があります。GUI全体の大きさを調整したい場合は、前節のディスプレイスケーリングまたは QT_SCALE_FACTOR を使用してください。

Windows ¶

通常はWindowsで設定されたUIフォントが使用されます。Windowsの「アクセシビリティ」にある「テキストのサイズ」でも文字を拡大できますが、GUI部品全体とのバランスを保つには「ディスプレイ」の「拡大/縮小」を使用する方が適しています。

Ubuntu ¶

UbuntuでGNOMEのフォントを変更するには、GNOME Tweaksを利用できます。未導入の場合は次のコマンドでインストールします。

sudo apt install gnome-tweaks

次のコマンド、またはアプリケーションメニューの「Tweaks」から起動します。

gnome-tweaks

「フォント」にある「インターフェースのテキスト」は、メニュー、ボタン、ダイアログなどで使われる標準UIフォントです。Choreonoidも通常はこちらの設定を使用します。

「ドキュメントのテキスト」は、文書表示用フォントを要求するアプリケーションのための設定です。テキストエディタなどが本文用フォントとして使用することがありますが、すべてのアプリケーションに適用されるわけではなく、Choreonoidの通常のGUIフォントを変更する項目でもありません。

変更が実行中のChoreonoidに反映されない場合は、Choreonoidを再起動してください。

スタイルの変更 ¶

スタイルとは ¶

Qtの「スタイル」は、ボタン、チェックボックス、タブ、スクロールバーなどのQt Widgetsの描画方法を定めるものです。スタイルを変えるとGUI部品の形、余白、立体感などが変わりますが、ウィンドウシステムや画面スケーリングが切り替わるわけではありません。

Qtには通常、次のスタイルが組み込まれています。

Fusion
Windows

Fusion はQt独自のプラットフォーム非依存スタイルです。WindowsやGNOMEのネイティブスタイルを再現したものではなく、どのOSでもおおむね同じ外観になるよう設計されています。ただし、配色やフォントはプラットフォームテーマから取得することがあるため、OSの設定が外観の一部に反映される場合があります。

Windowsでは、このほかに windowsvista などのWindows向けスタイルが利用され、通常はWindowsに適したスタイルが自動選択されます。Ubuntuでどのスタイルが標準選択されるかは、インストールされているプラットフォームテーマやQtのバージョンによって変わります。

利用可能なスタイルの確認 ¶

現在利用できるスタイルは、Choreonoidの --list-qt-styles オプションで確認できます。

choreonoid --list-qt-styles

組み込みスタイルに加えて、Qtのプラグインディレクトリにインストールされたスタイルも表示されます。

スタイルの適用 ¶

Choreonoidの起動時に -style オプションを指定します。例えばFusionを使用する場合は次のようにします。

choreonoid -style Fusion

BreezeやAdwaitaがインストールされている場合は、次のように選択できます。

choreonoid -style Breeze
choreonoid -style Adwaita

環境変数 QT_STYLE_OVERRIDE でも指定できます。

QT_STYLE_OVERRIDE=Breeze choreonoid

Windowsのコマンドプロンプトでは次のようにします。

set QT_STYLE_OVERRIDE=Fusion
choreonoid

PowerShellを使用する場合は次のようにします。

$env:QT_STYLE_OVERRIDE = "Fusion"
choreonoid

コマンドラインで一時的に指定する方法は、他のQtアプリケーションに影響しないため、スタイルを試す際に適しています。

Ubuntuへのスタイルの追加 ¶

Ubuntu 26.04のQt 6環境では、KDE Plasmaで使用されるBreezeを次のパッケージで追加できます。

sudo apt install kde-style-breeze

Ubuntu 24.04の kde-style-breeze はQt 5向けなので、標準のQt 6版ChoreonoidにはBreezeを追加しません。

Ubuntu 24.04および26.04のQt 6環境では、GNOMEに近い外観のAdwaitaも次のパッケージで追加できます。

sudo apt install adwaita-qt6

Ubuntu 24.04では、追加スタイルとしてAdwaitaを使用するか、組み込みのFusionを使用してください。

Ubuntu 22.04のQt 5環境では、従来の追加スタイルを次のパッケージで導入できます。

sudo apt install qt5-style-plugins

このパッケージにはCleanlooks、Motif、Plastiqueなどの古いスタイルが含まれます。BreezeやAdwaitaなど、個別のQt 5用スタイルパッケージを利用することもできます。インストール後は --list-qt-styles で実際のスタイル名を確認してください。

Ubuntu 26.04では qt5-style-plugins パッケージは提供されていません。また、このパッケージはQt 5用であり、Qt 6版Choreonoidでは使用できません。Qt 6で追加スタイルが廃止されたわけではなく、Breeze、Adwaita、Kvantumなどがそれぞれ独立したパッケージとして提供されています。

Qt表示設定の詳細 ¶

ここからは、通常は変更する必要のない高度な設定を扱います。表示上の問題を切り分ける場合や、デスクトップとの統合方法を細かく変更したい場合に参照してください。

各機能の役割 ¶

Qtの表示には名前の似た機能が複数あります。それぞれの役割は次のとおりです。

Qtの表示に関係する主な機能¶
機能	主な役割	主な指定方法
High DPIスケーリング	フォント、アイコン、GUI部品を含む全体の大きさ	OSのディスプレイ設定、`QT_SCALE_FACTOR`
Qtスタイル	ボタンなどQt Widgetsの形と描画	`-style`、`QT_STYLE_OVERRIDE`
プラットフォームテーマ	OSから取得するフォント、配色、アイコンテーマ、標準スタイル、ネイティブダイアログなど	`QT_QPA_PLATFORMTHEME`
QPAプラットフォーム	QtとWindows、X11、Waylandなどのウィンドウシステムとの接続	`QT_QPA_PLATFORM`、`-platform`
Wayland装飾	Wayland上でのタイトルバー、ウィンドウ枠、影など	`QT_WAYLAND_DECORATION`
qt5ct／qt6ct	Qt用のフォント、配色、スタイル、アイコンなどをまとめて設定するツール	`QT_QPA_PLATFORMTHEME=qt5ct` または `qt6ct`

これらは互いに関連しますが、同じ機能ではありません。例えば、プラットフォームテーマを変更するとデフォルトのスタイルやフォントが変わることがありますが、QPAプラットフォームがWaylandからX11へ切り替わるわけではありません。

プラットフォームテーマ ¶

プラットフォームテーマは、Qtアプリケーションとデスクトップ環境をつなぐ層です。フォント、パレット、アイコンテーマ、標準スタイル、ファイル選択ダイアログなどの情報をQtに提供します。

UbuntuのQt 6環境では、インストールされているパッケージに応じて、例えば次のプラットフォームテーマを利用できます。

gtk3: Qtに含まれるGTK 3連携用テーマです。GTKからフォントや配色などを取得します。Ubuntuでは qt6-gtk-platformtheme パッケージによって提供されます。
gnome: QGnomePlatformが提供するGNOME向けテーマです。GNOMEの設定をQtアプリケーションへ反映することを目的としており、Ubuntuでは qgnomeplatform-qt6 パッケージによって提供されます。
qt6ct: qt6ctで保存した設定を使用するためのテーマです。Ubuntuでは qt6ct パッケージによって提供されます。

各テーマを追加するコマンドは次のとおりです。必要なものだけをインストールしてください。

sudo apt install qt6-gtk-platformtheme
sudo apt install qgnomeplatform-qt6
sudo apt install qt6ct

GNOMEはデスクトップ環境、GTKはGNOMEアプリケーションで広く使われているGUIツールキットです。このため gnome と gtk3 は目的が重なる部分を持ちますが、別のプロジェクトによる代替実装です。一度に選択されるプラットフォームテーマは基本的にひとつです。

Qtはデスクトップ環境とインストール済みプラグインから適切なテーマを自動選択します。通常は明示的に指定する必要はありません。切り替えて比較する場合は、例えば次のように起動します。

QT_QPA_PLATFORMTHEME=gtk3 choreonoid
QT_QPA_PLATFORMTHEME=gnome choreonoid

指定したテーマのプラグインがインストールされていなければ使用できません。また、プラットフォームテーマを固定すると、UbuntuやQtの標準選択よりもその指定が優先されます。問題がなければ未指定のまま使用してください。

qt5ctとqt6ct ¶

qt5ctおよびqt6ctは、Unix系デスクトップ上のQtアプリケーションについて、スタイル、配色、フォント、アイコンテーマなどをまとめて設定するための外部ツールです。Qt 5にはqt5ct、Qt 6にはqt6ctを使用します。

Ubuntuでは次のようにインストールできます。

sudo apt install qt5ct
sudo apt install qt6ct

実際には、使用するQtのメジャーバージョンに対応する方だけをインストールしてください。設定ツールは次のコマンドで起動します。

qt5ct
qt6ct

保存した設定をChoreonoidに適用するには、対応するプラットフォームテーマを選択して起動します。

QT_QPA_PLATFORMTHEME=qt5ct choreonoid
QT_QPA_PLATFORMTHEME=qt6ct choreonoid

これらのツールは、GNOMEやWindowsの標準設定とは別にQt専用の設定を持ちたい場合には便利です。一方、通常のスケーリング、フォント、スタイルはOSの設定や本ページで説明した環境変数で調整できるため、必須ではありません。

qt5ctとqt6ctは主にUnix系デスクトップ向けのツールです。Windowsでは通常使用せず、Windowsのディスプレイ、フォント、配色の設定を利用します。

注意

QT_QPA_PLATFORMTHEME=qt6ct を設定すると、GNOMEとの自動連携に代わってqt6ctの設定が使用されます。qt6ctを試した後で標準状態に戻す場合は、QT_QPA_PLATFORMTHEME の設定を削除してください。

QPAプラットフォームとxcb ¶

QPA（Qt Platform Abstraction）プラットフォームは、Qtが実際のウィンドウシステムと通信するためのバックエンドです。Windowsでは windows、LinuxのX11では xcb、Waylandでは wayland が代表的です。

xcb はX protocol C-language Bindingの略称で、Qtの xcb プラグインはX Window System（X11）に接続します。Waylandセッション上でもXWaylandが利用可能であれば、次の指定によってChoreonoidをX11アプリケーションとして起動できます。

QT_QPA_PLATFORM=xcb choreonoid

またはQtのコマンドラインオプションを使用できます。

choreonoid -platform xcb

この方法では、X11側のウィンドウ装飾によって枠や影が見やすくなる場合があります。一方、ネイティブWaylandアプリケーションではなくなるため、ディスプレイごとの端数スケーリング、入力処理、セキュリティ、将来の互換性などの挙動がWaylandとは異なります。通常の設定として固定するのではなく、Wayland固有の表示問題を回避する必要がある場合に使用してください。

逆に、明示的にWaylandを選ぶ場合は次のようにします。

QT_QPA_PLATFORM=wayland choreonoid

どちらも指定しなければ、Qtが実行環境に応じて選択します。通常は自動選択を推奨します。

Waylandのウィンドウ枠と影 ¶

Waylandでは、タイトルバー、ウィンドウ枠、影などの装飾をアプリケーション側が描画する場合があります。Qt Waylandで使用する装飾プラグインは、環境変数 QT_WAYLAND_DECORATION で変更できます。

QGnomePlatformの装飾プラグインは、次のコマンドでインストールできます。

sudo apt install qgnomeplatform-qt6

インストール後、次の指定を試すことができます。

QT_WAYLAND_DECORATION=qgnomeplatform choreonoid

これによりウィンドウの影や境界が見やすくなる場合がありますが、タイトルバーの色や形も変わることがあります。装飾の最終的な表示はQt、装飾プラグイン、GNOMEのコンポジタ、配色設定の組み合わせで決まるため、常に他のGNOMEアプリケーションと同じになるとは限りません。

前節の QT_QPA_PLATFORM=xcb でも影が変わることがありますが、こちらは装飾だけでなく、ウィンドウシステムへの接続自体をWaylandからX11へ切り替える点が異なります。

High DPI関連の環境変数 ¶

Qtで利用できる主なHigh DPI関連の環境変数を以下にまとめます。通常は QT_SCALE_FACTOR 以外を設定する必要はありません。

QT_SCALE_FACTOR: OSから得た倍率に掛ける、アプリケーション全体の倍率です。Choreonoidだけを調整する場合に使用できます。
QT_ENABLE_HIGHDPI_SCALING: Qt 5の自動High DPIスケーリングを制御します。現在のChoreonoidはQt 5でこれを有効にしているため、通常は設定不要です。古いQt 5版Choreonoidの問題を切り分ける場合に 1 を指定できます。
QT_SCALE_FACTOR_ROUNDING_POLICY: OSから得た端数倍率をQtがどのように丸めるかを指定します。主な値には Round、RoundPreferFloor、PassThrough などがあります。デフォルトはQt 5では Round、Qt 6では PassThrough です。通常は変更せず、125%や150%で描画上の問題がある場合だけQtの公式ドキュメントを参照して調整してください。
QT_SCREEN_SCALE_FACTORS: ディスプレイごとの倍率を直接指定します。QtがOSのDPI情報を利用できなくなるため、常用は推奨されません。
QT_USE_PHYSICAL_DPI: X11で論理DPIの代わりにディスプレイから得た物理DPIを使用します。物理寸法の報告が正しくないディスプレイもあり、通常は論理DPIの方が適切なので、常用は推奨されません。
QT_AUTO_SCREEN_SCALE_FACTOR: 古いQt 5で使用されていた環境変数です。現在は使用しないでください。

詳細については、Qt公式ドキュメントの Qt 6 High DPI または Qt 5.15 High DPI を参照してください。

設定状態の確認と標準状態への復帰 ¶

環境変数が設定されているかは、Ubuntuでは次のように確認できます。

env | grep '^QT_'

Windowsのコマンドプロンプトでは次のようにします。

set QT_

PowerShellを使用する場合は次のようにします。

Get-ChildItem Env:QT_*

Qtが検索・読み込みするプラグインの詳細を確認するには、Ubuntuで次のように起動します。出力は非常に多くなりますが、QPAプラットフォーム、プラットフォームテーマ、スタイルなどの候補と、実際に読み込まれたライブラリを確認できます。

QT_DEBUG_PLUGINS=1 choreonoid

表示を標準状態に戻すときは、これまでに設定した QT_SCALE_FACTOR、QT_STYLE_OVERRIDE、QT_QPA_PLATFORMTHEME、QT_QPA_PLATFORM、QT_WAYLAND_DECORATION などの環境変数を削除し、Choreonoidを再起動してください。Ubuntuのシェルで一時的に設定した変数は、例えば次のように解除できます。

unset QT_SCALE_FACTOR
unset QT_STYLE_OVERRIDE
unset QT_QPA_PLATFORMTHEME
unset QT_QPA_PLATFORM
unset QT_WAYLAND_DECORATION

Windowsのコマンドプロンプトでは、変数名の後を空にして解除します。

set QT_SCALE_FACTOR=
set QT_STYLE_OVERRIDE=
set QT_QPA_PLATFORMTHEME=
set QT_QPA_PLATFORM=
set QT_WAYLAND_DECORATION=

PowerShellでは次のように解除します。

Remove-Item Env:QT_SCALE_FACTOR
Remove-Item Env:QT_STYLE_OVERRIDE
Remove-Item Env:QT_QPA_PLATFORMTHEME
Remove-Item Env:QT_QPA_PLATFORM
Remove-Item Env:QT_WAYLAND_DECORATION

QtのQPAについては Qt Platform Abstraction 、スタイルについては QStyle も参照してください。