Changing DPI scaling size of display make Qt application's font size get rendered bigger

Resolving Qt Application Font Scaling Issues with DPI Changes

Understand why Qt applications render fonts larger after DPI scaling changes and learn effective strategies to ensure consistent UI appearance across different display settings.

Users often encounter situations where their Qt applications, particularly those developed with older Qt versions or without explicit high-DPI awareness, exhibit unexpectedly large font sizes after adjusting display DPI (Dots Per Inch) scaling. This issue stems from how Qt applications interpret system-wide scaling factors, leading to an inconsistent user experience. This article delves into the root causes of this behavior and provides practical solutions to achieve predictable font rendering in your Qt applications.

Understanding DPI Scaling and Qt's Behavior

DPI scaling is a mechanism used by operating systems to make UI elements appear consistently sized across displays with different pixel densities. A display with a higher DPI will have smaller physical pixels, so scaling increases the size of elements to maintain readability. Qt applications, especially those built with Qt 5.6 and later, have improved high-DPI support, but older applications or those not explicitly configured can still face issues.

When the system DPI changes, Qt applications might re-evaluate font metrics based on the new scaling factor. If not handled correctly, this can lead to fonts being scaled up disproportionately, making text appear excessively large and potentially breaking UI layouts. This is particularly common when moving an application between monitors with different scaling settings or when changing the system's primary display scaling.

flowchart TD
    A[User Changes Display DPI Scaling] --> B{Qt Application Startup/Monitor Change}
    B --> C{Qt Framework Detects DPI Change}
    C --> D{Font Metrics Recalculated}
    D --> E{Application Renders UI}
    E --> F{Fonts Appear Larger/Smaller}
    F --> G{Inconsistent UI Experience}
    G --> H[Developer Needs to Address Scaling]

Flowchart illustrating the process leading to font scaling issues in Qt applications.

Strategies for Consistent Font Rendering

To mitigate font scaling issues, several approaches can be taken, ranging from application-level configurations to code-based adjustments. The most effective solution often depends on your Qt version and the specific requirements of your application.

1. Enabling High-DPI Scaling in Qt

Qt 5.6 introduced Qt::AA_EnableHighDpiScaling which allows Qt to automatically adjust pixel metrics based on the operating system's DPI settings. For Qt 5.14 and later, Qt::AA_EnableHighDpiScaling is enabled by default, but for earlier versions (5.6-5.13), you might need to explicitly set it. This flag should be set before creating the QApplication instance.

#include <QApplication>
#include <QDebug>

int main(int argc, char *argv[])
{
    // Enable high-DPI scaling (for Qt 5.6 - 5.13)
    // For Qt 5.14+, this is enabled by default.
    QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);

    // For Windows, you might also need to enable DPI awareness
    // QCoreApplication::setAttribute(Qt::AA_UseHighDpiPixmaps);

    QApplication app(argc, argv);

    // ... your application code ...

    return app.exec();
}

Enabling high-DPI scaling attribute in a Qt application.

2. Using Environment Variables

You can also control Qt's DPI behavior using environment variables. This is particularly useful for testing or for users who need to override application-specific settings. The QT_SCALE_FACTOR and QT_FONT_DPI variables can directly influence how Qt renders fonts and UI elements.

# Set a global scaling factor (e.g., 1.5 for 150% scaling)
export QT_SCALE_FACTOR=1.5

# Set a fixed font DPI (e.g., 96 for standard DPI)
export QT_FONT_DPI=96

# Run your Qt application
./your_qt_application

Setting Qt DPI-related environment variables before launching an application.

3. Programmatic Font Size Adjustment

If the above methods don't fully resolve the issue or if you need more granular control, you can programmatically adjust font sizes. This involves detecting the current screen's DPI and then scaling your application's base font size accordingly. This method requires more manual management but offers maximum flexibility.

#include <QApplication>
#include <QFont>
#include <QScreen>
#include <QDebug>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    // Get the primary screen
    QScreen *screen = app.primaryScreen();
    if (screen) {
        // Get the logical DPI (pixels per inch)
        qreal dpi = screen->logicalDotsPerInch();
        qDebug() << "Current screen DPI:" << dpi;

        // Assume a baseline DPI (e.g., 96 DPI for 100% scaling)
        qreal baseDpi = 96.0;
        qreal scaleFactor = dpi / baseDpi;

        // Get the application's default font
        QFont defaultFont = app.font();
        int originalPointSize = defaultFont.pointSize();

        // Adjust font size based on scale factor
        int newPointSize = qRound(originalPointSize * scaleFactor);
        defaultFont.setPointSize(newPointSize);
        app.setFont(defaultFont);

        qDebug() << "Original font point size:" << originalPointSize;
        qDebug() << "New font point size:" << newPointSize;
    }

    // ... rest of your application code ...

    return app.exec();
}

Programmatically adjusting the application's default font size based on screen DPI.

4. Manifest File for Windows DPI Awareness

On Windows, applications can declare their DPI awareness level through an application manifest file. This tells the operating system how the application handles DPI scaling. For Qt applications, especially older ones, embedding a manifest that declares Per-Monitor V2 or Per-Monitor DPI awareness can significantly improve scaling behavior.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
  <assemblyIdentity
      version="1.0.0.0"
      processorArchitecture="*"
      name="YourAppName"
      type="win32"
  />
  <trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
    <security>
      <requestedPrivileges>
        <requestedExecutionLevel
            level="asInvoker"
            uiAccess="false"
        />
      </requestedPrivileges>
    </security>
  </trustInfo>
  <application xmlns="urn:schemas-microsoft-com:asm.v3">
    <windowsSettings>
      <dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">
        PerMonitorV2
      </dpiAwareness>
      <dpiAware xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">
        true/PM
      </dpiAware>
    </windowsSettings>
  </application>
</assembly>

Example manifest file snippet for Per-Monitor V2 DPI awareness on Windows.

This manifest file (typically named your_app_name.manifest) needs to be embedded into your executable during the build process. For MSVC, you can use the mt.exe tool or integrate it into your .pro file using RC_ICONS or RC_FILE.