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 的比特-OR。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 为 true（默认值），遮罩的大小刚好能覆盖像素；否则，遮罩的大小会大于数据像素。

遮罩可能并不完美，但应该是合理的，因此您可以执行以下操作：

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(),QColormap::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

以独立于设备的像素为单位返回像素图的大小。

在计算用户界面尺寸时使用像素图尺寸时应使用此值。

返回值等同于 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)

使用指定的flags 控制转换，将给定的image 转换为像素图。flags 参数是Qt::ImageConversionFlags 的比特-OR。如果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 的比特-OR。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 时，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)

从len 给定二进制文件的第一个字节加载像素图data 。如果像素图加载成功，则返回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

使用指定的图像文件format 和quality 因子，将像素图保存到带有给定fileName 的文件中。如果成功，则返回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 。例如，该函数可用于将像素图直接保存到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

使用aspectRatioMode 和transformMode 指定的长宽比和变换模式，将像素图缩放至给定的size 。

• 如果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)

以 (dx,dy) 的方式滚动该像素图的rect 区域。露出的区域保持不变。您可以选择传递一个指向空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。将其设置为其他值有两种效果：

在像素图上打开的 QPainters 将被缩放。例如，如果在比例为 2.0 的 200x200 图像上绘画，有效（与设备无关）绘画边界将为 100x100。

Qt XML 中根据像素图大小计算布局几何图形的代码路径将考虑该比例：QSize layoutSize = pixmap.size() / pixmap.devicePixelRatio() 这样做的净效果是，像素图将显示为高 DPI 像素图，而不是大像素图（请参阅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 位。位数较多的图像将以接近底层系统的格式返回。通常情况下，有阿尔法值的像素图将以QImage::Format_ARGB32_Premultiplied 格式返回，无阿尔法值的像素图将以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 。

QVariant QPixmap::operator QVariant() const

以QVariant 的形式返回像素图。

bool QPixmap::operator!() const

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

另请参阅 isNull() 。

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

Move-assignsother 到此QPixmap 实例。

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

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

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