qiurui
/
qtdoc
mirror of https://github.com/qt/qtdoc.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge "Merge remote-tracking branch 'origin/5.13' into 5.14"

This commit is contained in:
Qt Forward Merge Bot 2019-10-15 03:03:31 +02:00 committed by Paul Wicking
parent 65a94384c6 69716f721c
commit dbc658903a
5 changed files with 144 additions and 135 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

248
doc/src/highdpi.qdoc
View File

@ -27,95 +27,89 @@
/*!
\page highdpi.html
\title High DPI Displays
\brief Concepts of High DPI Displays
\brief Describes the concepts in high DPI displays.
\section1 High DPI Displays
High DPI displays have increased pixel density, compared to standard DPI displays.
High DPI Displays are displays with increased pixel density compared to standard
DPI displays.
Pixel density is measured in Dots per Inch (DPI) or Pixels per Inch (PPI), and is determined by
the number of display pixels and their size. Consequently, the number of pixels alone isn't
enough to determine if a display falls into the high-DPI category.
This pixel density is measured in Dots per Inch (DPI) or Pixels Per Inch (PPI),
and is determined by the number of display pixels and physical size. This means that
the number of pixels alone is not enough to determine if a display falls into the
high-DPI category.
A 4K monitor has a fixed number of pixels (~8M), however its DPI varies between 185 (23 inches)
and 110 (40 inches). The former is around twice the standard 96 DPI desktop resolution; the
latter barely exceeds this resolution.
A 4K monitor has a fixed number of pixels (~8M), however the DPI varies between 185
(23 inch) and 110 (40 inch). The former is around 2x standard 96 DPI desktop resolution,
while the latter is barely over it.
\section2 Challenges with High DPI
\section2 Issues with High DPI
High DPI Displays cause a number of issues for existing applications:
High DPI displays bring about some challenges for existing applications:
\list
\li Applications using UI designs with fixed coordinates look small.
The combination of font size specification in points and other sizes in
pixels is particularly problematic since points are independent of the monitor
resolution. For example, a frame of 40x20 pixels around the text "hello"
using a 12pt font looks correct on low resolution monitors,
but the frame will be too small on high DPI monitors, causing the text
to be clipped.
\li \b{Applications using UI designs with fixed coordinates look small}
\br The combination of specifying font size in points and other sizes in pixels is
particularly problematic because points are independent from the monitor's resolution.
For example, suppose we have a frame of 40x20 pixels around the text "hello". If we use
a 12pt font, it would look correct on low resolution monitors. But, on high DPI
monitors, the frame would be too small, resulting in the text being clipped.
\li Applications must adapt to situations where users have multiple displays with
varying resolution. For example, they might use a 4K monitor for the
document window of an image editor and a low resolution monitor for the
tool box.
\li \b{Applications must adapt to situations where users have multiple displays with
varying resolutions}
\br For example, a user might use a 4K monitor for the document window of an image
editor but a low resolution monitor for the tool box.
\endlist
The traditional approach to supporting high DPI has been one where Qt scaled fonts
automatically, and then provided a DPI value that application code could use
to scale the rest of the UI.
Traditionally, to support high DPI, Qt scales fonts automatically and provides a DPI value
that application code can use to scale the rest of the UI.
\section2 Qt High DPI Support Overview
\section2 High DPI Support on a System Level
Qt supports a high DPI mode where the main coordinate system is virtualized and
made independent of the display pixel density. This mode is implemented by some
operating systems (\macos, iOS). In addition, Qt contains an implementation which
may be used where operating system support is missing.
Qt supports a high DPI mode where the main coordinate system is virtualized and made independent
from the display pixel density. Some operating systems, like \macOS and iOS implement this mode.
Additionally, if an operating system doesn't support this mode, Qt has an implementation to
fallback on.
Geometry is now specified in device independent pixels. This includes widget and
item geometry, event geometry, desktop, window and screen geometry, and animation
velocities. Rendered output is in device pixels, which corresponds to the display
resolution. The ratio between the device independent and device pixel coordinate
systems is the devicePixelRatio.
Now, geometry is specified in device independent pixels. This includes widget and item geometry,
event geometry, desktop, window and screen geometry, as well as animation velocities. The output
is rendered in device pixels, which corresponds to the display resolution. The \e devicePixelRatio
is the ratio between the device independent pixels and the device pixel coordinate system.
Applications mostly work with device independent pixels. Notable exceptions are
OpenGL and code that works with raster graphics.
Typically, most applications work with device independent pixels; except for OpenGL and code for
raster graphics.
\section2 Operating System Support
The operating systems supported by Qt offer the following support for high DPI displays:
The Qt-supported operating systems offer the following for high DPI displays:
\section3 \macos and iOS
The Apple platforms implement scaling and coordinate system virtualization in the
in the operating system. Normally, no special configuration is required.
The Apple platforms implement scaling and coordinate system virtualization in the operating
system. Normally, no special configuration is required.
On \macos, high-DPI support is enabled by settings in the \c{Info.plist} file; so make sure
these settings are present.
\note On \macos, high-DPI support is enabled by settings in the Info.plist file.
Make sure they are present.
\code
<key>NSPrincipalClass</key>
<string>NSApplication</string>
<key>NSHighResolutionCapable</key>
<string>True</string>
\endcode
Newer versions of qmake will generate Info.plist's with the NSPrincipalClass key,
which is sufficient since NSHighResolutionCapable is true by default.
\note \macos and iOS may apply further virtualization such that device pixels do not
correspond 1:1 to display pixels. This happens on the iPhone 6+ and on \macos configured
with 'display scaling' enabled.
Newer versions of qmake will generate an \c{Info.plist} file with the NSPrincipalClass key;
this is sufficient since NSHighResolutionCapable is true by default.
\note Both \macos and iOS may apply further virtualization, such that device pixels no longer
correspond to display pixels 1:1. This happens on the iPhone 6+ and on \macos configured with
"display scaling" enabled.
\section3 Microsoft Windows
\section4 Scaling
\b Scaling
The user can choose a scaling factor from the control panel or via context menu.
This works by making the functions for querying the system metrics return
different values for standard font sizes, sizes of window borders, and so on.
It does not perform any actual scaling.
Users choose a scaling factor from the \uicontrol{Control Panel} or via the context menu. This
works by making the functions for querying the system metrics return different values for
standard font sizes, sizes of window borders, and so on. It doesn't perform any actual scaling.
\section4 DPI Awareness
\b DPI Awareness
An application on Windows can assume one of the following levels of "DPI Awareness":
@ -126,82 +120,78 @@
\row
\li DPI Unaware
\li This level has been introduced in Windows Vista. Windows will pretend to the
application that it is running on a standard display of 96 DPI of 1920x1080
and scale the application accordingly. It is intended to accommodate older
applications designed for low DPI displays. Some artifacts may result from
this type of scaling.
\li This level was introduced in Windows Vista. To the application, Windows pretends
as if it's running on a standard display of 96 DPI of 1920x1080 and scales the
application accordingly. It's intended to accommodate older applications designed
for low DPI displays. This type of scaling may result in some artifacts.
\row
\li System-DPI Aware
\li This level has been introduced in Windows Vista. It differs from
\e{Per-Monitor DPI Aware} only when multiple monitors are connected.
Windows will calculate a scaling suitable for all connected monitors.
\li This level was introduced in Windows Vista. It differs from
\e{Per-Monitor DPI Aware} only when multiple monitors are connected. Windows
calculates a scaling that's suitable for all monitors connected.
\row
\li Per-Monitor DPI Aware
\li This level has been introduced in Windows 8.1. Windows does not perform
any scaling at all.
\li This level was introduced in Windows 8.1. Windows does not perform any scaling at
all.
\endtable
Qt applications by default are \e{Per-Monitor DPI Aware} on Windows 8.1 or \e{System-DPI Aware}
on older versions of Windows. As of Qt 5.4, the level can be specified by passing a parameter
to the platform plugin (see \l{Using qt.conf}):
By default, Qt applications are set to \e{Per-Monitor DPI Aware} on Windows 8.1 or
\e{System-DPI Aware} on older Windows versions. As of Qt 5.4, this level can be specified via
a parameter to the platform plugin:
\code
<application> -platform windows:dpiawareness=0,1,2
\endcode
For more information, see \l{Using qt.conf}.
\section2 High DPI Support in Qt
Qt provides the following ways for you to handle high DPI support in your application.
\list
\li Ability to provide pixmaps or artwork for high resolution:
\li The ability to provide pixmaps or artwork for high resolution. For more details,
see \l{Drawing High Resolution Versions of Pixmaps and Images}.
\li Qt 5.6 supports cross-platform high-DPI scaling for legacy applications,
similar to the scaling done natively by \macos. This allows applications written
for low-DPI screens to run unchanged on high-DPI devices. This feature is
opt-in, and can be enabled by the following environment variables:
\li Qt 5.6 supports cross-platform high-DPI scaling for legacy applications, similar to
the scaling done natively in \macos. This allows applications written for low DPI
screens to run unchanged on high DPI devices. This feature is opt-in, and can be
enabled using the following environment variables:
\list
\li \c QT_AUTO_SCREEN_SCALE_FACTOR [boolean] enables automatic scaling,
based on the pixel density of the monitor. This will not change the size
of point sized fonts, since point is a physical unit of measure. Multiple
screens may get different scale factors.
based on the monitor's pixel density. This won't change the size of point-sized
fonts, since point is a physical measurement unit. Multiple screens may get
different scale factors.
\li \c QT_SCALE_FACTOR [numeric] defines a global scale
factor for the whole application, including point sized fonts.
\li \c QT_SCALE_FACTOR [numeric] defines a global scale factor for the whole
application, including point-sized fonts.
\li \c QT_SCREEN_SCALE_FACTORS [list] specifies scale factors
for each screen. This will not change the size
of point sized fonts. This environment variable is
\li \c QT_SCREEN_SCALE_FACTORS [list] specifies scale factors for each screen.
This won't change the size of point-sized fonts. The environment variable is
mainly useful for debugging, or to work around monitors with wrong
\l {https://en.wikipedia.org/wiki/Extended_Display_Identification_Data}
{EDID information}(Extended Display Identification Data).
The format can be either a semicolon-separated list of scale
factors in the same order as QGuiApplication::screens(), or a
semicolon-separated list of \c name=value pairs, where \c
name is the same as QScreen::name().
The format can either be a semicolon-separated list of scale factors in the same
order as QGuiApplication::screens(), or a semicolon-separated list of \c name=value
pairs, where \c name is the same as QScreen::name().
\endlist
\endlist
While the \macOS style fully supports high-DPI, the Windows desktop style currently has
some limitations with certain scale factors. In these cases, consider using the Fusion
style instead, which supports high-DPI in all cases.
While the macOS style fully supports high-DPI, the Windows desktop style
currently has some limitations with certain scale factors. In these cases,
consider using the Fusion style instead, which aims to support high-DPI in
all cases.
\note Non-integer scale factors may cause significant scaling/painting artifacts.
\note Non-integer scale factors may cause significant
scaling/painting artifacts.
\li The \c Qt::AA_EnableHighDpiScaling application attribute, introduced in Qt 5.6,
enables automatic scaling based on the monitor's pixel density.
\li The application attribute \c Qt::AA_EnableHighDpiScaling, introduced in Qt 5.6,
enables automatic scaling based on the pixel density of the monitor.
\li The application attribute \c Qt::AA_DisableHighDpiScaling, introduced in Qt 5.6,
turns off all scaling. This is intended for applications that need to use
actual window system coordinates, regardless of environment variables. This
attribute takes priority over Qt::AA_EnableHighDpiScaling.
\li The \c Qt::AA_DisableHighDpiScaling application attribute, introduced in Qt 5.6,
turns off all scaling. This is intended for applications that require actual window
system coordinates, regardless of environment variables. This attribute takes priority
over Qt::AA_EnableHighDpiScaling.
\li The QT_ENABLE_HIGHDPI_SCALING environment variable, introduced in Qt 5.14,
enables automatic scaling based on the pixel density of the monitor. Replaces
@ -215,30 +205,32 @@
\c{PassThrough}. See the Qt::HighDpiScaleFactorRoundingPolicy enum documentation
for a full description of the options.
\li An experimental implementation of high-DPI scaling was introduced in Qt 5.4.
It was enabled by the environment variable \c QT_DEVICE_PIXEL_RATIO, which
could be set to a numerical scale factor or \c "auto". This variable is
deprecated in Qt 5.6.
\li In Qt 5.4, there was an experimental implementation of high DPI scaling introduced via
the \c QT_DEVICE_PIXEL_RATIO environment variable, that you could set to a numerical
scale factor or \c auto. This variable was deprecated in Qt 5.6.
\endlist
\section2 Migration of Existing Applications
\section2 Migrate Existing Applications
In order to get an application designed for low DPI values running on a high
resolution monitors quickly, consider one of the scaling options (let the
application run as \e{DPI Unaware} on Windows or set the environment
variable \c QT_AUTO_SCREEN_SCALE_FACTOR to \c "1". These options may incur
some scaling or painting artifacts, though.
To get an application designed for low DPI values running on high resolution monitors quickly,
consider one of the following:
In the longer term, the application should be adapted to run unmodified:
\list
\li let the application run as \e{DPI Unaware} on Windows
\li set the \c QT_AUTO_SCREEN_SCALE_FACTOR environment variable to \c 1.
However, these options may result in some scaling or painting artifacts.
In the long term, the application should be adapted to run unmodified:
\list
\li Always use the qreal versions of the QPainter drawing API.
\li Size windows and dialogs in relation to the screen size.
\li Replace hard-coded sizes in layouts and drawing code
by values calculated from font metrics or screen size.
\li Size windows and dialogs in relation to the corresponding screen size.
\li Replace hard-coded sizes in layouts and drawing code with values calculated from font
metrics or screen size.
\endlist
\section2 Glossary Of High DPI Terms
\section2 Glossary
\table
\header
@ -247,34 +239,28 @@
\row
\li Device Independent Pixels
\li Pixels used by application (user space), subject to scaling by the operating
\li The pixels that an application uses (user space), subject to scaling by the operating
system or Qt.
\row
\li Device Pixels
\li Pixels of the display device.
\li The display device's pixels.
\row
\li Device Pixel Ratio
\li Scale factor applied by the operating system or Qt.
\li The scale factor that either the operating system or Qt applies.
\row
\li Logical DPI
\li Resolution used for converting font sizes defined in points to font sizes in pixels.
Typically one of the standard values 96, 128, .. 192.
\li The resolution used to convert font sizes defined in points to font sizes in pixels.
The standard values are 96, 128, ... 192.
\row
\li Physical DPI
\li Physical resolution obtained by dividing the size of the monitor by
the number of pixels.
\row
\li Retina Display
\li See \l{http://en.wikipedia.org/wiki/Retina_Display}{Wikipedia on Retina Displays}
\li The physical resolution obtained by dividing the size of the monitor by the number
of pixels.
\row
\li User Space
\li The coordinate space the application uses (Device Independent Pixels).
\li The coordinate space that an application uses in Device Independent Pixels.
\endtable
*/

9
doc/src/platforms/linux.qdoc
View File

@ -1,6 +1,6 @@
/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Copyright (C) 2019 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
@ -446,6 +446,13 @@
\c LD_LIBRARY_PATH environment variable to include
\c{/usr/local/Qt-%VERSION%/lib}. On Linux with GCC this step
is not needed.
\section1 Step 5: Build the Qt Documentation
For the Qt reference documentation to be available in \l {Qt Assistant},
you must build it separately:
\snippet snippets/code/doc_src_installation.qdoc 24
*/
/*!

11
doc/src/platforms/macos.qdoc
View File

@ -1,6 +1,6 @@
/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Copyright (C) 2019 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
@ -363,7 +363,14 @@
If you use a different shell, please modify your environment
variables accordingly.
\b {That's all. Qt is now installed.}
\b {Qt is now installed.}
\section1 Step 5: Build the Qt Documentation
For the Qt reference documentation to be available in \l {Qt Assistant}, you
must build it separately:
\snippet snippets/code/doc_src_installation.qdoc 24
\section1 Limitations

8
doc/src/platforms/windows.qdoc
View File

@ -1214,4 +1214,12 @@
\l{jom} is a replacement for \c nmake which makes use of all CPU cores
and thus speeds up building.
\section1 Step 5: Build the Qt Documentation
For the Qt reference documentation to be available in \l {Qt Assistant},
you must build it separately:
\code
nmake docs
\endcode
*/

3
doc/src/snippets/code/doc_src_installation.qdoc
View File

@ -1,6 +1,6 @@
/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Copyright (C) 2019 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
@ -163,6 +163,7 @@ nmake install
//! [24]
make docs
//! [24]
//! [25]