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:

| (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 QHash< Key, T >::clear(), QByteArray::constData(), 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(), hintingPreferenceToRenderingMode(), 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(), pos, and QRect::topLeft().

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(), pos, and QRect::topLeft().

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(), QWindowsWindow::moveTransientChildren(), 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(), Q_UNUSED, and QRect::topLeft().

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(), QHash< Key, T >::insert(), 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(), 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:

qtbase/src/gui/kernel/qhighdpiscaling_p.h
qtbase/src/gui/kernel/qhighdpiscaling.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

| (Graphics Buffers) |

| Display 100 x 100 |

| Display 200 x 200 |

| Display 200 x 200 |

Member Enumeration Documentation

◆ DpiAdjustmentPolicy

Constructor & Destructor Documentation

◆ QHighDpiScaling() [1/3]

◆ ~QHighDpiScaling()

◆ QHighDpiScaling() [2/3]

◆ QHighDpiScaling() [3/3]

Member Function Documentation

◆ factor()

◆ initHighDpiScaling()

◆ isActive()

◆ logicalDpi()

◆ mapPositionFromNative()

◆ mapPositionToNative()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ roundScaleFactor()

◆ scaleAndOrigin() [1/3]

◆ scaleAndOrigin() [2/3]

◆ scaleAndOrigin() [3/3]

◆ setGlobalFactor()

◆ setScreenFactor()

◆ updateHighDpiScaling()

Friends And Related Symbol Documentation

◆ operator<<