Qt-related Settings¶

Overview ¶

Choreonoid uses a framework called Qt (pronounced “cute”) to implement its GUI. Qt accommodates differences among Windows, X11, Wayland, and other environments while reflecting each environment’s display scaling, fonts, color scheme, and other settings in the GUI.

Usually, you do not need to configure Qt-specific settings. Start by using the following approaches:

If the entire screen, including Choreonoid, is too small or too large, change the display scaling setting in Windows or Ubuntu. This is the recommended approach.
To enlarge or reduce only Choreonoid, use the QT_SCALE_FACTOR environment variable.
To change the appearance of buttons and other GUI elements, change the Qt “style.”
You can also change only the font, but this alters the size balance between the font, icons, and buttons. To adjust the size of the entire GUI, use display scaling rather than the font size.

On Windows, Qt uses the Windows settings. On Ubuntu, the High DPI scaling functionality of Qt 5 and Qt 6, which are currently used by standard Choreonoid builds, applies the GNOME display scaling setting to the entire Choreonoid GUI.

The following sections first explain the standard ways to adjust the display and then describe styles and advanced Qt-specific settings. If there is no problem with the default display, you do not need to use the advanced settings.

Adjusting the Overall GUI Size ¶

Using OS Display Scaling ¶

When adjusting the overall GUI size, the basic approach is to use the OS display scaling setting. Fonts, icons, buttons, margins, elements overlaid on the 3D display, and other GUI elements are adjusted by the same scale factor, maintaining a balanced appearance. If different scale factors are configured for multiple displays, the scale factor also changes when you move a window between them, provided that the OS and Qt support this behavior.

Windows ¶

On Windows 11, configure the scale factor under “Scale” in “Settings” - “System” - “Display.” Normally, select the scale factor recommended by Windows. Choreonoid uses the scale factor reported by Windows, so no Qt-specific setting is required.

If the display is not updated after changing the setting, exit and restart Choreonoid.

Ubuntu ¶

On Ubuntu, configure the scale factor under “Displays” in “Settings.” The available scale factors, such as 100%, 125%, 150%, and 200%, depend on the Ubuntu version, login session, and display configuration.

The standard Choreonoid configurations are as follows:

Standard Ubuntu and Qt configurations¶
Ubuntu	Qt	Scaling
22.04	Qt 5	Choreonoid enables Qt 5 High DPI scaling and applies the OS scale factor to the entire GUI.
24.04	Qt 6	Uses the High DPI scaling functionality enabled by default in Qt 6.
26.04	Qt 6	Uses the High DPI scaling functionality enabled by default in Qt 6.

Therefore, with the current version of Choreonoid, you normally do not need to set QT_ENABLE_HIGHDPI_SCALING, even on Ubuntu 22.04. If you are using an older Qt 5 version of Choreonoid and the font and icon sizes do not match at a scale factor other than 100%, temporarily launching it as follows may improve the display:

QT_ENABLE_HIGHDPI_SCALING=1 choreonoid

This setting enables automatic High DPI scaling in Qt 5.

Relationship with X11, Wayland, and Graphics Drivers ¶

Ubuntu login sessions can use X11 or Wayland. You can check the current session with the following command:

echo $XDG_SESSION_TYPE

This displays either x11 or wayland. The session used may vary depending on the Ubuntu version and driver configuration, including when using an NVIDIA driver.

The graphics card and driver do not directly determine the font size or Qt style. However, changes to the available login session or window system can indirectly affect the rendering path used by Qt, window borders, shadows, fractional scaling, and other behavior. Normally, allow Qt to select the backend automatically for the current session.

Scaling Only Choreonoid ¶

To adjust only Choreonoid without changing the system-wide OS scale factor, specify the QT_SCALE_FACTOR environment variable when launching Choreonoid. For example, to launch it at 1.25 times the normal size, use the following command on Ubuntu:

QT_SCALE_FACTOR=1.25 choreonoid

In Windows Command Prompt, use the following commands:

set QT_SCALE_FACTOR=1.25
choreonoid

In PowerShell, use the following commands:

$env:QT_SCALE_FACTOR = "1.25"
choreonoid

QT_SCALE_FACTOR affects the device pixel ratio and the entire Qt GUI, including not only fonts but also icons and buttons. This value does not replace the OS scale factor; it is multiplied by the scale factor obtained from the OS. For example, if the OS scale factor is 200% and QT_SCALE_FACTOR=1.25, the effective scale factor is equivalent to 250%.

It is recommended to specify this environment variable only when launching Choreonoid, as shown above. If it is set globally in .profile or another configuration file, it also affects other Qt applications.

Note

The official Qt documentation primarily positions QT_SCALE_FACTOR as a means of testing High DPI support. Normally, use the OS setting and use this variable only to adjust Choreonoid or diagnose display problems.

Changing Fonts ¶

When only the font is changed, icons and buttons may remain the same size. To adjust the size of the entire GUI, use the display scaling setting or QT_SCALE_FACTOR described in the previous section.

Windows ¶

The UI font configured in Windows is normally used. You can also enlarge text using “Text size” under “Accessibility” in Windows Settings, but the “Scale” setting under “Display” is more suitable for maintaining the size balance among all GUI elements.

Ubuntu ¶

You can use GNOME Tweaks to change GNOME fonts on Ubuntu. If it is not already installed, install it with the following command:

sudo apt install gnome-tweaks

Launch it with the following command or select “Tweaks” from the application menu:

gnome-tweaks

“Interface Text” under “Fonts” is the standard UI font used for menus, buttons, dialogs, and other GUI elements. Choreonoid normally uses this setting as well.

“Document Text” is intended for applications that request a document font. A text editor, for example, may use it as the body font, but it is not applied to every application and does not change the regular Choreonoid GUI font.

If the changes are not reflected in a running Choreonoid instance, restart Choreonoid.

Changing Styles ¶

What Is a Style?¶

A Qt “style” defines how Qt Widgets such as buttons, check boxes, tabs, and scroll bars are drawn. Changing the style alters the shape, spacing, and three-dimensional appearance of GUI elements, but it does not switch the window system or display scaling.

Qt normally includes the following built-in styles:

Fusion
Windows

Fusion is Qt’s own platform-independent style. It does not reproduce the native Windows or GNOME style and is designed to have approximately the same appearance on every OS. However, it may obtain the color scheme and fonts from the platform theme, so some OS settings may be reflected in its appearance.

On Windows, Windows-specific styles such as windowsvista are also available, and a suitable Windows style is normally selected automatically. On Ubuntu, the default style depends on the installed platform theme and the Qt version.

Checking the Available Styles ¶

You can check the currently available styles with Choreonoid’s --list-qt-styles option:

choreonoid --list-qt-styles

The output includes both the built-in styles and styles installed in the Qt plugin directory.

Applying a Style ¶

Specify the -style option when launching Choreonoid. For example, use the following command to select Fusion:

choreonoid -style Fusion

If Breeze or Adwaita is installed, you can select it as follows:

choreonoid -style Breeze
choreonoid -style Adwaita

You can also use the QT_STYLE_OVERRIDE environment variable:

QT_STYLE_OVERRIDE=Breeze choreonoid

In Windows Command Prompt, use the following commands:

set QT_STYLE_OVERRIDE=Fusion
choreonoid

In PowerShell, use the following commands:

$env:QT_STYLE_OVERRIDE = "Fusion"
choreonoid

Specifying the style temporarily on the command line is useful when trying styles because it does not affect other Qt applications.

Adding Styles on Ubuntu ¶

In the Qt 6 environment on Ubuntu 26.04, you can add Breeze, the style used by KDE Plasma, with the following package:

sudo apt install kde-style-breeze

The kde-style-breeze package on Ubuntu 24.04 is for Qt 5 and therefore does not add Breeze to the standard Qt 6 version of Choreonoid.

In the Qt 6 environments on Ubuntu 24.04 and 26.04, you can also add Adwaita, which has an appearance similar to GNOME, with the following package:

sudo apt install adwaita-qt6

On Ubuntu 24.04, use Adwaita as an additional style or use the built-in Fusion style.

In the Qt 5 environment on Ubuntu 22.04, you can install the traditional additional styles with the following package:

sudo apt install qt5-style-plugins

This package includes older styles such as Cleanlooks, Motif, and Plastique. You can also use separate Qt 5 style packages for Breeze, Adwaita, and other styles. After installation, use --list-qt-styles to check the actual style names.

The qt5-style-plugins package is not provided on Ubuntu 26.04. It is also intended for Qt 5 and cannot be used with the Qt 6 version of Choreonoid. Additional styles have not been discontinued in Qt 6; Breeze, Adwaita, Kvantum, and others are provided as separate packages.

Detailed Qt Display Settings ¶

This section covers advanced settings that normally do not need to be changed. Refer to it when diagnosing display problems or when you want more detailed control over desktop integration.

Roles of the Components ¶

Qt has several similarly named components related to its display. Their roles are as follows:

Main components related to the Qt display¶
Component	Primary role	Primary configuration method
High DPI scaling	Overall size, including fonts, icons, and GUI elements	OS display settings, `QT_SCALE_FACTOR`
Qt style	Shapes and drawing of Qt Widgets such as buttons	`-style`, `QT_STYLE_OVERRIDE`
Platform theme	Fonts, color scheme, icon theme, default style, native dialogs, and other information obtained from the OS	`QT_QPA_PLATFORMTHEME`
QPA platform	Connection between Qt and a window system such as Windows, X11, or Wayland	`QT_QPA_PLATFORM`, `-platform`
Wayland decoration	Title bar, window borders, shadows, and other decorations on Wayland	`QT_WAYLAND_DECORATION`
qt5ct/qt6ct	Tools for configuring Qt fonts, color schemes, styles, icons, and other settings together	`QT_QPA_PLATFORMTHEME=qt5ct` or `qt6ct`

These components are related but do not perform the same function. For example, changing the platform theme may change the default style or font, but it does not switch the QPA platform from Wayland to X11.

Platform Themes ¶

A platform theme is a layer that connects Qt applications to the desktop environment. It supplies Qt with information such as fonts, palettes, icon themes, default styles, and file selection dialogs.

In an Ubuntu Qt 6 environment, the following platform themes, for example, may be available depending on the installed packages:

gtk3: The GTK 3 integration theme included with Qt. It obtains fonts, colors, and other settings from GTK. On Ubuntu, it is provided by the qt6-gtk-platformtheme package.
gnome: The GNOME theme provided by QGnomePlatform. It is intended to reflect GNOME settings in Qt applications and is provided by the qgnomeplatform-qt6 package on Ubuntu.
qt6ct: A theme for using settings saved with qt6ct. On Ubuntu, it is provided by the qt6ct package.

Use the following commands to add these themes. Install only those you need:

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

GNOME is a desktop environment, while GTK is a GUI toolkit widely used by GNOME applications. Therefore, gnome and gtk3 have overlapping purposes, but they are alternative implementations from different projects. In principle, only one platform theme is selected at a time.

Qt automatically selects a suitable theme based on the desktop environment and installed plugins. You normally do not need to specify one explicitly. To switch themes for comparison, for example, launch Choreonoid as follows:

QT_QPA_PLATFORMTHEME=gtk3 choreonoid
QT_QPA_PLATFORMTHEME=gnome choreonoid

A specified theme cannot be used unless its plugin is installed. Explicitly setting a platform theme also takes precedence over the standard selection made by Ubuntu or Qt. If there is no problem, leave it unspecified.

qt5ct and qt6ct ¶

qt5ct and qt6ct are external tools for configuring the styles, color schemes, fonts, icon themes, and other settings of Qt applications on Unix-like desktops. Use qt5ct for Qt 5 and qt6ct for Qt 6.

You can install them on Ubuntu as follows:

sudo apt install qt5ct
sudo apt install qt6ct

In practice, install only the tool corresponding to the major Qt version you use. Launch the configuration tools with the following commands:

qt5ct
qt6ct

To apply the saved settings to Choreonoid, launch it with the corresponding platform theme selected:

QT_QPA_PLATFORMTHEME=qt5ct choreonoid
QT_QPA_PLATFORMTHEME=qt6ct choreonoid

These tools are useful when you want Qt-specific settings separate from the standard GNOME or Windows settings. However, they are not required because the regular scaling, fonts, and styles can be adjusted with OS settings and the environment variables described on this page.

qt5ct and qt6ct are primarily intended for Unix-like desktops. They are not normally used on Windows; use the Windows display, font, and color settings instead.

Caution

Setting QT_QPA_PLATFORMTHEME=qt6ct replaces automatic GNOME integration with the qt6ct settings. To restore the standard state after trying qt6ct, remove the QT_QPA_PLATFORMTHEME setting.

QPA Platforms and xcb ¶

The QPA (Qt Platform Abstraction) platform is the backend through which Qt communicates with the actual window system. Typical QPA platforms are windows for Windows, xcb for X11 on Linux, and wayland for Wayland.

xcb stands for X Protocol C-Language Binding, and Qt’s xcb plugin connects to the X Window System (X11). Even in a Wayland session, if XWayland is available, you can launch Choreonoid as an X11 application by specifying the following:

QT_QPA_PLATFORM=xcb choreonoid

Alternatively, you can use the Qt command-line option:

choreonoid -platform xcb

This method may make borders and shadows easier to see because it uses X11-side window decorations. However, Choreonoid is no longer a native Wayland application, so behavior related to per-display fractional scaling, input handling, security, and future compatibility differs from Wayland. Do not set this as the standard configuration; use it when necessary to work around a Wayland-specific display problem.

Conversely, use the following command to select Wayland explicitly:

QT_QPA_PLATFORM=wayland choreonoid

If neither is specified, Qt selects one according to the runtime environment. Automatic selection is normally recommended.

Wayland Window Borders and Shadows ¶

On Wayland, the application may draw decorations such as the title bar, window borders, and shadows. The decoration plugin used by Qt Wayland can be changed with the QT_WAYLAND_DECORATION environment variable.

You can install the QGnomePlatform decoration plugin with the following command:

sudo apt install qgnomeplatform-qt6

After installation, you can try the following setting:

QT_WAYLAND_DECORATION=qgnomeplatform choreonoid

This may make window shadows and borders easier to see, but it may also change the title bar color and shape. The final appearance of the decoration is determined by the combination of Qt, the decoration plugin, the GNOME compositor, and the color settings, so it does not necessarily match other GNOME applications.

The QT_QPA_PLATFORM=xcb setting described in the previous section may also change the shadow, but it differs in that it switches the connection to the window system itself from Wayland to X11 rather than changing only the decoration.

Checking the Current Settings and Restoring the Defaults ¶

On Ubuntu, use the following command to check whether any relevant environment variables are set:

env | grep '^QT_'

In Windows Command Prompt, use the following command:

set QT_

In PowerShell, use the following command:

Get-ChildItem Env:QT_*

To check details of the plugins that Qt searches for and loads, launch Choreonoid on Ubuntu as follows. The output is extensive, but it shows the QPA platform, platform themes, style candidates, and the libraries that are actually loaded:

QT_DEBUG_PLUGINS=1 choreonoid

To restore the standard display settings, remove any environment variables you have set, such as QT_SCALE_FACTOR, QT_STYLE_OVERRIDE, QT_QPA_PLATFORMTHEME, QT_QPA_PLATFORM, and QT_WAYLAND_DECORATION, and restart Choreonoid. In an Ubuntu shell, variables set temporarily can be removed as follows:

unset QT_SCALE_FACTOR
unset QT_STYLE_OVERRIDE
unset QT_QPA_PLATFORMTHEME
unset QT_QPA_PLATFORM
unset QT_WAYLAND_DECORATION

In Windows Command Prompt, clear each variable by leaving the value after its name empty:

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

In PowerShell, remove the variables as follows:

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

For more information about Qt’s QPA, refer to Qt Platform Abstraction, and for styles, refer to QStyle.