內容

• 公共類型
• 公共函數
• 靜態公共成員
• 相關非成員
• 詳細描述
• 製作使用 QIcon 的類
• 高 DPI 圖標

QIcon 類

The QIcon 類提供在不同模式和狀態下的可伸縮圖標。 更多...

頭：	#include <QIcon>
qmake:	QT += gui

• 所有成員列錶，包括繼承成員
• 過時成員

公共類型

enum	Mode { Normal, Disabled, Active, Selected }
enum	State { Off, On }

公共函數

	QIcon ()
	QIcon (const QPixmap & pixmap )
	QIcon (const QIcon & other )
	QIcon (QIcon && other )
	QIcon (const QString & fileName )
	QIcon (QIconEngine * engine )
	~QIcon ()
QSize	actualSize (const QSize & size , QIcon::Mode mode = Normal, QIcon::State state = Off) const
QSize	actualSize (QWindow * window , const QSize & size , QIcon::Mode mode = Normal, QIcon::State state = Off) const
void	addFile (const QString & fileName , const QSize & size = QSize(), QIcon::Mode mode = Normal, QIcon::State state = Off)
void	addPixmap (const QPixmap & pixmap , QIcon::Mode mode = Normal, QIcon::State state = Off)
QList<QSize>	availableSizes (QIcon::Mode mode = Normal, QIcon::State state = Off) const
qint64	cacheKey () const
bool	isMask () const
bool	isNull () const
QString	name () const
void	paint (QPainter * painter , const QRect & rect , Qt::Alignment alignment = Qt::AlignCenter, QIcon::Mode mode = Normal, QIcon::State state = Off) const
void	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
QPixmap	pixmap (const QSize & size , QIcon::Mode mode = Normal, QIcon::State state = Off) const
QPixmap	pixmap (int w , int h , QIcon::Mode mode = ..., QIcon::State state = ...) const
QPixmap	pixmap (int extent , QIcon::Mode mode = ..., QIcon::State state = ...) const
QPixmap	pixmap (QWindow * window , const QSize & size , QIcon::Mode mode = Normal, QIcon::State state = Off) const
void	setIsMask (bool isMask )
void	swap (QIcon & other )
QVariant	operator QVariant () const
QIcon &	operator= (const QIcon & other )
QIcon &	operator= (QIcon && other )

靜態公共成員

QStringList	fallbackSearchPaths ()
QString	fallbackThemeName ()
QIcon	fromTheme (const QString & name )
QIcon	fromTheme (const QString & name , const QIcon & fallback )
bool	hasThemeIcon (const QString & name )
void	setFallbackSearchPaths (const QStringList & paths )
void	setFallbackThemeName (const QString & name )
void	setThemeName (const QString & name )
void	setThemeSearchPaths (const QStringList & paths )
QString	themeName ()
QStringList	themeSearchPaths ()

相關非成員

QDataStream &	operator<< (QDataStream & stream , const QIcon & icon )
QDataStream &	operator>> (QDataStream & stream , QIcon & icon )

詳細描述

The QIcon 類提供在不同模式和狀態下的可伸縮圖標。

A QIcon can generate smaller, larger, active, and disabled pixmaps from the set of pixmaps it is given. Such pixmaps are used by Qt widgets to show an icon representing a particular action.

The simplest use of QIcon is to create one from a QPixmap 文件 (或資源)，然後使用它，允許 Qt 算齣所有要求圖標的樣式和大小。例如：

QToolButton *button = new QToolButton;
button->setIcon(QIcon("open.xpm"));
					

To undo a QIcon , simply set a null icon in its place:

button->setIcon(QIcon());
					

使用 QImageReader::supportedImageFormats () 和 QImageWriter::supportedImageFormats () 函數能檢索支持文件格式的完整列錶。

當檢索像素圖使用 pixmap( QSize , Mode, State), and no pixmap for this given size, mode and state has been added with addFile () 或 addPixmap ()，然後 QIcon will generate one on the fly. This pixmap generation happens in a QIconEngine . The default engine scales pixmaps down if required, but never up, and it uses the current style to calculate a disabled appearance. By using custom icon engines, you can customize every aspect of generated icons. With QIconEnginePlugin it is possible to register different icon engines for different file suffixes, making it possible for third parties to provide additional icon engines to those included with Qt.

注意： Since Qt 4.2, an icon engine that supports SVG is included.

製作使用 QIcon 的類

If you write your own widgets that have an option to set a small pixmap, consider allowing a QIcon to be set for that pixmap. The Qt class QToolButton is an example of such a widget.

Provide a method to set a QIcon , and when you draw the icon, choose whichever pixmap is appropriate for the current state of your widget. For example:

void MyWidget::drawIcon(QPainter *painter, QPoint pos)
{
    QPixmap pixmap = icon.pixmap(QSize(22, 22),
                                   isEnabled() ? QIcon::Normal
                                               : QIcon::Disabled,
                                   isChecked() ? QIcon::On
                                               : QIcon::Off);
    painter->drawPixmap(pos, pixmap);
}
					

You might also make use of the Active mode, perhaps making your widget Active when the mouse is over the widget (see QWidget::enterEvent ()), while the mouse is pressed pending the release that will activate the function, or when it is the currently selected item. If the widget can be toggled, the "On" mode might be used to draw a different icon.

注意： QIcon needs a QGuiApplication 實例在創建圖標之前。

高 DPI 圖標

There are two ways that QIcon supports 高 DPI (每英寸點數) 圖標：憑藉 addFile () 和 fromTheme ().

addFile () is useful if you have your own custom directory structure and do not need to use the freedesktop.org Icon Theme Specification . Icons created via this approach use Qt's "@nx" high DPI syntax .

使用 fromTheme () is necessary if you plan on following the Icon Theme Specification. To make QIcon use the high DPI version of an image, add an additional entry to the appropriate index.theme 文件：

[Icon Theme]
Name=Test
Comment=Test Theme
Directories=32x32/actions,32x32@2/actions
[32x32/actions]
Size=32
Context=Actions
Type=Fixed
# High DPI version of the entry above.
[32x32@2/actions]
Size=32
Scale=2
Type=Fixed
					

Your icon theme directory would then look something like this:

├── 32x32
│   └── actions
│       └── appointment-new.png
├── 32x32@2
│   └── actions
│       └── appointment-new.png
└── index.theme
					

另請參閱 GUI 設計手冊：圖標化標簽 and 圖標範例 .

成員類型文檔編製

enum QIcon:: Mode

此枚舉類型描述旨在使用的像素圖模式。目前定義的模式：

常量	值	描述
QIcon::Normal	0	顯示像素圖當用戶未與圖標交互時，但由圖標錶示的功能是可用的。
QIcon::Disabled	1	Display the pixmap when the functionality represented by the icon is not available.
QIcon::Active	2	Display the pixmap when the functionality represented by the icon is available and the user is interacting with the icon, for example, moving the mouse over it or clicking it.
QIcon::Selected	3	顯示像素圖當由圖標錶示的項被選中時。

enum QIcon:: State

此枚舉描述旨在使用的像素圖狀態。 state 可以是：

常量	值	描述
QIcon::Off	1	Display the pixmap when the widget is in an "off" state
QIcon::On	0	Display the pixmap when the widget is in an "on" state

成員函數文檔編製

QIcon:: QIcon ()

構造 null 圖標。

QIcon:: QIcon (const QPixmap & pixmap )

構造圖標從 pixmap .

QIcon:: QIcon (const QIcon & other )

構造副本為 other 。這非常快。

QIcon:: QIcon ( QIcon && other )

移動構造 QIcon 實例，使它指嚮同一對象 other 所指嚮的。

QIcon:: QIcon (const QString & fileName )

構造圖標從文件采用給定 fileName 。將按需加載文件。

若 fileName 包含相對路徑 (如：僅文件名)，必須相對運行時工作目錄查找相關文件。

文件名可以引用實際磁盤文件或應用程序嵌入資源之一。見 資源係統 概述，瞭解如何在應用程序可執行文件中嵌入圖像及其它資源文件的細節。

使用 QImageReader::supportedImageFormats () 和 QImageWriter::supportedImageFormats () 函數能檢索支持文件格式的完整列錶。

QIcon:: QIcon ( QIconEngine * engine )

創建圖標采用特定圖標 engine 。圖標擁有引擎的所有權。

QIcon:: ~QIcon ()

銷毀圖標。

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

Returns the actual size of the icon for the requested size , mode ，和 state . The result might be smaller than requested, but never larger. The returned size is in device-independent pixels (This is relevant for high-dpi pixmaps.)

另請參閱 pixmap () 和 paint ().

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

Returns the actual size of the icon for the requested window size , mode ，和 state .

The pixmap can be smaller than the requested size. The returned size is in device-independent pixels (This is relevant for high-dpi pixmaps.)

該函數在 Qt 5.1 引入。

另請參閱 actualSize (), pixmap ()，和 paint ().

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

Adds an image from the file with the given fileName 到圖標，作為特殊化為 size , mode and state . The file will be loaded on demand. Note: custom icon engines are free to ignore additionally added pixmaps.

若 fileName 包含相對路徑 (如：僅文件名)，必須相對運行時工作目錄查找相關文件。

文件名可以引用實際磁盤文件或應用程序嵌入資源之一。見 資源係統 概述，瞭解如何在應用程序可執行文件中嵌入圖像及其它資源文件的細節。

使用 QImageReader::supportedImageFormats () 和 QImageWriter::supportedImageFormats () 函數能檢索支持文件格式的完整列錶。

If a high resolution version of the image exists (identified by the suffix @2x on the base name), it is automatically loaded and added with the 設備像素比率 set to a value of 2. This can be disabled by setting the environment variable QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING (見 QImageReader ).

注意： 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.

另請參閱 addPixmap () 和 QPixmap::devicePixelRatio ().

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

添加 pixmap 到圖標，作為特殊化為 mode and state .

自定義圖標引擎可自由忽略額外添加的像素圖。

另請參閱 addFile ().

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

返迴可用圖標大小的列錶為指定 mode and state .

該函數在 Qt 4.5 引入。

qint64 QIcon:: cacheKey () const

返迴內容標識數對於此 QIcon 對象。截然不同的 QIcon 對象可以擁有相同鍵，若它們引用相同內容。

The cacheKey() will change when the icon is altered via addPixmap () 或 addFile ().

Cache keys are mostly useful in conjunction with caching.

該函數在 Qt 4.3 引入。

另請參閱 QPixmap::cacheKey ().

[static] QStringList QIcon:: fallbackSearchPaths ()

返迴用於圖標的迴退搜索路徑。

The default value will depend on the platform.

該函數在 Qt 5.11 引入。

另請參閱 setFallbackSearchPaths () 和 themeSearchPaths ().

[static] QString QIcon:: fallbackThemeName ()

返迴迴退圖標主題的名稱。

On X11, if not set, the fallback icon theme depends on your desktop settings. On other platforms it is not set by default.

該函數在 Qt 5.12 引入。

另請參閱 setFallbackThemeName () 和 themeName ().

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

返迴 QIcon 對應 name 在當前圖標主題。

The latest version of the freedesktop icon specification and naming specification can be obtained here:

• http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html
• http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html

To fetch an icon from the current icon theme:

    QIcon undoicon = QIcon::fromTheme("edit-undo");
					

注意： By default, only X11 will support themed icons. In order to use themed icons on Mac and Windows, you will have to bundle a compliant theme in one of your themeSearchPaths () and set the appropriate themeName ().

注意： Qt will make use of GTK's icon-theme.cache if present to speed up the lookup. These caches can be generated using gtk-update-icon-cache: https://developer.gnome.org/gtk3/stable/gtk-update-icon-cache.html .

注意： If an icon can't be found in the current theme, then it will be searched in fallbackSearchPaths () as an unthemed icon.

該函數在 Qt 4.6 引入。

另請參閱 themeName (), setThemeName (), themeSearchPaths ()，和 fallbackSearchPaths ().

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

這是重載函數。

返迴 QIcon 對應 name in the current icon theme. If no such icon is found in the current theme fallback 被返迴取而代之。

If you want to provide a guaranteed fallback for platforms that do not support theme icons, you can use the second argument:

    QIcon undoicon = QIcon::fromTheme("edit-undo", QIcon(":/undo.png"));
					

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

返迴 true if there is an icon available for name in the current icon theme, otherwise returns false .

該函數在 Qt 4.6 引入。

另請參閱 themeSearchPaths (), fromTheme ()，和 setThemeName ().

bool QIcon:: isMask () const

返迴 true if this icon has been marked as a mask image. Certain platforms render mask icons differently (for example, menu icons on macOS ).

該函數在 Qt 5.6 引入。

另請參閱 setIsMask ().

bool QIcon:: isNull () const

返迴 true 若圖標為空；否則返迴 false .

圖標為空，若既沒有像素圖也沒有文件名。

注意：即使非 null 圖標也可能無法創建有效像素圖 (如：若文件不存在，或無法讀取)。

QString QIcon:: name () const

返迴用於創建圖標的名稱，若可用。

從屬圖標的創建方式，它可能有關聯名稱。這是用於創建圖標的情況采用 fromTheme () or icons using a QIconEngine which supports the QIconEngine::IconNameHook .

該函數在 Qt 4.7 引入。

另請參閱 fromTheme () 和 QIconEngine .

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

使用 painter 來描繪圖標采用指定 alignment ，要求 mode ，和 state 到矩形 rect .

另請參閱 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

Returns a pixmap with the requested size , mode ，和 state , generating one if necessary. The pixmap might be smaller than requested, but never larger.

設置 Qt::AA_UseHighDpiPixmaps application attribute enables this function to return pixmaps that are larger than the requested size. Such images will have a devicePixelRatio larger than 1.

另請參閱 actualSize () 和 paint ().

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

這是重載函數。

Returns a pixmap of size QSize ( w , h ). The pixmap might be smaller than requested, but never larger.

設置 Qt::AA_UseHighDpiPixmaps application attribute enables this function to return pixmaps that are larger than the requested size. Such images will have a devicePixelRatio larger than 1.

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

這是重載函數。

Returns a pixmap of size QSize ( extent , extent ). The pixmap might be smaller than requested, but never larger.

設置 Qt::AA_UseHighDpiPixmaps application attribute enables this function to return pixmaps that are larger than the requested size. Such images will have a devicePixelRatio larger than 1.

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

Returns a pixmap with the requested window size , mode ，和 state , generating one if necessary.

The pixmap can be smaller than the requested size. If window is on a high-dpi display the pixmap can be larger. In that case it will have a devicePixelRatio larger than 1.

該函數在 Qt 5.1 引入。

另請參閱 actualSize () 和 paint ().

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

Sets the fallback search paths for icons to paths .

注意： To add some path without replacing existing ones:

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

該函數在 Qt 5.11 引入。

另請參閱 fallbackSearchPaths () 和 setThemeSearchPaths ().

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

將迴退圖標主題設為 name .

The name should correspond to a directory name in the themeSearchPath() containing an index.theme file describing its contents.

注意： This should be done before creating QGuiApplication , to ensure correct initialization.

該函數在 Qt 5.12 引入。

另請參閱 fallbackThemeName (), themeSearchPaths ()，和 themeName ().

void QIcon:: setIsMask ( bool isMask )

Indicate that this icon is a mask image(boolean isMask ), and hence can potentially be modified based on where it's displayed.

該函數在 Qt 5.6 引入。

另請參閱 isMask ().

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

將當前圖標主題設為 name .

The name should correspond to a directory name in the themeSearchPath() containing an index.theme file describing its contents.

該函數在 Qt 4.6 引入。

另請參閱 themeSearchPaths () 和 themeName ().

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

Sets the search paths for icon themes to paths .

該函數在 Qt 4.6 引入。

另請參閱 themeSearchPaths (), fromTheme ()，和 setThemeName ().

void QIcon:: swap ( QIcon & other )

交換圖標 other 與此圖標。此操作很快且從不失敗。

該函數在 Qt 4.8 引入。

[static] QString QIcon:: themeName ()

返迴當前圖標主題的名稱。

On X11, the current icon theme depends on your desktop settings. On other platforms it is not set by default.

該函數在 Qt 4.6 引入。

另請參閱 setThemeName (), themeSearchPaths (), fromTheme ()，和 hasThemeIcon ().

[static] QStringList QIcon:: themeSearchPaths ()

返迴圖標主題的搜索路徑。

The default value will depend on the platform:

On X11, the search path will use the XDG_DATA_DIRS environment variable if available.

By default all platforms will have the resource directory :\icons as a fallback. You can use "rcc -project" to generate a resource file from your icon theme.

該函數在 Qt 4.6 引入。

另請參閱 setThemeSearchPaths (), fromTheme ()，和 setThemeName ().

QVariant QIcon:: operator QVariant () const

Returns the icon as a QVariant .

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

賦值 other 圖標到此圖標並返迴此圖標的引用。

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

移動賦值 other 到此 QIcon 實例。

該函數在 Qt 5.2 引入。

相關非成員

QDataStream & operator<< ( QDataStream & stream , const QIcon & icon )

寫入給定 icon 到給定 stream as a PNG image. If the icon contains more than one image, all images will be written to the stream. Note that writing the stream to a file will not produce a valid image file.

該函數在 Qt 4.2 引入。

QDataStream & operator>> ( QDataStream & stream , QIcon & icon )

讀取圖像 (或一組圖像) 從給定 stream 進給定 icon .

該函數在 Qt 4.2 引入。