Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Static Public Member Functions | Friends | List of all members
QHighDpiScaling Class Reference

Collection of utility functions for UI scaling. More...

#include <qhighdpiscaling_p.h>

+ Collaboration diagram for QHighDpiScaling:

Classes

struct  Point
 
struct  ScaleAndOrigin
 

Public Types

enum class  DpiAdjustmentPolicy { Unset , Enabled , Disabled , UpOnly }
 

Public Member Functions

 QHighDpiScaling ()=delete
 
 ~QHighDpiScaling ()=delete
 
 QHighDpiScaling (const QHighDpiScaling &)=delete
 
QHighDpiScaling & operator= (const QHighDpiScaling &)=delete
 
 QHighDpiScaling (QHighDpiScaling &&)=delete
 
QHighDpiScaling & operator= (QHighDpiScaling &&)=delete
 

Static Public Member Functions

static void initHighDpiScaling ()
 
static void updateHighDpiScaling ()
 
static void setGlobalFactor (qreal factor)
 
static void setScreenFactor (QScreen *screen, qreal factor)
 
static bool isActive ()
 
static ScaleAndOrigin scaleAndOrigin (const QPlatformScreen *platformScreen, Point position=Point{ Point::Invalid, QPoint() })
 
static ScaleAndOrigin scaleAndOrigin (const QScreen *screen, Point position=Point{ Point::Invalid, QPoint() })
 
static ScaleAndOrigin scaleAndOrigin (const QWindow *platformScreen, Point position=Point{ Point::Invalid, QPoint() })
 
template<typename C >
static qreal factor (C *context)
 
static QPoint mapPositionFromNative (const QPoint &pos, const QPlatformScreen *platformScreen)
 
static QPoint mapPositionToNative (const QPoint &pos, const QPlatformScreen *platformScreen)
 
static QDpi logicalDpi (const QScreen *screen)
 
static qreal roundScaleFactor (qreal rawFactor)
 

Friends

Q_GUI_EXPORT QDebug operator<< (QDebug, const ScreenFactor &)
 

Detailed Description

Collection of utility functions for UI scaling.

Since
5.6

\preliminary

QHighDpiScaling implements utility functions for high-dpi scaling for use on operating systems that provide limited support for native scaling, such as Windows, X11, and Android. In addition this functionality can be used for simulation and testing purposes.

The functions support scaling between the device independent coordinate system used by Qt applications and the native coordinate system used by the platform plugins. Intended usage locations are the low level / platform plugin interfacing parts of QtGui, for example the QWindow, QScreen and QWindowSystemInterface implementation.

There are now up to three active coordinate systems in Qt:

| Application Device Independent Pixels | devicePixelRatio | Qt Widgets | = | Qt Gui | |------------------------------------------------—| Qt Scale Factor | Qt Gui QPlatform* Native Pixels | * | Qt platform plugin | |------------------------------------------------—| OS Scale Factor | Display Device Pixels |

| (Graphics Buffers) |

This is an simplification and shows the main coordinate system. All layers may work with device pixels in specific cases: OpenGL, creating the backing store, and QPixmap management. The "Native Pixels" coordinate system is internal to Qt and should not be exposed to Qt users: Seen from the outside there are only two coordinate systems: device independent pixels and device pixels.

The devicePixelRatio seen by applications is the product of the Qt scale factor and the OS scale factor (see QWindow::devicePixelRatio()). The value of the scale factors may be 1, in which case two or more of the coordinate systems are equivalent. Platforms that (may) have an OS scale factor include macOS, iOS, Wayland, and Web(Assembly).

Note that the API implemented in this file do use the OS scale factor, and is used for converting between device independent and native pixels only.

Configuration Examples:

'Classic': Device Independent Pixels = Native Pixels = Device Pixels ------------------------------------------------— devicePixelRatio: 1 | Application / Qt Gui 100 x 100 | | | Qt Scale Factor: 1 | Qt Platform / OS 100 x 100 | | | OS Scale Factor: 1

| Display 100 x 100 |

'2x Apple Device': Device Independent Pixels = Native Pixels ------------------------------------------------— devicePixelRatio: 2 | Application / Qt Gui 100 x 100 | | | Qt Scale Factor: 1 | Qt Platform / OS 100 x 100 | |------------------------------------------------—| OS Scale Factor: 2

| Display 200 x 200 |

'Windows at 200': Native Pixels = Device Pixels ------------------------------------------------— devicePixelRatio: 2 | Application / Qt Gui 100 x 100 | |------------------------------------------------—| Qt Scale Factor: 2 | Qt Platform / OS 200 x 200 | | | OS Scale Factor: 1

| Display 200 x 200 |

Configuration

  • Enabling: In Qt 6, high-dpi scaling (the functionality implemented in this file) is always enabled. The Qt scale factor value is typically determined by the QPlatformScreen implementation - see below.

    There is one environment variable based opt-out option: set QT_ENABLE_HIGHDPI_SCALING=0. Keep in mind that this does not affect the OS scale factor, which is controlled by the operating system.

  • Qt scale factor value: The Qt scale factor is the product of the screen scale factor and the global scale factor, which are independently either set or determined by the platform plugin. Several APIs are offered for this, targeting both developers and end users. All scale factors are of type qreal.

    1) Per-screen scale factors

    Per-screen scale factors are computed based on logical DPI provided by by the platform plugin.

    The platform plugin implements DPI accessor functions: QDpi QPlatformScreen::logicalDpi() QDpi QPlatformScreen::logicalBaseDpi()

    QHighDpiScaling then computes the per-screen scale factor as follows: 

    factor = logicalDpi / logicalBaseDpi

    Alternatively, QT_SCREEN_SCALE_FACTORS can be used to set the screen scale factors.

    2) The global scale factor

    The QT_SCALE_FACTOR environment variable can be used to set a global scale factor which applies to all application windows. This allows developing and testing at any DPR, independently of available hardware and without changing global desktop settings.

  • Rounding

    Qt 6 does not round scale factors by default. Qt 5 rounds the screen scale factor to the nearest integer (except for Qt on Android which does not round).

    The rounding policy can be set by the application, or on the environment:

    Application (C++): QGuiApplication::setHighDpiScaleFactorRoundingPolicy() User (environment): QT_SCALE_FACTOR_ROUNDING_POLICY

    Note that the OS scale factor, and global scale factors set with QT_SCALE_FACTOR are never rounded by Qt.

    C++ API Overview

  • Coordinate Conversion ("scaling")

    The QHighDpi namespace provides several functions for converting geometry between the device independent and native coordinate systems. These should be used when calling "QPlatform*" API from QtGui. Callers are responsible for selecting a function variant based on geometry type: 

      Type                        From Native                              To Native

    local : QHighDpi::fromNativeLocalPosition() QHighDpi::toNativeLocalPosition() global (screen) : QHighDpi::fromNativeGlobalPosition() QHighDpi::toNativeGlobalPosition() QWindow::geometry() : QHighDpi::fromNativeWindowGeometry() QHighDpi::toNativeWindowGeometry() sizes, margins, etc : QHighDpi::fromNativePixels() QHighDpi::toNativePixels()

    The conversion functions take two arguments; the geometry and a context:

    QSize nativeSize = toNativePixels(deviceIndependentSize, window);

    The context is usually a QWindow instance, but can also be a QScreen instance, or the corresponding QPlatform classes.

  • Activation

    QHighDpiScaling::isActive() returns true iff Qt high-dpi scaling is enabled (e.g. with AA_EnableHighDpiScaling) AND there is a Qt scale factor != 1

    (the value of the OS scale factor does not affect this API)

  • Calling QtGui from the platform plugins

    Platform plugin code should be careful about calling QtGui geometry accessor functions like geometry():

    QRect r = window->geometry();

    In this case the returned geometry is in the wrong coordinate system (device independent instead of native pixels). Fix this by adding a conversion call:

    QRect r = QHighDpi::toNativeWindowGeometry(window->geometry());

    (Also consider if the call to QtGui is really needed - prefer calling QPlatform* API.)

Definition at line 38 of file qhighdpiscaling_p.h.

Member Enumeration Documentation

◆ DpiAdjustmentPolicy

enum class QHighDpiScaling::DpiAdjustmentPolicy
strong
Enumerator
Unset 
Enabled 
Disabled 
UpOnly 

Definition at line 41 of file qhighdpiscaling_p.h.

Constructor & Destructor Documentation

◆ QHighDpiScaling() [1/3]

QHighDpiScaling::QHighDpiScaling ( )
delete

◆ ~QHighDpiScaling()

QHighDpiScaling::~QHighDpiScaling ( )
delete

◆ QHighDpiScaling() [2/3]

QHighDpiScaling::QHighDpiScaling ( const QHighDpiScaling & )
delete

◆ QHighDpiScaling() [3/3]

QHighDpiScaling::QHighDpiScaling ( QHighDpiScaling && )
delete

Member Function Documentation

◆ factor()

template<typename C >
static qreal QHighDpiScaling::factor ( C * context)
inlinestatic

Definition at line 84 of file qhighdpiscaling_p.h.

References context.

Referenced by QWindowsOleDropSource::createCursors(), QBackingStorePrivate::deviceIndependentToNativeFactor(), QScreen::devicePixelRatio(), QHighDpi::fromNative(), QHighDpi::fromNativeLocalExposedRegion(), QHighDpi::fromNativeLocalPosition(), QHighDpi::fromNativeLocalRegion(), QHighDpi::fromNativeScreenGeometry(), QScreen::grabWindow(), QXcbWindow::handleConfigureNotifyEvent(), QXcbWindow::hide(), QPlatformWindow::initialGeometry(), mapPositionFromNative(), mapPositionToNative(), QWindowsCursor::pixmapWindowCursor(), QXcbWindow::propagateSizeHints(), setGlobalFactor(), setScreenFactor(), QHighDpi::toNativeLocalPosition(), QHighDpi::toNativeLocalRegion(), toNativeSizeConstrained(), QWindowPrivate::updateDevicePixelRatio(), QScreenPrivate::updateGeometry(), and updateHighDpiScaling().

+ Here is the caller graph for this function:

◆ initHighDpiScaling()

void QHighDpiScaling::initHighDpiScaling ( )
static

Definition at line 402 of file qhighdpiscaling.cpp.

References dpiAdjustmentPolicyEnvVar, dpiAdjustmentPolicyLookup, enableHighDpiScalingEnvVar, joinEnumValues(), lookupDpiAdjustmentPolicy(), lookupScaleFactorRoundingPolicy(), qCDebug, qEnvironmentVariableOptionalByteArray(), qEnvironmentVariableOptionalInt(), qEnvironmentVariableOptionalReal(), qEnvironmentVariableOptionalString(), qFuzzyCompare(), qWarning, scaleFactorEnvVar, scaleFactorRoundingPolicyEnvVar, scaleFactorRoundingPolicyLookup, screenFactorsEnvVar, QGuiApplication::setHighDpiScaleFactorRoundingPolicy(), Qt::Unset, Unset, and usePhysicalDpiEnvVar.

Referenced by QGuiApplicationPrivate::createPlatformIntegration().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ isActive()

static bool QHighDpiScaling::isActive ( )
inlinestatic

Definition at line 61 of file qhighdpiscaling_p.h.

References m_active.

Referenced by QBackingStore::beginPaint(), fromNativeGlobalPixels(), QHighDpi::fromNativeLocalExposedRegion(), loadAndroidStyle(), QScreen::logicalDotsPerInch(), QScreen::logicalDotsPerInchX(), QScreen::logicalDotsPerInchY(), QBackingStore::paintDevice(), QHighDpi::scale(), QHighDpi::scale(), toNativeSizeConstrained(), and QPlatformWindow::windowSizeIncrement().

+ Here is the caller graph for this function:

◆ logicalDpi()

QDpi QHighDpiScaling::logicalDpi ( const QScreen * screen)
static

Definition at line 636 of file qhighdpiscaling.cpp.

References QScreen::handle(), QPlatformScreen::logicalDpi(), QPlatformScreen::overrideDpi(), roundScaleFactor(), and screen.

Referenced by QScreen::logicalDotsPerInch(), QScreen::logicalDotsPerInchX(), and QScreen::logicalDotsPerInchY().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mapPositionFromNative()

QPoint QHighDpiScaling::mapPositionFromNative ( const QPoint & pos,
const QPlatformScreen * platformScreen )
static

Definition at line 593 of file qhighdpiscaling.cpp.

References factor(), QPlatformScreen::geometry(), and pos.

Referenced by QDockWidgetPrivate::mouseMoveEvent(), and QXcbDrag::move().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mapPositionToNative()

QPoint QHighDpiScaling::mapPositionToNative ( const QPoint & pos,
const QPlatformScreen * platformScreen )
static

Definition at line 584 of file qhighdpiscaling.cpp.

References factor(), QPlatformScreen::geometry(), and pos.

Referenced by QDockWidgetPrivate::mouseMoveEvent(), and QQmlPreviewPosition::takePosition().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ operator=() [1/2]

QHighDpiScaling & QHighDpiScaling::operator= ( const QHighDpiScaling & )
delete

◆ operator=() [2/2]

QHighDpiScaling & QHighDpiScaling::operator= ( QHighDpiScaling && )
delete

◆ roundScaleFactor()

qreal QHighDpiScaling::roundScaleFactor ( qreal rawFactor)
static

Definition at line 332 of file qhighdpiscaling.cpp.

References Qt::Ceil, Qt::Floor, QGuiApplication::highDpiScaleFactorRoundingPolicy(), Qt::PassThrough, qCeil(), qFloor(), qMax(), qRound(), Qt::Round, Qt::RoundPreferFloor, and Qt::Unset.

Referenced by QWindowsWindow::dpiRelativeScale(), logicalDpi(), and updateHighDpiScaling().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ scaleAndOrigin() [1/3]

QHighDpiScaling::ScaleAndOrigin QHighDpiScaling::scaleAndOrigin ( const QPlatformScreen * platformScreen,
QHighDpiScaling::Point position = Point{ Point::Invalid, QPoint() } )
static

Definition at line 723 of file qhighdpiscaling.cpp.

References QPlatformScreen::geometry(), position(), and Q_UNUSED.

Referenced by QHighDpi::fromNativeGlobalPosition(), QHighDpi::fromNativePixels(), QHighDpi::fromNativeWindowGeometry(), scaleAndOrigin(), scaleAndOrigin(), QHighDpi::toNativeGlobalPosition(), QHighDpi::toNativePixels(), and QHighDpi::toNativeWindowGeometry().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ scaleAndOrigin() [2/3]

QHighDpiScaling::ScaleAndOrigin QHighDpiScaling::scaleAndOrigin ( const QScreen * screen,
QHighDpiScaling::Point position = Point{ Point::Invalid, QPoint() } )
static

Definition at line 733 of file qhighdpiscaling.cpp.

References QScreen::handle(), position(), Q_UNUSED, scaleAndOrigin(), and screen.

+ Here is the call graph for this function:

◆ scaleAndOrigin() [3/3]

QHighDpiScaling::ScaleAndOrigin QHighDpiScaling::scaleAndOrigin ( const QWindow * platformScreen,
QHighDpiScaling::Point position = Point{ Point::Invalid, QPoint() } )
static

Definition at line 743 of file qhighdpiscaling.cpp.

References position(), QGuiApplication::primaryScreen, scaleAndOrigin(), screen, and window().

+ Here is the call graph for this function:

◆ setGlobalFactor()

void QHighDpiScaling::setGlobalFactor ( qreal factor)
static

Definition at line 535 of file qhighdpiscaling.cpp.

References QGuiApplication::allWindows(), factor(), qCDebug, qFuzzyCompare(), qWarning, screen, and QGuiApplication::screens().

+ Here is the call graph for this function:

◆ setScreenFactor()

void QHighDpiScaling::setScreenFactor ( QScreen * screen,
qreal factor )
static

Definition at line 562 of file qhighdpiscaling.cpp.

References factor(), QScreen::name, qCDebug, qFuzzyCompare(), scaleFactorProperty, screen, and QObject::setProperty().

Referenced by updateHighDpiScaling().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ updateHighDpiScaling()

void QHighDpiScaling::updateHighDpiScaling ( )
static

Definition at line 488 of file qhighdpiscaling.cpp.

References factor(), QScreen::handle(), i, QScreen::name, qCDebug, qFuzzyCompare(), roundScaleFactor(), screen, QGuiApplication::screens(), and setScreenFactor().

Referenced by QWindowSystemInterface::handleScreenAdded(), QWindowSystemInterface::handleScreenLogicalDotsPerInchChange(), and QGuiApplicationPrivate::processScreenLogicalDotsPerInchChange().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

Friends And Related Symbol Documentation

◆ operator<<

Q_GUI_EXPORT QDebug operator<< ( QDebug debug,
const ScreenFactor & factor )
friend

Definition at line 757 of file qhighdpiscaling.cpp.

The documentation for this class was generated from the following files: