Scaling Qt GUIs for HiDPI Displays: Beyond QPaintDevice::devicePixelRatio()

Purpose

• In high-resolution (HiDPI) displays, also known as Retina displays, multiple physical pixels are packed into a single logical pixel. This function helps Qt adapt your application's UI to these displays by providing the ratio between physical and logical pixels.

Functionality

• A ratio greater than 1 signifies a HiDPI display, where multiple physical pixels make up a single logical pixel.
• A ratio of 1 indicates a one-to-one mapping between physical and logical pixels (typical for non-HiDPI displays).
• It returns a qreal value, which is a floating-point representation of the device pixel ratio.
• QPaintDevice::devicePixelRatio() is a member function of the QPaintDevice class, which is the base class for objects that can be painted on using QPainter in Qt.

Example

#include <QGuiApplication>
#include <QWidget>
#include <QLabel>
#include <QHBoxLayout>

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

    QWidget window;
    QHBoxLayout *layout = new QHBoxLayout(&window);

    QLabel *label = new QLabel("This text appears on screen");
    layout->addWidget(label);

    // Get the device pixel ratio
    qreal devicePixelRatio = label->devicePixelRatio();

    // Adjust font size for HiDPI displays (optional)
    if (devicePixelRatio > 1.0) {
        QFont font = label->font();
        font.setPixelSize(font.pointSize() * devicePixelRatio);
        label->setFont(font);
    }

    window.setLayout(layout);
    window.show();

    return app.exec();
}

1. The code creates a simple Qt application with a window and a label.
2. It retrieves the device pixel ratio using label->devicePixelRatio().
3. If the ratio is greater than 1 (HiDPI display), the code adjusts the font size of the label proportionally to maintain a consistent visual appearance across different display resolutions.

Benefits

• Using QPaintDevice::devicePixelRatio() ensures that your Qt GUI elements scale appropriately on HiDPI displays, leading to a sharper and more visually appealing user experience.

• Qt provides mechanisms for automatically handling HiDPI displays, but QPaintDevice::devicePixelRatio() gives you more fine-grained control if needed.
• Consider using other functions like logicalDpiX() and logicalDpiY() to obtain the logical dots per inch (DPI) for the device.

---

Scaling an Image

#include <QGuiApplication>
#include <QWidget>
#include <QLabel>
#include <QPixmap>
#include <QHBoxLayout>

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

    QWidget window;
    QHBoxLayout *layout = new QHBoxLayout(&window);

    QLabel *label = new QLabel;
    QPixmap image("image.png"); // Replace with your image path

    // Scale the image based on device pixel ratio
    qreal devicePixelRatio = label->devicePixelRatio();
    image.setDevicePixelRatio(devicePixelRatio);
    label->setPixmap(image.scaled(image.size() * devicePixelRatio, Qt::KeepAspectRatio));

    layout->addWidget(label);

    window.setLayout(layout);
    window.show();

    return app.exec();
}

This code retrieves the device pixel ratio, sets it on the image, and then scales the image while maintaining its aspect ratio. This ensures the image appears sharp on HiDPI displays.

Scaling Multiple UI Elements

#include <QGuiApplication>
#include <QWidget>
#include <QPushButton>
#include <QLabel>
#include <QVBoxLayout>

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

    QWidget window;
    QVBoxLayout *layout = new QVBoxLayout(&window);

    QLabel *label = new QLabel("This text scales");
    QPushButton *button = new QPushButton("Scaled Button");

    // Get device pixel ratio
    qreal devicePixelRatio = window.devicePixelRatio();

    // Adjust font sizes and margins proportionally
    QFont font = label->font();
    font.setPixelSize(font.pointSize() * devicePixelRatio);
    label->setFont(font);
    button->setFont(font);

    layout->addWidget(label);
    layout->addWidget(button);

    // Adjust margins (optional)
    layout->setSpacing(layout->spacing() * devicePixelRatio);

    window.setLayout(layout);
    window.show();

    return app.exec();
}

This example scales both the font size of a label and a button based on the device pixel ratio. It also optionally adjusts the layout spacing for a more consistent visual appearance.

---

Qt's Automatic High-DPI Scaling

Qt provides built-in mechanisms for handling HiDPI displays. By enabling the Qt::AA_EnableHighDpiScaling application attribute, Qt automatically scales fonts and other UI elements based on the system's DPI information. This is often the easiest and most recommended approach for most scenarios.

#include <QApplication>

int main(int argc, char *argv[]) {
  QApplication app(argc, argv);
  app.setAttribute(Qt::AA_EnableHighDpiScaling);

  // ... Your application code here ...

  return app.exec();
}

Layout Management

Qt offers powerful layout classes like QHBoxLayout and QVBoxLayout that can automatically adjust the size and position of child widgets based on their relative proportions. This approach helps maintain a consistent layout across different display resolutions without relying on manual scaling calculations.

Stylesheets

Qt Stylesheets allow you to define the appearance of your widgets using CSS-like syntax. You can leverage units like px (pixels), pt (points), and em (relative to font size) to create layouts that adapt to different DPI settings.

QLabel {
  font-size: 16px; /* Base font size */
}

QPushButton {
  font-size: 1.2em;  /* Font size relative to base font */
}

logicalDpiX() and logicalDpiY()

These functions provide the logical DPI (dots per inch) values for the X and Y axes, respectively. You can use these values along with the device pixel ratio to perform custom scaling calculations if needed.

• QPaintDevice::devicePixelRatio()
  Opt for this function when you need precise control over individual UI element scaling beyond Qt's automatic mechanisms.
• Stylesheets
  Consider stylesheets for defining a consistent look and feel across different DPI environments.
• Layout management
  Prioritize layouts for responsive UIs without manual scaling.
• Automatic scaling
  Use Qt::AA_EnableHighDpiScaling for the simplest and most common approach.