QPixmap Class

成员函数文档

QPixmap::QPixmap()

创建一个空像素图。

另请参阅 isNull()。

[explicit] QPixmap::QPixmap(const char *const[] xpm)

根据给定的xpm 数据构建一个像素图，该数据必须是有效的XPM图像。

错误将被静默忽略。

请注意，通过使用一种非标准的声明，可以稍微压缩一下 XPM 变量：

static const char * const start_xpm[] = {
    "16 15 8 1",
    "a c #cec6bd",
    // etc.
};

额外的const 使整个定义成为只读的，这在某些情况下（例如代码位于共享库中）效率略高，并且当应用程序需要存储在ROM中时，该定义可被写入ROM。

QPixmap::QPixmap(int width, int height)

使用给定的width 和height 构建一个像素图。如果width 或height 中的任一个为零，则构建一个空像素图。

另请参阅 isNull()。

QPixmap::QPixmap(const QString &fileName, const char *format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor)

根据给定的fileName ，从文件中构建一个像素图。如果文件不存在或格式未知，则该像素图将变为空像素图。

加载器将尝试使用指定的format 读取像素图。如果未指定format （这是默认情况），加载器会扫描文件中的头部信息以推测文件格式。

文件名可以指向磁盘上的实际文件，也可以指向应用程序的嵌入资源之一。有关如何将图像和其他资源文件嵌入应用程序可执行文件的详细信息，请参阅“资源系统概述”。

如果需要修改图像以适应较低分辨率的输出（例如从 32 位转换为 8 位），请使用 `flags ` 来控制转换。

fileName 、format 和flags 参数将传递给load()。这意味着fileName 中的数据不会被编译到二进制文件中。如果fileName 包含相对路径（例如仅包含文件名），则必须相对于运行时工作目录查找相关文件。

另请参阅 Reading and Writing Image Files 。

[explicit] QPixmap::QPixmap(const QSize &size)

根据给定的size 构建一个像素图。

QPixmap::QPixmap(const QPixmap &pixmap)

创建一个像素图，该像素图是给定的pixmap 的副本。

另请参阅 copy()。

[noexcept] QPixmap::QPixmap(QPixmap &&other)

从other 移动构造一个 QPixmap 实例。

另请参阅 swap() 和operator=(QPixmap&&)。

[virtual noexcept] QPixmap::~QPixmap()

销毁像素图。

qint64 QPixmap::cacheKey() const

返回一个用于标识此QPixmap 的数字。不同的QPixmap 对象只有在引用相同内容时，才可能具有相同的缓存键。

当位图发生更改时，cacheKey() 值也会随之改变。

bool QPixmap::convertFromImage(const QImage &image, Qt::ImageConversionFlags flags = Qt::AutoColor)

使用指定的flags 控制转换，将该位图的数据替换为给定的image 。flags 参数是Qt::ImageConversionFlags 的按位或运算结果。若将flags 参数设为0，则采用所有默认选项。若转换后该位图不为空，则返回true 。

另请参阅 fromImage()。

QPixmap QPixmap::copy(const QRect &rectangle = QRect()) const

返回由给定的rectangle 指定的像素图子集的深度拷贝。有关深度拷贝的更多信息，请参阅《隐式数据共享》文档。

如果给定的rectangle 为空，则复制整个图像。

另请参阅 operator=()、QPixmap() 和Pixmap Transformations 。

QPixmap QPixmap::copy(int x, int y, int width, int height) const

返回由矩形QRect （x 、y 、width 、height ）指定的像素图子集的深度拷贝。

QBitmap QPixmap::createHeuristicMask(bool clipTight = true) const

为该位图创建并返回一个启发式蒙版。

该函数的工作原理是：从其中一个角选择一种颜色，然后从所有边缘开始，逐步移除该颜色的像素。如果clipTight 为真（默认值），则遮罩的大小刚好足以覆盖这些像素；否则，遮罩会比数据像素更大。

该掩码可能并非完美，但应是合理的，因此您可以执行如下操作：

QPixmap myPixmap;
myPixmap.setMask(myPixmap.createHeuristicMask());

该函数运行较慢，因为它涉及与QImage 之间的转换，以及一些非简单的计算。

另请参阅 QImage::createHeuristicMask() 和createMaskFromColor()。

QBitmap QPixmap::createMaskFromColor(const QColor &maskColor, Qt::MaskMode mode = Qt::MaskInColor) const

根据给定的maskColor ，为该位图创建并返回一个蒙版。如果mode 为Qt::MaskInColor ，则所有与maskColor匹配的像素将变为透明；如果mode 为Qt::MaskOutColor ，则所有与maskColor匹配的像素将变为不透明。

该函数运行较慢，因为它涉及与QImage 之间的转换。

另请参阅 createHeuristicMask() 和QImage::createMaskFromColor()。

[static] int QPixmap::defaultDepth()

返回应用程序使用的默认位图深度。

在所有平台上，该函数将返回主屏幕的位深度。

另请参阅 depth() 和Pixmap Information 。

int QPixmap::depth() const

返回位图的深度。

像素图的深度也称为“每像素位数”（bpp）或像素图的“位平面”。空像素图的深度为 0。

另请参阅 defaultDepth() 和Pixmap Information 。

void QPixmap::detach()

将像素图从共享像素图数据中分离出来。

每当像素图的内容即将发生变化时，Qt 会自动将其分离。几乎所有修改像素图的QPixmap 成员函数（如fill()、fromImage()、load() 等）以及对像素图调用的QPainter::begin() 都会执行此操作。

有两种情况必须显式调用 detach()，即调用 handle() 或 x11PictureHandle() 函数时（仅在 X11 上可用）。否则，使用系统调用进行的任何修改都将作用于共享数据。

如果仅有一个引用，或者像素图尚未初始化，detach() 函数将立即返回。

[since 6.2] QSizeF QPixmap::deviceIndependentSize() const

返回像素图在设备独立像素（DIP）单位下的尺寸。

在将位图大小用于用户界面尺寸计算时，应使用此值。

该返回值等同于 `pixmap.size()` / `pixmap.devicePixelRatio()`。

该函数在 Qt 6.2 中引入。

qreal QPixmap::devicePixelRatio() const

返回该像素图的设备像素比。这是设备像素与设备独立像素之间的比例。

在根据位图大小计算布局几何形状时，请使用此函数：QSize layoutSize = image.size() / image.devicePixelRatio()

默认值为 1.0。

另请参阅 setDevicePixelRatio() 和QImageReader 。

void QPixmap::fill(const QColor &color = Qt::white)

使用给定的color 填充像素图。

当像素图正在被绘制时，此函数的效果未定义。

另请参阅 Pixmap Transformations 。

[static] QPixmap QPixmap::fromImage(const QImage &image, Qt::ImageConversionFlags flags = Qt::AutoColor)

将给定的image 转换为像素图，并使用指定的flags 来控制转换过程。flags 参数是Qt::ImageConversionFlags 的按位或运算结果。若将flags 设为0，则采用所有默认选项。

对于单色和 8 位图像，系统会先将图像转换为 32 位像素图，然后用颜色表中的颜色填充。如果此操作开销过大，可以使用QBitmap::fromImage() 代替。

另请参阅 fromImageReader()、toImage() 以及Pixmap Conversion 。

[static] QPixmap QPixmap::fromImage(QImage &&image, Qt::ImageConversionFlags flags = Qt::AutoColor)

将给定的image 转换为像素图，如果可能的话，不进行复制。

[static] QPixmap QPixmap::fromImageReader(QImageReader *imageReader, Qt::ImageConversionFlags flags = Qt::AutoColor)

从直接读取自imageReader 的图像创建QPixmap 。flags 参数是Qt::ImageConversionFlags 的按位或运算结果。若将flags 设为0，则采用所有默认选项。

在某些系统上，将图像直接读取到 `QPixmap ` 所占用的内存可能比读取 `QImage ` 并将其转换为 `QPixmap` 更少。

另请参阅 fromImage()、toImage() 和Pixmap Conversion 。

bool QPixmap::hasAlpha() const

如果该位图具有Alpha通道或具有蒙版，则返回true ；否则返回false 。

另请参阅 hasAlphaChannel() 和mask()。

bool QPixmap::hasAlphaChannel() const

如果位图的格式支持Alpha通道，则返回true ；否则返回false 。

另请参阅 hasAlpha()。

int QPixmap::height() const

返回位图的高度。

另请参阅 size() 和Pixmap Information 。

bool QPixmap::isNull() const

如果这是一个空像素图，则返回true ；否则返回false 。

空像素图的宽度为零、高度为零且无内容。无法在空像素图中绘制图形。

bool QPixmap::isQBitmap() const

如果这是一个QBitmap ，则返回true ；否则返回false 。

bool QPixmap::load(const QString &fileName, const char *format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor)

从指定fileName 的文件中加载位图。如果位图加载成功，则返回true；否则，将位图设为无效并返回false 。

加载器将尝试使用指定的format 读取位图。如果未指定format （这是默认情况），加载器会扫描文件中的头部信息以推测文件格式。

文件名可以是指磁盘上的实际文件，也可以是指应用程序的嵌入式资源之一。有关如何将位图和其他资源文件嵌入应用程序可执行文件的详细信息，请参阅“资源系统”概述。

如果需要修改数据以适应较低分辨率的结果（例如从 32 位转换为 8 位），请使用flags 来控制转换。

请注意，当从主线程加载文件时，QPixmaps 会自动添加到 `QPixmapCache ` 中；所使用的键是内部键，无法获取。

另请参阅 loadFromData() 和Reading and Writing Image Files 。

bool QPixmap::loadFromData(const uchar *data, uint len, const char *format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor)

从给定二进制文件data 的前len 个字节中加载位图。如果位图加载成功，则返回true ；否则，将位图置为无效并返回false 。

加载器将尝试使用指定的format 读取像素图。如果未指定format （这是默认情况），加载器会扫描文件以查找文件头，从而推测文件格式。

如果需要修改数据以适应较低分辨率的结果（例如从32位转换为8位），请使用flags 来控制转换。

另请参阅 load() 和Reading and Writing Image Files 。

bool QPixmap::loadFromData(const QByteArray &data, const char *format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor)

使用指定的format 和转换方式flags ，从二进制文件data 中加载位图。

QBitmap QPixmap::mask() const

从像素图的Alpha通道中提取位图蒙版。

另请参阅 setMask() 和Pixmap Information 。

QRect QPixmap::rect() const

返回位图的包围矩形。

另请参阅 Pixmap Information 。

bool QPixmap::save(const QString &fileName, const char *format = nullptr, int quality = -1) const

将位图保存到指定fileName 的文件中，使用指定的图像文件format 和quality 因子。若成功，则返回true ；否则返回false 。

quality 因子必须在[0,100]或-1的范围内。指定0可获得较小的压缩文件，指定100可获得较大的未压缩文件，指定-1则使用默认设置。

如果format 为nullptr ，则将从fileName 的后缀中选择一种图像格式。

另请参阅 Reading and Writing Image Files 。

bool QPixmap::save(QIODevice *device, const char *format = nullptr, int quality = -1) const

该函数使用指定的图像文件format 和quality 参数，将一个QPixmap 写入给定的device 中。例如，这可用于将一个pixmap直接保存到QByteArray 中：

QPixmap pixmap;
QByteArray bytes;
QBuffer buffer(&bytes);
buffer.open(QIODevice::WriteOnly);
pixmap.save(&buffer, "PNG"); // writes pixmap into bytes in PNG format

QPixmap QPixmap::scaled(const QSize &size, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const

将位图按给定的size 进行缩放，并使用aspectRatioMode 和transformMode 中指定的宽高比和变换模式。

• 如果 `aspectRatioMode ` 为 `Qt::IgnoreAspectRatio`，则将像素图缩放为 `size`。
• 如果aspectRatioMode 为Qt::KeepAspectRatio ，则将像素图缩放为size 内的最大矩形，同时保持宽高比。
• 如果 `aspectRatioMode ` 为 `Qt::KeepAspectRatioByExpanding`，则将像素图缩放为 `size` 之外尽可能小的矩形，同时保持宽高比。

如果给定的 `size ` 为空，则该函数返回一个空像素图。

在某些情况下，将位图绘制到已设置缩放比例的绘图器上，比直接缩放位图更为有利。例如，当绘图器基于 OpenGL 时，或者当缩放因子变化迅速时，就是这种情况。

另请参阅 isNull() 和Pixmap Transformations 。

QPixmap QPixmap::scaled(int width, int height, Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const

返回一个像素图的副本，该副本根据给定的aspectRatioMode 和transformMode ，被缩放为具有给定width 和height 的矩形。

如果width 或height 为零或负数，则该函数返回一个空像素图。

QPixmap QPixmap::scaledToHeight(int height, Qt::TransformationMode mode = Qt::FastTransformation) const

返回图像的缩放副本。返回的图像将使用指定的变换mode ，缩放至给定的height 。像素图的宽度会自动计算，以确保保留其宽高比。

如果height 为 0 或负数，则返回一个空像素图。

另请参阅 isNull() 和Pixmap Transformations 。

QPixmap QPixmap::scaledToWidth(int width, Qt::TransformationMode mode = Qt::FastTransformation) const

返回图像的缩放副本。返回的图像将使用指定的变换mode ，按给定的width 进行缩放。像素图的高度会自动计算，以确保保持其宽高比。

如果width 为 0 或负数，则返回一个空像素图。

另请参阅 isNull() 和Pixmap Transformations 。

void QPixmap::scroll(int dx, int dy, const QRect &rect, QRegion *exposed = nullptr)

将该像素图的rect 区域按(dx,dy)进行滚动。暴露的区域保持不变。您可以选择性地传递一个指向空QRegion 的指针，以获取被滚动操作exposed 的区域。

QPixmap pixmap("background.png");
QRegion exposed;
pixmap.scroll(10, 10, pixmap.rect(), &exposed);

当位图上存在活动绘制器时，无法进行滚动。

另请参阅 QWidget::scroll() 和QGraphicsItem::scroll()。

void QPixmap::scroll(int dx, int dy, int x, int y, int width, int height, QRegion *exposed = nullptr)

此便捷函数等同于调用QPixmap::scroll （dx 、dy 、QRect （x 、y 、width 、height ）、exposed ）。

另请参阅 QWidget::scroll() 和QGraphicsItem::scroll()。

void QPixmap::setDevicePixelRatio(qreal scaleFactor)

设置位图的设备像素比。这是图像像素与设备独立像素之间的比例。

默认的scaleFactor 值为1.0。将其设置为其他值会产生以下两个效果：

在该像素图上打开的 QPainter 将被缩放。例如，如果在比例为 2.0 的情况下对 200x200 的图像进行绘制，则实际（与设备无关的）绘制边界将为 100x100。

Qt 中基于 pixmap 尺寸计算布局几何形状的代码路径会将该比例纳入考量：QSize layoutSize = pixmap.size() / pixmap.devicePixelRatio()其最终效果是，pixmap 将作为高 DPI pixmap 显示，而非大尺寸 pixmap（参见Drawing High Resolution Versions of Pixmaps and Images ）。

另请参阅 devicePixelRatio() 和deviceIndependentSize()。

void QPixmap::setMask(const QBitmap &mask)

设置蒙版位图。

该函数将mask 与像素图的Alpha通道进行合并。掩码中像素值为1表示像素图的该像素保持不变；值为0表示该像素为透明。掩码的大小必须与该像素图相同。

设置空掩码将重置掩码，使先前透明的像素变为黑色。当正在对像素图进行绘制时，此函数的效果未定义。

另请参阅 mask(),Pixmap Transformations 以及QBitmap 。

QSize QPixmap::size() const

返回位图的大小。

另请参阅 width()、height() 以及Pixmap Information 。

[noexcept] void QPixmap::swap(QPixmap &other)

将此位图与other 互换。此操作速度极快，且绝不会失败。

QImage QPixmap::toImage() const

将像素图转换为QImage 。如果转换失败，则返回一个空图像。

如果像素图的色深为1位，则返回的图像色深也将为1位。色深更大的图像将以最接近底层系统的格式返回。通常，对于带有Alpha通道的像素图，返回格式为QImage::Format_ARGB32_Premultiplied ；对于不带Alpha通道的像素图，返回格式为QImage::Format_RGB32 或QImage::Format_RGB16 。

请注意，目前单色图像上的 alpha 蒙版会被忽略。

另请参阅 fromImage() 和Image Formats 。

QPixmap QPixmap::transformed(const QTransform &transform, Qt::TransformationMode mode = Qt::FastTransformation) const

返回一个经过给定变换transform 和变换mode 变换后的像素图副本。原始像素图不会被修改。

变换transform 会在内部进行调整，以补偿不需要的平移；也就是说，生成的位图是包含原始位图所有变换后点的最小位图。请使用trueMatrix() 函数来获取用于变换该位图的实际矩阵。

该函数运行较慢，因为它涉及将坐标系转换为QImage 、非平凡的计算，以及将坐标系转换回QPixmap 。

另请参阅 trueMatrix() 和Pixmap Transformations 。

[static] QTransform QPixmap::trueMatrix(const QTransform &matrix, int width, int height)

返回用于对位图进行变换的实际矩阵，该变换基于给定的width 、height 和matrix 。

使用transformed()函数对像素图进行变换时，系统会内部调整变换矩阵以补偿不需要的平移，即transformed()函数返回一个包含原始像素图所有变换后点的最小像素图。本函数返回经过修改的矩阵，该矩阵能将原始像素图中的点正确映射到新像素图中。

另请参阅 transformed() 和Pixmap Transformations 。

int QPixmap::width() const

返回位图的宽度。

另请参阅 size() 和Pixmap Information 。

QPixmap::operator QVariant() const

将位图作为QVariant 返回。

bool QPixmap::operator!() const

如果这是一个空的像素图，则返回true ；否则返回false 。

另请参阅 isNull()。

[noexcept] QPixmap &QPixmap::operator=(QPixmap &&other)

将other 通过move-assign操作赋值给此QPixmap 实例。

QPixmap &QPixmap::operator=(const QPixmap &pixmap)

将给定的pixmap 分配给此像素图，并返回对此像素图的引用。

另请参见 copy() 和QPixmap()。