From f85f3acd7878f49f0878644905ca27ceb7bc0775 Mon Sep 17 00:00:00 2001 From: Friedemann Kleint Date: Tue, 26 Aug 2014 09:23:43 +0200 Subject: Document loading of high resolution versions of images. Task-number: QTBUG-38858 Change-Id: I87ee18b66e137f5f5c01d77910f1a7f256b85e18 Reviewed-by: Alessandro Portale --- src/gui/image/qicon.cpp | 10 ++++++++-- src/gui/image/qimage.cpp | 7 ++++--- src/gui/image/qimagereader.cpp | 14 ++++++++++++++ src/gui/image/qpixmap.cpp | 7 ++++--- 4 files changed, 30 insertions(+), 8 deletions(-) (limited to 'src/gui/image') diff --git a/src/gui/image/qicon.cpp b/src/gui/image/qicon.cpp index ac95222c99..1e4a9ebe8c 100644 --- a/src/gui/image/qicon.cpp +++ b/src/gui/image/qicon.cpp @@ -989,10 +989,16 @@ void QIcon::addPixmap(const QPixmap &pixmap, Mode mode, State state) QImageWriter::supportedImageFormats() functions to retrieve a complete list of the supported file formats. - Note: When you add a non-empty filename to a QIcon, the icon becomes + If a high resolution version of the image exists (identified by + the suffix \c @2x on the base name), it is automatically loaded + and added with the \e{device pixel ratio} set to a value of 2. + This can be disabled by setting the environment variable + \c QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING (see QImageReader). + + \note When you add a non-empty filename to a QIcon, the icon becomes non-null, even if the file doesn't exist or points to a corrupt file. - \sa addPixmap() + \sa addPixmap(), QPixmap::devicePixelRatio() */ void QIcon::addFile(const QString &fileName, const QSize &size, Mode mode, State state) { diff --git a/src/gui/image/qimage.cpp b/src/gui/image/qimage.cpp index 16696f611d..c3b4b1444a 100644 --- a/src/gui/image/qimage.cpp +++ b/src/gui/image/qimage.cpp @@ -1391,14 +1391,14 @@ QVector QImage::colorTable() const /*! Returns the device pixel ratio for the image. This is the - ratio between image pixels and device-independent pixels. + ratio between \e{device pixels} and \e{device independent pixels}. Use this function when calculating layout geometry based on the image size: QSize layoutSize = image.size() / image.devicePixelRatio() The default value is 1.0. - \sa setDevicePixelRatio() + \sa setDevicePixelRatio(), QImageReader */ qreal QImage::devicePixelRatio() const { @@ -1423,7 +1423,8 @@ qreal QImage::devicePixelRatio() const image size will take the ratio into account: QSize layoutSize = image.size() / image.devicePixelRatio() The net effect of this is that the image is displayed as - high-dpi image rather than a large image. + high-DPI image rather than a large image + (see \l{Drawing High Resolution Versions of Pixmaps and Images}). \sa devicePixelRatio() */ diff --git a/src/gui/image/qimagereader.cpp b/src/gui/image/qimagereader.cpp index 3c75202766..3bf002373c 100644 --- a/src/gui/image/qimagereader.cpp +++ b/src/gui/image/qimagereader.cpp @@ -74,6 +74,8 @@ that occurred, or errorString() to get a human readable description of what went wrong. + \section1 Formats + Call supportedImageFormats() for a list of formats that QImageReader can read. QImageReader supports all built-in image formats, in addition to any image format plugins that support @@ -85,7 +87,19 @@ stream contents. You can enable or disable this feature, by calling setAutoDetectImageFormat(). + \section1 High Resolution Versions of Images + + It is possible to provide high resolution versions of images should a scaling + between \e{device pixels} and \e{device independent pixels} be in effect. + + The high resolution version is marked by the suffix \c @2x on the base name. + The image read will have its \e{device pixel ratio} set to a value of 2. + + This can be disabled by setting the environment variable + \c QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING. + \sa QImageWriter, QImageIOHandler, QImageIOPlugin, QMimeDatabase + \sa QImage::devicePixelRatio(), QPixmap::devicePixelRatio(), QIcon, QPainter::drawPixmap(), QPainter::drawImage(), Qt::AA_UseHighDpiPixmaps */ /*! diff --git a/src/gui/image/qpixmap.cpp b/src/gui/image/qpixmap.cpp index 2d41ca7e24..88ce48f0e8 100644 --- a/src/gui/image/qpixmap.cpp +++ b/src/gui/image/qpixmap.cpp @@ -648,14 +648,14 @@ void QPixmap::setMask(const QBitmap &mask) /*! Returns the device pixel ratio for the pixmap. This is the - ratio between pixmap pixels and device-independent pixels. + ratio between \e{device pixels} and \e{device independent pixels}. Use this function when calculating layout geometry based on the pixmap size: QSize layoutSize = image.size() / image.devicePixelRatio() The default value is 1.0. - \sa setDevicePixelRatio() + \sa setDevicePixelRatio(), QImageReader */ qreal QPixmap::devicePixelRatio() const { @@ -680,7 +680,8 @@ qreal QPixmap::devicePixelRatio() const pixmap size will take the ratio into account: QSize layoutSize = pixmap.size() / pixmap.devicePixelRatio() The net effect of this is that the pixmap is displayed as - high-dpi pixmap rather than a large pixmap. + high-DPI pixmap rather than a large pixmap + (see \l{Drawing High Resolution Versions of Pixmaps and Images}). \sa devicePixelRatio() */ -- cgit v1.2.3