1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page qtquickcontrols-icons.html
6 \keyword Icons in Qt Quick Controls 2
7 \title Icons in Qt Quick Controls
9 Qt Quick Controls comes with support for icons since Qt 5.10. This means,
10 Buttons, item delegates, and menu items are now capable of presenting an
11 icon in addition to a text label.
15 \l {AbstractButton::icon}{AbstractButton} and \l {Action::icon}{Action} provide
16 the following properties through which icons can be set:
26 Theme icons are referenced by a name, and regular icons by a source URL. Both
27 \c icon.name and \c icon.source can be set to ensure that an icon will always
28 be found. If the icon is found in the theme, it will always be used; even if
29 \c icon.source is also set. If the icon is not found in the theme, \c icon.source
35 icon.source: "images/cut.png"
39 Each \l {Styling Qt Quick Controls}{Qt Quick Controls 2 style} requests a
40 default icon size and color according to their guidelines, but it is possible
41 to override these by setting the \c icon.width, \c icon.height, and \c icon.color
44 The image that is loaded by an icon whose \c width and \c height are not set
45 depends on the type of icon in use. For theme icons, the closest available size
46 will be chosen. For regular icons, the behavior is the same as the \l {Image::}
47 {sourceSize} property of \l Image.
49 The icon color is specified by default so that it matches the text color in
50 different states. In order to use an icon with the original colors, set the
51 color to \c "transparent".
55 icon.color: "transparent"
56 icon.source: "images/logo.png"
60 For buttons, the \l {AbstractButton::}{display} property can be used to control
61 how the icon and text are displayed within the button.
63 The \c icon.cache property controls whether or not the icon image is cached.
64 For more information, see \l {Image::}{cache}.
68 Compliant icon themes must follow the freedesktop icon theme specification,
69 which can be obtained here: \l {http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html}.
71 Traditionally, only Linux and UNIX support icon themes on the platform level,
72 but it is possible to bundle a compliant icon theme in an application to use
73 themed icons on any platform.
75 The default \l {QIcon::themeSearchPaths()}{icon theme search paths} depend on
76 the platform. On Linux and UNIX, the search path will use the \c XDG_DATA_DIRS
77 environment variable if available. All platforms have the resource directory
78 \c :/icons as a fallback. Custom icon theme search paths can be set with
79 \l QIcon::setThemeSearchPaths().
81 The following example bundles an icon theme called \e mytheme into the application's
82 resources using \l {The Qt Resource System}{Qt's resource system}.
86 <qresource prefix="/">
87 <file>icons/mytheme/index.theme</file>
88 <file>icons/mytheme/32x32/myicon.png</file>
89 <file>icons/mytheme/32x32@2/myicon.png</file>
94 The \c index.theme file describes the general attributes of the icon theme, and
95 lists the available theme icon directories:
100 Comment=My Icon Theme
102 Directories=32x32,32x32@2
114 In order to use the bundled icon theme, an application should call \l QIcon::setThemeName()
115 before loading the main QML file:
118 #include <QGuiApplication>
119 #include <QQmlApplicationEngine>
122 int main(int argc, char *argv[])
124 QGuiApplication app(argc, argv);
126 QIcon::setThemeName("mytheme"); // <--
128 QQmlApplicationEngine engine;
129 engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
134 Now it is possible to use named icons from the bundled icon theme without having
135 to specify any fallback source:
143 The \l {Qt Quick Controls - Gallery}{Gallery example} and \l {Qt Quick Controls 2 - Wearable Demo}
144 {Wearable Demo} provide complete runnable applications with a bundled icon theme.