QIcon Class

成员函数文档

[noexcept] QIcon::QIcon()

创建一个空图标。

[explicit] QIcon::QIcon(QIconEngine *engine)

使用指定的图标创建一个图标engine 。该图标将接管引擎。

QIcon::QIcon(const QPixmap &pixmap)

根据pixmap 对象构建一个图标。

[explicit] QIcon::QIcon(const QString &fileName)

根据给定的fileName ，从文件中生成图标。该文件将按需加载。

如果 `fileName ` 包含相对路径（例如仅包含文件名），则必须相对于运行时工作目录查找该文件。

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

请使用QImageReader::supportedImageFormats() 和QImageWriter::supportedImageFormats() 函数来获取支持的文件格式的完整列表。

QIcon::QIcon(const QIcon &other)

创建other 的副本。该操作非常快。

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

通过“move”构造一个 QIcon 实例，使其指向与 `other ` 所指向的同一对象。

[noexcept] QIcon::~QIcon()

删除该图标。

QSize QIcon::actualSize(const QSize &size, QIcon::Mode mode = Normal, QIcon::State state = Off) const

返回所请求的size 、mode 和state 图标的实际尺寸。结果可能小于请求的尺寸，但绝不会大于请求的尺寸。返回的尺寸以设备无关像素为单位（这对高DPI位图很重要）。

另请参阅 pixmap() 和paint()。

void QIcon::addFile(const QString &fileName, const QSize &size = QSize(), QIcon::Mode mode = Normal, QIcon::State state = Off)

将指定fileName 的文件中的图像添加到图标中，作为size 、mode 和state 的特化实现。该文件将按需加载。注意：自定义图标引擎可以忽略额外添加的位图。

如果fileName 包含相对路径（例如仅包含文件名），则必须以运行时工作目录为基准查找相关文件。

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

使用QImageReader::supportedImageFormats() 和QImageWriter::supportedImageFormats() 函数可获取支持的文件格式的完整列表。

如果存在该图像的高分辨率版本（通过基名后的后缀@2x 标识），系统会自动加载该版本并将其添加，同时将设备像素比设置为 2。可通过设置环境变量QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING 来禁用此功能（参见QImageReader ）。

另请参阅 addPixmap() 和QPixmap::devicePixelRatio()。

void QIcon::addPixmap(const QPixmap &pixmap, QIcon::Mode mode = Normal, QIcon::State state = Off)

向图标添加“pixmap ”，作为“mode ”和“state ”的专项功能。

自定义图标引擎可以忽略额外添加的位图。

另请参阅 addFile()。

QList<QSize> QIcon::availableSizes(QIcon::Mode mode = Normal, QIcon::State state = Off) const

返回指定mode 和state 的可用图标尺寸列表。

qint64 QIcon::cacheKey() const

返回一个用于标识此QIcon 对象内容的标识符。如果不同的QIcon 对象指向相同的内容，它们可以具有相同的键。

当通过 `addPixmap()` 或 `addFile()` 更改图标时，`cacheKey()` 值也会随之改变。

缓存键主要在与缓存功能结合使用时非常有用。

另请参阅 QPixmap::cacheKey()。

[static] QStringList QIcon::fallbackSearchPaths()

返回图标的备用搜索路径。

如果current icon theme 或fallback icon theme 在查找图标时未提供结果，系统将参考这些备用搜索路径来查找独立的图标文件。

如果未设置，则后备搜索路径将由平台定义。

另请参阅 setFallbackSearchPaths() 和themeSearchPaths()。

[static] QString QIcon::fallbackThemeName()

返回备用图标主题的名称。

如果未设置，则备用图标主题将由平台定义。

另请参阅 setFallbackThemeName() 和themeName()。

[static] QIcon QIcon::fromTheme(const QString &name)

返回current icon theme 中与name 对应的QIcon 。

如果当前主题未提供name 的图标，则会先查询fallback icon theme ，随后再回退到在fallback icon search path 中查找独立图标文件。最后，会查询平台的原生图标库。

要从当前图标主题中获取图标：

QIcon undoicon = QIcon::fromTheme(QIcon::ThemeIcon::EditUndo);

如果未通过setThemeName() 显式设置icon theme ，则将使用平台定义的图标主题。

另请参阅 themeName()、fallbackThemeName()、setThemeName()、themeSearchPaths()、fallbackSearchPaths() 以及Freedesktop 图标命名规范。

返回current icon theme 中与icon 对应的QIcon 。

如果当前主题未提供icon 的图标，则会先查询fallback icon theme ，随后退而查询fallback icon search path 中的独立图标文件。最后，会查询平台的原生图标库。

如果未找到图标且提供了fallback ，则返回fallback 。这有助于提供有保障的备用方案，无论当前的图标主题集和备用路径是否支持所请求的图标。

如果未找到图标且未提供fallback ，则返回一个通过默认构造函数创建的空QIcon 。

这些函数在 Qt 6.7 中引入。

[static] QIcon QIcon::fromTheme(const QString &name, const QIcon &fallback)

返回current icon theme 中与name 对应的QIcon 。

如果当前主题未提供name 的图标，则会先查询fallback icon theme ，随后退而查询fallback icon search path 中的独立图标文件。最后，会查询平台的原生图标库。

如果未找到图标，则返回fallback 。

这有助于提供有保障的备用方案，无论当前的图标主题集和备用路径是否支持所请求的图标。

例如：

QIcon undoicon = QIcon::fromTheme(QIcon::ThemeIcon::EditUndo, QIcon(":/undo.png"));

另请参阅 fallbackThemeName() 和fallbackSearchPaths()。

[static] bool QIcon::hasThemeIcon(const QString &name)

如果当前图标主题或任何备用主题中存在适用于name 的图标（如fromTheme() 所述），则返回true ；否则返回false 。

另请参阅 themeSearchPaths()、fromTheme() 和setThemeName()。

[static, since 6.7] bool QIcon::hasThemeIcon(QIcon::ThemeIcon icon)

如果当前图标主题或任何备用主题中存在适用于icon 的图标（如fromTheme() 所述），则返回true ；否则返回false 。

该函数在 Qt 6.7 中引入。

另请参阅 fromTheme()。

bool QIcon::isMask() const

如果该图标已被标记为蒙版图像，则返回true 。某些平台对蒙版图标的渲染方式不同（例如，macOS 上的菜单图标）。

另请参阅 setIsMask()。

bool QIcon::isNull() const

如果图标为空，则返回true ；否则返回false 。

如果图标既没有位图也没有文件名，则该图标为空。

注意：即使图标不为空，也可能无法创建有效的位图，例如文件不存在或无法读取时。

QString QIcon::name() const

返回用于创建图标的名称（如有）。

根据图标的创建方式，它可能有一个关联的名称。使用fromTheme() 创建的图标即属于这种情况。

另请参阅 fromTheme() 和QIconEngine::iconName()。

void QIcon::paint(QPainter *painter, const QRect &rect, Qt::Alignment alignment = Qt::AlignCenter, QIcon::Mode mode = Normal, QIcon::State state = Off) const

使用painter 方法，将图标绘制到矩形rect 内，并使用指定的alignment 、必需的mode 以及state 。

另请参阅 actualSize() 和pixmap()。

void QIcon::paint(QPainter *painter, int x, int y, int w, int h, Qt::Alignment alignment = Qt::AlignCenter, QIcon::Mode mode = Normal, QIcon::State state = Off) const

将图标绘制到矩形中：QRect （x 、y 、w 、h ）。

QPixmap QIcon::pixmap(const QSize &size, QIcon::Mode mode = Normal, QIcon::State state = Off) const

返回一个具有指定size 、mode 和state 的像素图，必要时会生成一个。该像素图可能小于请求的尺寸，但绝不会大于请求的尺寸，除非返回的像素图的设备像素比大于1。

另请参阅 actualSize() 和paint()。

QPixmap QIcon::pixmap(int extent, QIcon::Mode mode = Normal, QIcon::State state = Off) const

返回一个大小为QSize 的像素图（extent ，extent ）。该像素图的大小可能小于请求的大小，但绝不会大于请求的大小，除非返回的像素图的设备像素比大于1。

[since 6.0] QPixmap QIcon::pixmap(const QSize &size, qreal devicePixelRatio, QIcon::Mode mode = Normal, QIcon::State state = Off) const

返回一个具有所请求的size 、devicePixelRatio 、mode 和state 的像素图，必要时会根据给定的mode 和state 生成一个新的像素图。该像素图可能小于所请求的尺寸，但绝不会大于所请求的尺寸，除非返回的像素图的设备像素比大于1。

该函数在 Qt 6.0 中引入。

另请参阅 actualSize() 和paint()。

QPixmap QIcon::pixmap(int w, int h, QIcon::Mode mode = Normal, QIcon::State state = Off) const

返回一个大小为QSize 的像素图（w ，h ）。该像素图的大小可能小于请求的大小，但绝不会大于请求的大小，除非返回的像素图的设备像素比大于1。

[static] void QIcon::setFallbackSearchPaths(const QStringList &paths)

将图标的备用搜索路径设置为paths 。

如果current icon theme 或fallback icon theme 在查找图标时未提供结果，系统将参考这些备用搜索路径来查找独立的图标文件。

例如：

QIcon::setFallbackSearchPaths(QIcon::fallbackSearchPaths() << "my/search/path");

另请参阅 fallbackSearchPaths() 和setThemeSearchPaths()。

[static] void QIcon::setFallbackThemeName(const QString &name)

将备用图标主题设置为name 。

当current icon theme 未提供某些图标，或者current icon theme 不存在时，系统会参考备用图标主题。

name 应与setThemeName() 中记录的格式一致，并将通过themeSearchPaths() 进行查找。

另请参阅 fallbackThemeName()、themeSearchPaths() 和themeName()。

void QIcon::setIsMask(bool isMask)

指示该图标为蒙版图像（布尔值isMask ），因此可根据其显示位置进行修改。

另请参阅 isMask()。

[static] void QIcon::setThemeName(const QString &name)

将当前图标主题设置为name 。

如果该主题名称与已安装的、提供命名字形的字体名称匹配，则QIcon::fromTheme 中调用与其中一个字形匹配的名称将生成该字形的图标。

否则，将在 `themeSearchPaths()` 中查找该主题。目前唯一受支持的图标主题格式是Freedesktop 图标主题规范。`name ` 应对应 `themeSearchPath()` 中的一个目录名称，该目录内应包含一个描述其内容的 `index.theme ` 文件。

另请参阅 themeSearchPaths()、themeName() 以及Freedesktop 图标主题规范。

[static] void QIcon::setThemeSearchPaths(const QStringList &paths)

将图标主题的搜索路径设置为paths 。

paths 文件的内容应遵循setThemeName() 中记录的主题格式。

另请参阅 themeSearchPaths()、fromTheme() 以及setThemeName()。

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

将此图标替换为other 。此操作非常快速，且从不会失败。

[static] QString QIcon::themeName()

返回当前图标主题的名称。

如果未设置，则当前图标主题将由平台定义。

另请参阅 setThemeName()、themeSearchPaths()、fromTheme() 以及hasThemeIcon()。

[static] QStringList QIcon::themeSearchPaths()

返回图标主题的搜索路径。

默认搜索路径由平台定义。所有平台还将使用资源目录:\icons 作为备用路径。

另请参阅 setThemeSearchPaths()、fromTheme() 和setThemeName()。

QIcon::operator QVariant() const

将图标作为QVariant 返回。

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

将other 通过Move操作赋值给该QIcon 实例。

QIcon &QIcon::operator=(const QIcon &other)

将other 图标分配给此图标，并返回对此图标的引用。