Diagnosing and Fixing High‑DPI Scaling Issues in Qt Quick Controls 2 on Windows

Problem Overview

Qt Quick Controls 2 apps on Windows often look blurry, have misaligned layouts, or show pixelated icons when the system DPI is set above 100% (e.g., 150%). These symptoms usually stem from missing or mis‑configured high‑DPI support in the application. The guide below gives a step‑by‑step diagnostic flow, checks, and fixes that work with Qt 5.15 and Qt 6.5+ on Windows 10 or newer.

Quick Reference Table

Symptom	Common Cause	Diagnostic Check	Fix
Blurry, fuzzy text at >100% scaling	Qt::AA_EnableHighDpiScaling not set before QGuiApplication creation	Run qDebug() << QGuiApplication::devicePixelRatio(); – should equal system DPI factor (e.g., 1.5)	Set attribute in main.cpp before creating the application object
Controls jump or overlap when DPI changes at runtime	Runtime DPI change not handled by the window system	Observe layout shifts when changing Windows scaling while the app is running	Re‑create the window or call QQuickWindow::setPersistentSceneGraph(true) and allow Qt to re‑layout
Icon or image appears pixelated or too small	Icon assets not provided at high‑resolution (2×, 3×)	Check image size in the QML file and compare with devicePixelRatio()	Supply higher‑resolution images or use vector formats (SVG)
Widget size mismatches design pixel values	Qt::AA_UseHighDpiPixmaps not enabled or layout uses absolute pixels	Print QQuickWindow::highPixelRatioScaleFactor() and compare to design scale	Use Qt::AA_UseHighDpiPixmaps and relative sizing (e.g., width: 200 * dpiScale)

Ordered Diagnostic Checklist

1. Confirm Qt Version and OS
   • Run qmake -v or qmake -query QT_VERSION to ensure you’re on Qt 5.15 or Qt 6.5+.
   • Verify Windows version (10 or newer) via winver.
2. Check High‑DPI Attribute

   // main.cpp – must be first line after includes
   QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling, true);
   QGuiApplication app(argc, argv);
   

   Run the app and check the console for QGuiApplication::devicePixelRatio(). It should equal the system scaling factor (e.g., 1.5 for 150%). If it prints 1.0, the attribute was not set.

3. Inspect Environment Variables
   • Open a command prompt and echo QT_ENABLE_HIGHDPI_SCALING and QT_AUTO_SCREEN_SCALE_FACTOR.
   • Both should be unset or set to 1 for default behavior.

   These variables can override the attribute and cause blurry output if set incorrectly.

4. Use Qt Creator DPI Simulation

   In Qt Creator, go to Tools → Settings → Devices → DPI and simulate 150% scaling. Run the project and compare the layout to the design pixel values. If controls appear misaligned, the app isn’t handling scaling.

5. Verify Icon Scaling

   Image {
       source: "qrc:/icons/app.svg" // use vector if possible
       width: 32 * dpiScale
       height: 32 * dpiScale
   }
   

   Check that the image file exists at the expected resolution or is a vector. Use QWindow::devicePixelRatio() to calculate dpiScale.

6. Test Runtime DPI Changes

   On Windows, change the display scaling while the app is running. Observe if controls jump or overlap. If so, add a handler for the screenChanged signal:

   connect(window, &QWindow::screenChanged, this, &YourClass::onScreenChanged);
   
   void YourClass::onScreenChanged(QScreen *screen) {
       qreal scale = screen->devicePixelRatio();
       // Re‑apply scaling or rebuild the UI if necessary
   }
   

Fixes Tied to Findings

• Blurry Text

  Set the high‑DPI attribute before creating the application object. If you must run the attribute after QGuiApplication creation, you’ll need to recreate the window or call QQuickWindow::setPersistentSceneGraph(true) and force a re‑layout.

• Layout Shifts at Runtime

  Use relative sizing and avoid hard‑coded pixel values. Wrap sizes in a dpiScale multiplier derived from QScreen::logicalDotsPerInch() or devicePixelRatio(). Re‑create the window when the DPI changes if the layout cannot be recalculated.

• Icon Pixelation

  Provide high‑resolution raster assets (2×, 3×) or switch to vector formats such as SVG. Ensure the Image element’s source points to the correct file and that the UI uses width: 32 * dpiScale.

• Widget Size Mismatch

  Enable Qt::AA_UseHighDpiPixmaps in addition to Qt::AA_EnableHighDpiScaling. This tells Qt to load the appropriate image resolution automatically.

Escalation Criteria

1. If after applying all fixes the app still shows blurry text or misaligned controls, consider upgrading to the latest stable Qt release. Newer versions contain improved high‑DPI handling and bug fixes.
2. For multi‑monitor setups with per‑monitor scaling, verify that each monitor’s devicePixelRatio() is respected. If not, you may need to rebuild the UI when the window is moved to a different monitor.
3. If the issue persists only on certain Windows versions (e.g., Windows 11), file a bug report with the Qt Project and provide a minimal reproducible example.

Practical Verification Checklist

• Run the minimal example with high‑DPI scaling enabled.
• Confirm that QGuiApplication::devicePixelRatio() matches the system DPI factor.
• Use the DPI simulation in Qt Creator to compare layout against design pixel values.
• Check that icons render sharp at the current scaling level.
• Change Windows scaling while the app is running and verify that no controls jump or overlap.

Limitations

• Per‑monitor scaling changes on multi‑monitor setups are not fully handled by this guide. Additional logic may be required.
• Qt Widgets use a different scaling mechanism; this guide focuses exclusively on Qt Quick Controls 2.
• Older Windows versions (pre‑10) may report different DPI values and behave differently.

Conclusion

High‑DPI scaling on Windows can be subtle, but by following the ordered diagnostic steps above and applying the targeted fixes, you can restore sharp text, correct layout, and proper icon scaling in Qt Quick Controls 2 applications. Always verify with a minimal example before deploying to production.