QPixmap 类是可以用作描绘设备的离屏图像表示。 更多...
| 头： | #include <QPixmap> |
| CMake: |
find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| 继承： | QPaintDevice |
| 继承者： | QBitmap |
| QPixmap () | |
| QPixmap (int width , int height ) | |
| QPixmap (const QSize & size ) | |
| QPixmap (const QString & fileName , const char * format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor) | |
| QPixmap (const char *const [] xpm ) | |
| QPixmap (const QPixmap & pixmap ) | |
| QPixmap (QPixmap && other ) | |
| virtual | ~QPixmap () |
| qint64 | cacheKey () const |
| bool | convertFromImage (const QImage & image , Qt::ImageConversionFlags flags = Qt::AutoColor) |
| QPixmap | copy (const QRect & rectangle = QRect()) const |
| QPixmap | copy (int x , int y , int width , int height ) const |
| QBitmap | createHeuristicMask (bool clipTight = true) const |
| QBitmap | createMaskFromColor (const QColor & maskColor , Qt::MaskMode mode = Qt::MaskInColor) const |
| int | depth () const |
| void | detach () |
| QSizeF | deviceIndependentSize () const |
| qreal | devicePixelRatio () const |
| void | fill (const QColor & color = Qt::white) |
| bool | hasAlpha () const |
| bool | hasAlphaChannel () const |
| int | height () const |
| bool | isNull () const |
| bool | isQBitmap () const |
| bool | load (const QString & fileName , const char * format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor) |
| bool | loadFromData (const uchar * data , uint len , const char * format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor) |
| bool | loadFromData (const QByteArray & data , const char * format = nullptr, Qt::ImageConversionFlags flags = Qt::AutoColor) |
| QBitmap | mask () const |
| QRect | rect () const |
| bool | save (const QString & fileName , const char * format = nullptr, int quality = -1) const |
| bool | save (QIODevice * device , const char * format = nullptr, int quality = -1) const |
| QPixmap | scaled (const QSize & size , Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const |
| QPixmap | scaled (int width , int height , Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio, Qt::TransformationMode transformMode = Qt::FastTransformation) const |
| QPixmap | scaledToHeight (int height , Qt::TransformationMode mode = Qt::FastTransformation) const |
| QPixmap | scaledToWidth (int width , Qt::TransformationMode mode = Qt::FastTransformation) const |
| void | scroll (int dx , int dy , int x , int y , int width , int height , QRegion * exposed = nullptr) |
| void | scroll (int dx , int dy , const QRect & rect , QRegion * exposed = nullptr) |
| void | setDevicePixelRatio (qreal scaleFactor ) |
| void | setMask (const QBitmap & mask ) |
| QSize | size () const |
| void | swap (QPixmap & other ) |
| QImage | toImage () const |
| QPixmap | transformed (const QTransform & transform , Qt::TransformationMode mode = Qt::FastTransformation) const |
| int | width () const |
| QVariant | operator QVariant () const |
| bool | operator! () const |
| QPixmap & | operator= (const QPixmap & pixmap ) |
| QPixmap & | operator= (QPixmap && other ) |
| int | defaultDepth () |
| QPixmap | fromImage (const QImage & image , Qt::ImageConversionFlags flags = Qt::AutoColor) |
| QPixmap | fromImage (QImage && image , Qt::ImageConversionFlags flags = Qt::AutoColor) |
| QPixmap | fromImageReader (QImageReader * imageReader , Qt::ImageConversionFlags flags = Qt::AutoColor) |
| QTransform | trueMatrix (const QTransform & matrix , int width , int height ) |
| QDataStream & | operator<< (QDataStream & stream , const QPixmap & pixmap ) |
| QDataStream & | operator>> (QDataStream & stream , QPixmap & pixmap ) |
Qt 为处理图像数据提供了 4 个类：
QImage
, QPixmap,
QBitmap
and
QPicture
.
QImage
是为 I/O 及直接访问和操纵像素而设计和优化的，而 QPixmap 是为在屏幕上展示图像而设计和优化的。
QBitmap
只是继承 QPixmap 的方便类，确保 1 深度。
isQBitmap
() 函数返回
true
如果 QPixmap 对象确实是位图，否则返回
false
。最后，
QPicture
类是描绘设备，它记录并重演
QPainter
命令。
QPixmap 可以轻松显示在屏幕上使用 QLabel 或某一 QAbstractButton 子类 (譬如 QPushButton and QToolButton ). QLabel 拥有 pixmap 属性，而 QAbstractButton 拥有 icon 特性。
QPixmap 对象可以按值传递，由于 QPixmap 类使用隐式数据共享。更多信息，见 隐式数据共享 文档编制。QPixmap 对象还可以被流化。
注意，像素图中的像素数据在内部，且由底层窗口系统管理。因为 QPixmap 是 QPaintDevice 子类， QPainter 可以用于在像素图中直接绘制。只可以访问像素透过 QPainter 函数或通过将 QPixmap 转换成 QImage 。不管怎样， fill () 函数是可用的为采用给定颜色初始化整个像素图。
有函数能转换 QImage 和 QPixmap。通常， QImage 类用于加载图像文件，可选操纵图像数据，先于 QImage 对象被转换成 QPixmap 以展示在屏幕中。另外，若不期望操纵，可以直接将图像文件加载进 QPixmap。
QPixmap 提供可以用于获取像素图各种有关信息的一批函数。此外，还有几个函数启用像素图变换。
QPixmap 提供了读取图像文件的几种方式：可以在构造 QPixmap 对象时加载文件，或通过使用 load () 或 loadFromData () 函数稍后。当加载图像时，文件名可以引用实际磁盘文件，或引用应用程序的某一嵌入资源。见 Qt 资源系统 概述，了解如何在应用程序可执行文件中嵌入图像及其它资源文件的细节。
只需调用 save () 函数以保存 QPixmap 对象。
可获得支持的文件格式的完整列表，透过 QImageReader::supportedImageFormats () 和 QImageWriter::supportedImageFormats () 函数。可以将新文件格式添加作为插件。默认情况下，Qt 支持以下格式：
| 格式 | 描述 | Qt 支持 |
|---|---|---|
| BMP | Windows 位图 | 读/写 |
| GIF | GIF (图形互换格式) 可选 | 读取 |
| JPG | JPEG (联合摄影专家组) | 读/写 |
| JPEG | JPEG (联合摄影专家组) | 读/写 |
| PNG | PNG (便携式网络图形) | 读/写 |
| PBM | PBM (便携式位图) | 读取 |
| PGM | PGM (便携式灰度图) | 读取 |
| PPM | Portable Pixmap (便携式像素图) | 读/写 |
| XBM | X11 Bitmap (X11 位图) | 读/写 |
| XPM | X11 Pixmap (X11 像素图) | 读/写 |
QPixmap 提供了可以用于获取有关像素图各种信息的一批函数：
| 可用函数 | |
|---|---|
| 几何体 | The size (), width () 和 height () 函数提供像素图大小的有关信息。 rect () 函数返回图像的封闭矩形。 |
| Alpha 组件 |
The
hasAlphaChannel
() 返回
true
若像素图是遵守 Alpha 通道的格式，否则返回
false
。
hasAlpha
(),
setMask
() 和
mask
() 函数是传统的且不应使用。它们潜在非常慢。
The createHeuristicMask () 函数创建并返回 1-bpp 试探遮罩 (即 QBitmap ) 对于此像素图。它的工作是通过从一角选择颜色，然后从所有边缘开始去除相应颜色的像素。 createMaskFromColor () 函数创建并返回遮罩 (即 QBitmap ) 对于基于给定颜色的像素图而言。 |
| 低级信息 |
The
depth
() 函数返回像素图的深度。
defaultDepth
() 函数返回默认深度 (即：应用程序在给定屏幕上所使用的深度)。
The cacheKey () 函数返回标识 QPixmap 对象内容的唯一数字。 |
QPixmap 对象可以转换成 QImage 使用 toImage () 函数。同样， QImage 可以转换成 QPixmap 使用 fromImage ()。若操作过于昂贵，可以使用 QBitmap::fromImage () 代替。
要转换 QPixmap 到和从 HICON，可以分别使用 QtWinExtras 函数 QtWin::toHICON() 和 QtWin::fromHICON()。
QPixmap 支持许多用于创建新像素图 (即：原始变换版本) 的函数：
The scaled (), scaledToWidth () 和 scaledToHeight () 函数返回像素图的比例缩放副本，而 copy () 函数创建是原始 QPixmap 普通拷贝的 QPixmap。
The transformed () 函数返回按给定变换矩阵和变换模式变换的像素图副本：在内部，调节变换矩阵以补偿不想要的平移，即 transformed () 返回包含原始像素图所有变换点的最小像素图。静态 trueMatrix () 函数返回用于变换像素图的实际矩阵。
另请参阅 QBitmap , QImage , QImageReader ，和 QImageWriter .
构造 null 像素图。
另请参阅 isNull ().
构造像素图采用给定 width and height 。若 width or height 为 0，构造 null 像素图。
警告： 这将创建 QPixmap 采用未初始化数据。调用 fill () 以合适颜色填充像素图先于绘制采用 QPainter .
另请参阅 isNull ().
[explicit]
QPixmap::
QPixmap
(const
QSize
&
size
)
这是重载函数。
构造像素图为给定 size .
警告： 这将创建 QPixmap 采用未初始化数据。调用 fill () 以合适颜色填充像素图先于绘制采用 QPainter .
从文件构造像素图采用给定 fileName 。若文件不存在 (或格式未知)，像素图变为 null 像素图。
加载器试图读取像素图使用指定 format 。若 format 未指定 (默认)，加载器会探针文件 Header (头) 以猜测文件格式。
文件名可以引用实际磁盘文件，或引用应用程序的某一嵌入资源。见 资源系统 概述，了解如何在应用程序可执行文件中嵌入图像及其它资源文件的细节。
若需要修改图像以拟合更低分辨率结果 (如：从 32 位转换成 8 位)，使用 flags 来控制转换。
The fileName , format and flags 参数被传递给 load ()。这意味着数据在 fileName 未被编译成二进制。若 fileName 包含相对路径 (如：仅文件名)，必须相对运行时工作目录查找相关文件。
另请参阅 读写图像文件 .
[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 中时。
构造像素图副本为给定 pixmap .
另请参阅 copy ().
移动构造 QPixmap 实例从 other .
另请参阅 swap () 和 operator= (QPixmap&&).
[虚拟]
QPixmap::
~QPixmap
()
销毁像素图。
返回的数字标识此 QPixmap 。截然不同的 QPixmap 对象只可以拥有相同缓存键，若它们引用相同内容。
cacheKey() 会改变，当像素图变更时。
替换此像素图的数据采用给定
image
使用指定
flags
来控制转换。
flags
自变量是按位 OR 的
Qt::ImageConversionFlags
。传递 0 为
flags
设置所有默认选项。返回
true
若结果是此像素图不为 null。
注意：此函数是 Qt 4.6 及更早版本的 Qt 3 支持的一部分。在 4.7 已提升为官方 API 状态以支持更新像素图图像，不用创建新的 QPixmap as fromImage () would.
另请参阅 fromImage ().
返回像素图子集的深拷贝，指定通过给定 rectangle 。有关深拷贝的更多信息，见 隐式数据共享 文档编制。
若给定 rectangle 为空，拷贝整个图像。
另请参阅 operator= (), QPixmap ()，和 像素图变换 .
这是重载函数。
返回像素图子集的深拷贝，指定通过矩形 QRect ( x , y , width , height ).
创建并返回此像素图的试探遮罩。
函数的工作是通过从一角选择颜色，然后从所有边缘开始去除相应颜色的像素。若 clipTight 为 true (默认)，遮罩刚好足够大以覆盖像素；否则，遮罩 > 数据像素。
遮罩可能并不完美但应该合理，所以可以做的事情如下：
QPixmap myPixmap; myPixmap.setMask(myPixmap.createHeuristicMask());
此函数很慢，因为它涉及转换到/从 QImage ，及非通俗计算。
另请参阅 QImage::createHeuristicMask () 和 createMaskFromColor ().
创建并返回用于此像素图的遮罩基于给定 maskColor 。若 mode is Qt::MaskInColor ，与 maskColor 匹配的所有像素都将透明。若 mode is Qt::MaskOutColor ，与 maskColor 匹配的所有像素都将不透明。
此函数很慢，因为它涉及转换到/从 QImage .
另请参阅 createHeuristicMask () 和 QImage::createMaskFromColor ().
[static]
int
QPixmap::
defaultDepth
()
返回用于应用程序的默认像素图深度。
在所有平台，将返回首要屏幕深度。
注意： QGuiApplication 必须被创建在调用此函数之前。
另请参阅 depth (), QColormap::depth ()，和 像素图信息 .
返回像素图的深度。
像素图深度又称 BPP (每像素位) 或像素图位平面。null 像素图拥有深度 0。
另请参阅 defaultDepth () 和 像素图信息 .
从共享像素图数据分离像素图。
像素图会被 Qt 自动分离，每当其内容即将改变时。这的完成是在几乎所有 QPixmap 成员函数修改像素图 ( fill (), fromImage (), load ()，等)，和在 QPainter::begin () 在像素图。
必须明确调用 detach() 存在 2 种例外情况，就是当调用 handle() 或 x11PictureHandle() 函数 (只可用于 X11) 时。否则，使用系统调用完成的任何修改，都将在共享数据中履行。
detach() 函数会立即返回，若仅仅存在一个引用 (或者，若像素图尚未被初始化)。
[since 6.2]
QSizeF
QPixmap::
deviceIndependentSize
() const
按设备无关像素返回像素图的大小。
应使用此值，当在用户界面大小计算中使用像素图大小时。
返回值相当于 pixmap. size () / pixmap. devicePixelRatio ().
该函数在 Qt 6.2 引入。
返回像素图的设备像素比率。此比率介于 设备像素 and 设备无关像素 .
使用此函数，当基于像素图大小计算布局几何体时： QSize layoutSize = image. size () / image.devicePixelRatio()
默认值为 1.0。
另请参阅 setDevicePixelRatio () 和 QImageReader .
填充像素图采用给定 color .
此函数的效果未定义，当描绘像素图时。
另请参阅 像素图变换 .
[static]
QPixmap
QPixmap::
fromImage
(const
QImage
&
image
,
Qt::ImageConversionFlags
flags
= Qt::AutoColor)
转换给定 image 到像素图使用指定 flags 来控制转换。 flags 自变量是按位 OR 的 Qt::ImageConversionFlags 。传递 0 为 flags 设置所有默认选项。
在单色和 8 位图像情况下，图像首先被转换成 32 位像素图，然后采用颜色表颜色填充。若此操作过于昂贵，可以使用 QBitmap::fromImage () 代替。
另请参阅 fromImageReader (), toImage ()，和 像素图转换 .
[static]
QPixmap
QPixmap::
fromImage
(
QImage
&&
image
,
Qt::ImageConversionFlags
flags
= Qt::AutoColor)
这是重载函数。
转换给定 image 到像素图不拷贝 (若可能的话)。
[static]
QPixmap
QPixmap::
fromImageReader
(
QImageReader
*
imageReader
,
Qt::ImageConversionFlags
flags
= Qt::AutoColor)
创建 QPixmap 从图像直接读取自 imageReader 。 flags 自变量是按位 OR 的 Qt::ImageConversionFlags 。传递 0 为 flags 设置所有默认选项。
在某些系统，将图像直接读取到 QPixmap 可以使用更少内存相比读取 QImage 以转换它到 QPixmap .
另请参阅 fromImage (), toImage ()，和 像素图转换 .
返回
true
若此像素图有 Alpha 通道，
or
有遮罩，否则返回
false
.
另请参阅 hasAlphaChannel () 和 mask ().
返回
true
若像素图是遵守 Alpha 通道的格式，否则返回
false
.
另请参阅 hasAlpha ().
返回像素图的高度。
返回
true
若这是 null 像素图；否则返回
false
.
null 像素图拥有 0 宽度，0 高度，且没有内容。无法在 null 像素图中绘制。
返回
true
若这是
QBitmap
；否则返回
false
.
从文件加载像素图采用给定
fileName
。返回 true 若像素图加载成功；否则使像素图无效并返回
false
.
加载器试图读取像素图使用指定 format 。若 format 未指定 (默认)，加载器会探针文件 Header (头) 以猜测文件格式。
文件名可以引用实际磁盘文件，或引用应用程序的某一嵌入资源。见 资源系统 概述了解如何在应用程序可执行文件中嵌入像素图及其它资源文件的细节。
若需要修改数据以拟合较低分辨率的结果 (如：从 32 位转换到 8 位)，使用 flags 来控制转换。
注意：QPixmap 会被自动添加到 QPixmapCache 当在主线程中加载文件时；使用键是内部的且无法获得。
另请参阅 loadFromData () 和 读写图像文件 .
加载像素图从
len
首字节的给定二进制
data
。返回
true
若像素图加载成功；否则使像素图无效并返回
false
.
加载器试图读取像素图使用指定 format 。若 format 未指定 (默认)，加载器会探针文件 Header (头) 以猜测文件格式。
若需要修改数据以拟合较低分辨率的结果 (如：从 32 位转换到 8 位)，使用 flags 来控制转换。
这是重载函数。
加载像素图从二进制 data 使用指定 format 和转换 flags .
从像素图的 Alpha 通道提取位图遮罩。
警告： 这潜在是很昂贵的操作。像素图遮罩是从像素数据动态提取的。
返回像素图的封闭矩形。
另请参阅 像素图信息 .
把像素图保存到文件，采用给定
fileName
使用指定图像文件
format
and
quality
因子。返回
true
若成功；否则返回
false
.
The quality 因子必须在 [0,100] 范围内或为 -1。指定 0 以获得小压缩文件，100 为大的未压缩文件，和 -1 使用默认设置。
若
format
is
nullptr
，图像格式将选取自
fileName
的后缀。
另请参阅 读写图像文件 .
这是重载函数。
此函数写入 QPixmap 到给定 device 使用指定图像文件 format and quality 因子。这可以被使用，例如：把像素图直接保存到 QByteArray :
QPixmap pixmap; QByteArray bytes; QBuffer buffer(&bytes); buffer.open(QIODevice::WriteOnly); pixmap.save(&buffer, "PNG"); // writes pixmap into bytes in PNG format
比例缩放像素图到给定 size ，使用宽高比和变换模式，指定通过 aspectRatioMode and transformMode .
若给定 size 为空，此函数返回 null 像素图。
在某些情况下，把像素图绘制到具有比例缩放设置的描绘器，比比例缩放像素图效果更好。如：当描绘器是基于 OpenGL 的实例，或当比例缩放因子快速变化时。
这是重载函数。
返回的像素图副本被比例缩放到矩形采用给定 width and height 根据给定 aspectRatioMode and transformMode .
若 width 或 height 为 0 或负值，此函数返回 null 像素图。
返回图像的比例缩放副本。返回图像被比例缩放到给定 height 使用指定变换 mode 。 自动计算像素图宽度，以便维持像素图宽高比。
若 height 为 0 或负数，返回 null 像素图。
返回图像的比例缩放副本。返回图像被比例缩放到给定 width 使用指定变换 mode 。自动计算像素图高度，以便维持像素图宽高比。
若 width 为 0 或负数，返回 null 像素图。
此方便函数相当于调用 QPixmap::scroll( dx , dy , QRect ( x , y , width , height ), exposed ).
另请参阅 QWidget::scroll () 和 QGraphicsItem::scroll ().
卷动区域 rect 为此像素图按 ( dx , dy )。暴露区域保持不变。可以可选将指针传递给空 QRegion 以获取区域 exposed 通过卷动操作。
QPixmap pixmap("background.png"); QRegion exposed; pixmap.scroll(10, 10, pixmap.rect(), &exposed);
无法卷动，当像素图中有活动描绘器时。
另请参阅 QWidget::scroll () 和 QGraphicsItem::scroll ().
设置像素图的设备像素比率。这是图像像素和设备无关像素之间的比率。
默认 scaleFactor 为 1.0。将它设为其它值有 2 种效果：
将比例缩放在像素图中打开的 QPainter。例如，若采用比率 2.0，在 200x200 图像中描绘将产生有效 (独立于设备) 的 100x100 描绘边界。
Qt 中基于像素图大小计算布局几何体的代码路径，会考虑比率： QSize layoutSize = pixmap. size () / pixmap. devicePixelRatio () 这的净效果是像素图被显示成高 DPI (每英寸点数) 像素图，而不是大像素图 (见 绘制高分辨率版本的像素图和图像 ).
另请参阅 devicePixelRatio () 和 deviceIndependentSize ().
设置遮罩位图。
此函数合并 mask 采用像素图的 Alpha 通道。遮罩像素值 1 意味着像素图的像素无变化；值 0 意味着像素透明。遮罩必须拥有如此像素图的相同大小。
设置 null 遮罩将重置遮罩，使先前透明像素变为黑色。此函数的效果未定义，当描绘像素图时。
警告： 这是潜在的昂贵操作。
另请参阅 mask (), 像素图变换 ，和 QBitmap .
返回像素图尺寸。
另请参阅 width (), height ()，和 像素图信息 .
交换像素图 other 与此像素图。此操作非常快且从不失败。
将像素图转换成 QImage 。返回 null 图像，若转换失败。
若像素图拥有 1 位深度，返回图像也将是 1 位深。具有更多位的图像将按底层系统所表示的密切格式返回。通常，这会是 QImage::Format_ARGB32_Premultiplied 对于具有 Alpha 的像素图和 QImage::Format_RGB32 or QImage::Format_RGB16 对于没有 Alpha 的像素图。
注意：目前，单色图像忽略 Alpha 遮罩。
返回像素图副本的变换是使用给定变换 transform 和变换 mode 。原始像素图不改变。
变换 transform 在内部调节以补偿不想要的平移；即，产生像素图是包含原始像素图所有变换点的最小像素图。使用 trueMatrix () 函数能检索用于变换像素图的实际矩阵。
此函数很慢，因为它涉及变换到 QImage ，非通俗计算及变换回 QPixmap .
另请参阅 trueMatrix () 和 像素图变换 .
[static]
QTransform
QPixmap::
trueMatrix
(const
QTransform
&
matrix
,
int
width
,
int
height
)
返回用于变换像素图的实际矩阵采用给定 width , height and matrix .
当变换像素图使用 transformed () 函数，变换矩阵在内部调节以补偿不想要的平移，即 transformed () 返回包含原始像素图所有变换点的最小像素图。此函数返回将原始像素图中的点，正确映射到新像素图的修改矩阵。
另请参阅 transformed () 和 像素图变换 .
返回像素图的宽度。
将像素图返回为 QVariant .
返回
true
若这是 null 像素图；否则返回
false
.
另请参阅 isNull ().
赋值给定 pixmap 到此像素图并返回此像素图的引用。
移动赋值 other 到此 QPixmap 实例。
写入给定 pixmap 到给定 stream 作为 PNG 图像。注意：将流写入文件不会产生有效图像文件。
另请参阅 QPixmap::save () 和 序列化 Qt 数据类型 .
读取图像从给定 stream 进给定 pixmap .
另请参阅 QPixmap::load () 和 序列化 Qt 数据类型 .