QIcon¶
Synopsis¶
Functions¶
def
actualSize
(size[, mode=Normal[, state=Off]])def
actualSize
(window, size[, mode=Normal[, state=Off]])def
addFile
(fileName[, size=QSize()[, mode=Normal[, state=Off]]])def
addPixmap
(pixmap[, mode=Normal[, state=Off]])def
availableSizes
([mode=Normal[, state=Off]])def
cacheKey
()def
isMask
()def
isNull
()def
name
()def
paint
(painter, rect[, alignment=Qt.AlignCenter[, mode=Normal[, state=Off]]])def
paint
(painter, x, y, w, h[, alignment=Qt.AlignCenter[, mode=Normal[, state=Off]]])def
pixmap
(extent[, mode=Normal[, state=Off]])def
pixmap
(size[, mode=Normal[, state=Off]])def
pixmap
(w, h[, mode=Normal[, state=Off]])def
pixmap
(window, size[, mode=Normal[, state=Off]])def
setIsMask
(isMask)def
swap
(other)
Static functions¶
def
fallbackSearchPaths
()def
fallbackThemeName
()def
fromTheme
(name)def
fromTheme
(name, fallback)def
hasThemeIcon
(name)def
setFallbackSearchPaths
(paths)def
setFallbackThemeName
(name)def
setThemeName
(path)def
setThemeSearchPaths
(searchpath)def
themeName
()def
themeSearchPaths
()
Detailed Description¶
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 aQPixmap
file or resource, and then use it, allowing Qt to work out all the required icon styles and sizes. For example:button = QToolButton() button.setIcon(QIcon("open.xpm"))To undo a
QIcon
, simply set a null icon in its place:button.setIcon(QIcon())Use the
supportedImageFormats()
andsupportedImageFormats()
functions to retrieve a complete list of the supported file formats.When you retrieve a pixmap using pixmap(
QSize
, Mode, State), and no pixmap for this given size, mode and state has been added withaddFile()
oraddPixmap()
, thenQIcon
will generate one on the fly. This pixmap generation happens in aQIconEngine
. 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. WithQIconEnginePlugin
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.Note
Since Qt 4.2, an icon engine that supports SVG is included.
Making Classes that Use 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 classQToolButton
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:def drawIcon(self, painter, pos): enabledStatus = QIcon.Normal if not isEnabled(): enabledStatus = QIcon::Disabled onOff = QIcon.On if not isOn(): onOff = QIcon.Off pixmap = self.icon.pixmap(QSize(22, 22), enabledStatus, onOff) painter.drawPixmap(pos, pixmap)You might also make use of the
Active
mode, perhaps making your widgetActive
when the mouse is over the widget (seeenterEvent()
), 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.Note
QIcon
needs aQGuiApplication
instance before the icon is created.
High DPI Icons¶
There are two ways that
QIcon
supports high DPI icons: viaaddFile()
andfromTheme()
.
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
.Using
fromTheme()
is necessary if you plan on following the Icon Theme Specification. To makeQIcon
use the high DPI version of an image, add an additional entry to the appropriateindex.theme
file:[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=FixedYour icon theme directory would then look something like this:
├── 32x32 │ └── actions │ └── appointment-new.png ├── 32x32@2 │ └── actions │ └── appointment-new.png └── index.theme
- class PySide2.QtGui.QIcon¶
PySide2.QtGui.QIcon(engine)
PySide2.QtGui.QIcon(other)
PySide2.QtGui.QIcon(pixmap)
PySide2.QtGui.QIcon(fileName)
- param other:
- param fileName:
str
- param engine:
- param pixmap:
Constructs a null icon.
Creates an icon with a specific icon
engine
. The icon takes ownership of the engine.
- PySide2.QtGui.QIcon.Mode¶
This enum type describes the mode for which a pixmap is intended to be used. The currently defined modes are:
Constant
Description
QIcon.Normal
Display the pixmap when the user is not interacting with the icon, but the functionality represented by the icon is available.
QIcon.Disabled
Display the pixmap when the functionality represented by the icon is not available.
QIcon.Active
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
Display the pixmap when the item represented by the icon is selected.
- PySide2.QtGui.QIcon.State¶
This enum describes the state for which a pixmap is intended to be used. The state can be:
Constant
Description
QIcon.Off
Display the pixmap when the widget is in an “off” state
QIcon.On
Display the pixmap when the widget is in an “on” state
- PySide2.QtGui.QIcon.actualSize(window, size[, mode=Normal[, state=Off]])¶
- Parameters:
window –
PySide2.QtGui.QWindow
size –
PySide2.QtCore.QSize
mode –
Mode
state – State
- Return type:
Returns the actual size of the icon for the requested
window
size
,mode
, andstate
.The pixmap can be smaller than the requested size. The returned size is in device-independent pixels (This is relevant for high-dpi pixmaps.)
See also
- PySide2.QtGui.QIcon.actualSize(size[, mode=Normal[, state=Off]])
- Parameters:
size –
PySide2.QtCore.QSize
mode –
Mode
state – State
- Return type:
Returns the actual size of the icon for the requested
size
,mode
, andstate
. 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.)
- PySide2.QtGui.QIcon.addFile(fileName[, size=QSize()[, mode=Normal[, state=Off]]])¶
- Parameters:
fileName – str
size –
PySide2.QtCore.QSize
mode –
Mode
state – State
Adds an image from the file with the given
fileName
to the icon, as a specialization forsize
,mode
andstate
. The file will be loaded on demand. Note: custom icon engines are free to ignore additionally added pixmaps.If
fileName
contains a relative path (e.g. the filename only) the relevant file must be found relative to the runtime working directory.The file name can refer to an actual file on disk or to one of the application’s embedded resources. See the Resource System overview for details on how to embed images and other resource files in the application’s executable.
Use the
supportedImageFormats()
andsupportedImageFormats()
functions to retrieve a complete list of the supported file formats.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 device pixel ratio set to a value of 2. This can be disabled by setting the environment variableQT_HIGHDPI_DISABLE_2X_IMAGE_LOADING
(seeQImageReader
).Note
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.See also
addPixmap()
devicePixelRatio()
- PySide2.QtGui.QIcon.addPixmap(pixmap[, mode=Normal[, state=Off]])¶
- Parameters:
pixmap –
PySide2.QtGui.QPixmap
mode –
Mode
state – State
Adds
pixmap
to the icon, as a specialization formode
andstate
.Custom icon engines are free to ignore additionally added pixmaps.
See also
- PySide2.QtGui.QIcon.availableSizes([mode=Normal[, state=Off]])¶
-
Returns a list of available icon sizes for the specified
mode
andstate
.
- PySide2.QtGui.QIcon.cacheKey()¶
- Return type:
int
Returns a number that identifies the contents of this
QIcon
object. DistinctQIcon
objects can have the same key if they refer to the same contents.The will change when the icon is altered via
addPixmap()
oraddFile()
.Cache keys are mostly useful in conjunction with caching.
See also
- static PySide2.QtGui.QIcon.fallbackSearchPaths()¶
- Return type:
list of strings
Returns the fallback search paths for icons.
The default value will depend on the platform.
- static PySide2.QtGui.QIcon.fallbackThemeName()¶
- Return type:
str
Returns the name of the fallback icon theme.
On X11, if not set, the fallback icon theme depends on your desktop settings. On other platforms it is not set by default.
See also
- static PySide2.QtGui.QIcon.fromTheme(name)¶
- Parameters:
name – str
- Return type:
Returns the
QIcon
corresponding toname
in the current icon theme.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:
undoicon = QIcon.fromTheme("edit-undo")
Note
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 appropriatethemeName()
.Note
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 .
Note
If an icon can’t be found in the current theme, then it will be searched in
fallbackSearchPaths()
as an unthemed icon.
- static PySide2.QtGui.QIcon.fromTheme(name, fallback)
- Parameters:
name – str
fallback –
PySide2.QtGui.QIcon
- Return type:
This is an overloaded function.
Returns the
QIcon
corresponding toname
in the current icon theme. If no such icon is found in the current themefallback
is returned instead.If you want to provide a guaranteed fallback for platforms that do not support theme icons, you can use the second argument:
undoicon = QIcon.fromTheme("edit-undo", QIcon(":/undo.png"))
- static PySide2.QtGui.QIcon.hasThemeIcon(name)¶
- Parameters:
name – str
- Return type:
bool
Returns
true
if there is an icon available forname
in the current icon theme, otherwise returnsfalse
.See also
- PySide2.QtGui.QIcon.isMask()¶
- Return type:
bool
Returns
true
if this icon has been marked as a mask image. Certain platforms render mask icons differently (for example, menu icons on macOS).See also
- PySide2.QtGui.QIcon.isNull()¶
- Return type:
bool
Returns
true
if the icon is empty; otherwise returnsfalse
.An icon is empty if it has neither a pixmap nor a filename.
Note: Even a non-null icon might not be able to create valid pixmaps, eg. if the file does not exist or cannot be read.
- PySide2.QtGui.QIcon.name()¶
- Return type:
str
Returns the name used to create the icon, if available.
Depending on the way the icon was created, it may have an associated name. This is the case for icons created with
fromTheme()
or icons using aQIconEngine
which supports theIconNameHook
.See also
- PySide2.QtGui.QIcon.paint(painter, rect[, alignment=Qt.AlignCenter[, mode=Normal[, state=Off]]])¶
- Parameters:
painter –
PySide2.QtGui.QPainter
rect –
PySide2.QtCore.QRect
alignment –
Alignment
mode –
Mode
state – State
Uses the
painter
to paint the icon with specifiedalignment
, requiredmode
, andstate
into the rectanglerect
.See also
- PySide2.QtGui.QIcon.paint(painter, x, y, w, h[, alignment=Qt.AlignCenter[, mode=Normal[, state=Off]]])
- Parameters:
painter –
PySide2.QtGui.QPainter
x – int
y – int
w – int
h – int
alignment –
Alignment
mode –
Mode
state – State
This is an overloaded function.
Paints the icon into the rectangle
QRect
(x
,y
,w
,h
).
- PySide2.QtGui.QIcon.pixmap(w, h[, mode=Normal[, state=Off]])¶
- Parameters:
- Return type:
This is an overloaded function.
Returns a pixmap of size
QSize
(w
,h
). The pixmap might be smaller than requested, but never larger.Setting the
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.
- PySide2.QtGui.QIcon.pixmap(extent[, mode=Normal[, state=Off]])
- Parameters:
- Return type:
This is an overloaded function.
Returns a pixmap of size
QSize
(extent
,extent
). The pixmap might be smaller than requested, but never larger.Setting the
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.
- PySide2.QtGui.QIcon.pixmap(size[, mode=Normal[, state=Off]])
- Parameters:
size –
PySide2.QtCore.QSize
mode –
Mode
state – State
- Return type:
- PySide2.QtGui.QIcon.pixmap(window, size[, mode=Normal[, state=Off]])
- Parameters:
window –
PySide2.QtGui.QWindow
size –
PySide2.QtCore.QSize
mode –
Mode
state – State
- Return type:
- static PySide2.QtGui.QIcon.setFallbackSearchPaths(paths)¶
- Parameters:
paths – list of strings
Sets the fallback search paths for icons to
paths
.Note
To add some path without replacing existing ones:
QIcon::setFallbackSearchPaths(QIcon::fallbackSearchPaths() << "my/search/path");
- static PySide2.QtGui.QIcon.setFallbackThemeName(name)¶
- Parameters:
name – str
Sets the fallback icon theme to
name
.The
name
should correspond to a directory name in the themeSearchPath() containing an index.theme file describing its contents.Note
This should be done before creating
QGuiApplication
, to ensure correct initialization.
- PySide2.QtGui.QIcon.setIsMask(isMask)¶
- Parameters:
isMask – bool
Indicate that this icon is a mask image(boolean
isMask
), and hence can potentially be modified based on where it’s displayed.See also
- static PySide2.QtGui.QIcon.setThemeName(path)¶
- Parameters:
path – str
Sets the current icon theme to
name
.The
name
should correspond to a directory name in the themeSearchPath() containing an index.theme file describing its contents.See also
- static PySide2.QtGui.QIcon.setThemeSearchPaths(searchpath)¶
- Parameters:
searchpath – list of strings
Sets the search paths for icon themes to
paths
.See also
- PySide2.QtGui.QIcon.swap(other)¶
- Parameters:
other –
PySide2.QtGui.QIcon
Swaps icon
other
with this icon. This operation is very fast and never fails.
- static PySide2.QtGui.QIcon.themeName()¶
- Return type:
str
Returns the name of the current icon theme.
On X11, the current icon theme depends on your desktop settings. On other platforms it is not set by default.
- static PySide2.QtGui.QIcon.themeSearchPaths()¶
- Return type:
list of strings
Returns the search paths for icon themes.
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.
© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.