1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtquickcontrols2-icons.html
\title Icons in Qt Quick Controls 2
Qt Quick Controls 2.3 (Qt 5.10) introduced built-in support for icons. Buttons,
item delegates, and menu items are now capable of presenting an icon in addition
to a text label.
\section1 Using Icons
\l {AbstractButton::icon}{AbstractButton} and \l {Action::icon}{Action} provide
the following properties through which icons can be set:
\list
\li \c icon.name
\li \c icon.source
\li \c icon.width
\li \c icon.height
\li \c icon.color
\endlist
Theme icons are referenced by a name, and regular icons by a source URL. Both
\c icon.name and \c icon.source can be set to ensure that an icon will always
be found. If the icon is found in the theme, it will always be used; even if
\c icon.source is also set. If the icon is not found in the theme, \c icon.source
will be used instead.
\code
Button {
icon.name: "edit-cut"
icon.source: "images/cut.png"
}
\endcode
Each \l {Styling Qt Quick Controls 2}{Qt Quick Controls 2 style} requests a
default icon size and color according to their guidelines, but it is possible
to override these by setting the \c icon.width, \c icon.height, and \c icon.color
properties.
The image that is loaded by an icon whose \c width and \c height are not set
depends on the type of icon in use. For theme icons, the closest available size
will be chosen. For regular icons, the behavior is the same as the \l {Image::}
{sourceSize} property of \l Image.
The icon color is specified by default so that it matches the text color in
different states. In order to use an icon with the original colors, set the
color to \c "transparent".
\code
Button {
icon.color: "transparent"
icon.source: "images/logo.png"
}
\endcode
For buttons, the \l {AbstractButton::}{display} property can be used to control
how the icon and text are displayed within the button.
\section1 Icon Themes
Compliant icon themes must follow the freedesktop icon theme specification,
which can be obtained here: \l {http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html}.
Traditionally, only Linux and UNIX support icon themes on the platform level,
but it is possible to bundle a compliant icon theme in an application to use
themed icons on any platform.
The default \l {QIcon::themeSearchPaths()}{icon theme search paths} depend on
the platform. On Linux and UNIX, the search path will use the \c XDG_DATA_DIRS
environment variable if available. All platforms have the resource directory
\c :/icons as a fallback. Custom icon theme search paths can be set with
\l QIcon::setThemeSearchPaths().
The following example bundles an icon theme called \e mytheme into the application's
resources using \l {The Qt Resource System}{Qt's resource system}.
\badcode
<RCC>
<qresource prefix="/">
<file>icons/mytheme/index.theme</file>
<file>icons/mytheme/32x32/myicon.png</file>
<file>icons/mytheme/32x32@2/myicon.png</file>
</qresource>
</RCC>
\endcode
The \c index.theme file describes the general attributes of the icon theme, and
lists the available theme icon directories:
\badcode
[Icon Theme]
Name=mytheme
Comment=My Icon Theme
Directories=32x32,32x32@2
[32x32]
Size=32
Type=Fixed
[32x32@2]
Size=32
Scale=2
Type=Fixed
\endcode
In order to use the bundled icon theme, an application should call \l QIcon::setThemeName()
before loading the main QML file:
\code
#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QIcon>
int main(int argc, char *argv[])
{
QGuiApplication app(argc, argv);
QIcon::setThemeName("mytheme"); // <--
QQmlApplicationEngine engine;
engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
return app.exec();
}
\endcode
Now it is possible to use named icons from the bundled icon theme without having
to specify any fallback source:
\code
Button {
icon.name: "myicon"
}
\endcode
The \l {Qt Quick Controls 2 - Gallery}{Gallery example} and \l {Qt Quick Controls 2 - Wearable Demo}
{Wearable Demo} provide complete runnable applications with a bundled icon theme.
\section1 Related Information
\list
\li \l {High-DPI Support in Qt Quick Controls 2}
\endlist
*/
|
