1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtGui module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include "qiconengine.h"
41#include "qpainter.h"
42
43QT_BEGIN_NAMESPACE
44
45/*!
46 \class QIconEngine
47
48 \brief The QIconEngine class provides an abstract base class for QIcon renderers.
49
50 \ingroup painting
51 \inmodule QtGui
52
53 An icon engine provides the rendering functions for a QIcon. Each icon has a
54 corresponding icon engine that is responsible for drawing the icon with a
55 requested size, mode and state.
56
57 The icon is rendered by the paint() function, and the icon can additionally be
58 obtained as a pixmap with the pixmap() function (the default implementation
59 simply uses paint() to achieve this). The addPixmap() function can be used to
60 add new pixmaps to the icon engine, and is used by QIcon to add specialized
61 custom pixmaps.
62
63 The paint(), pixmap(), and addPixmap() functions are all virtual, and can
64 therefore be reimplemented in subclasses of QIconEngine.
65
66 \sa QIconEnginePlugin
67
68*/
69
70/*!
71 \fn virtual void QIconEngine::paint(QPainter *painter, const QRect &rect, QIcon::Mode mode, QIcon::State state) = 0;
72
73 Uses the given \a painter to paint the icon with the required \a mode and
74 \a state into the rectangle \a rect.
75*/
76
77/*! Returns the actual size of the icon the engine provides for the
78 requested \a size, \a mode and \a state. The default implementation
79 returns the given \a size.
80 */
81QSize QIconEngine::actualSize(const QSize &size, QIcon::Mode /*mode*/, QIcon::State /*state*/)
82{
83 return size;
84}
85
86/*!
87 \since 5.6
88 Constructs the icon engine.
89 */
90QIconEngine::QIconEngine()
91{
92}
93
94/*!
95 \since 5.8
96 \internal
97 */
98QIconEngine::QIconEngine(const QIconEngine &)
99{
100}
101
102/*!
103 Destroys the icon engine.
104 */
105QIconEngine::~QIconEngine()
106{
107}
108
109
110/*!
111 Returns the icon as a pixmap with the required \a size, \a mode,
112 and \a state. The default implementation creates a new pixmap and
113 calls paint() to fill it.
114*/
115QPixmap QIconEngine::pixmap(const QSize &size, QIcon::Mode mode, QIcon::State state)
116{
117 QPixmap pm(size);
118 {
119 QPainter p(&pm);
120 paint(&p, QRect(QPoint(0,0),size), mode, state);
121 }
122 return pm;
123}
124
125/*!
126 Called by QIcon::addPixmap(). Adds a specialized \a pixmap for the given
127 \a mode and \a state. The default pixmap-based engine stores any supplied
128 pixmaps, and it uses them instead of scaled pixmaps if the size of a pixmap
129 matches the size of icon requested. Custom icon engines that implement
130 scalable vector formats are free to ignores any extra pixmaps.
131 */
132void QIconEngine::addPixmap(const QPixmap &/*pixmap*/, QIcon::Mode /*mode*/, QIcon::State /*state*/)
133{
134}
135
136
137/*! Called by QIcon::addFile(). Adds a specialized pixmap from the
138 file with the given \a fileName, \a size, \a mode and \a state. The
139 default pixmap-based engine stores any supplied file names, and it
140 loads the pixmaps on demand instead of using scaled pixmaps if the
141 size of a pixmap matches the size of icon requested. Custom icon
142 engines that implement scalable vector formats are free to ignores
143 any extra files.
144 */
145void QIconEngine::addFile(const QString &/*fileName*/, const QSize &/*size*/, QIcon::Mode /*mode*/, QIcon::State /*state*/)
146{
147}
148
149
150/*!
151 \enum QIconEngine::IconEngineHook
152 \since 4.5
153
154 These enum values are used for virtual_hook() to allow additional
155 queries to icon engine without breaking binary compatibility.
156
157 \value IsNullHook Allow to query if this engine represents a null
158 icon. The \a data argument of the virtual_hook() is a pointer to a
159 bool that can be set to true if the icon is null. This enum value
160 was added in Qt 5.7.
161
162 \value ScaledPixmapHook Provides a way to get a pixmap that is scaled
163 according to the given scale (typically equal to the \l {Glossary Of High
164 DPI Terms}{device pixel ratio}). The \a data argument of the virtual_hook()
165 function is a \l ScaledPixmapArgument pointer that contains both the input and
166 output arguments. This enum value was added in Qt 5.9.
167
168 \sa virtual_hook()
169 */
170
171/*!
172 \class QIconEngine::ScaledPixmapArgument
173 \since 5.9
174
175 \inmodule QtGui
176
177 This struct represents arguments to the virtual_hook() function when
178 the \a id parameter is QIconEngine::ScaledPixmapHook.
179
180 The struct provides a way for icons created via \l QIcon::fromTheme()
181 to return pixmaps that are designed for the current \l {Glossary Of High
182 DPI Terms}{device pixel ratio}. The scale for such an icon is specified
183 using the \l {Icon Theme Specification - Directory Layout}{Scale directory key}
184 in the appropriate \c index.theme file.
185
186 Icons created via other approaches will return the same result as a call to
187 \l pixmap() would, and continue to benefit from Qt's \l {High Resolution
188 Versions of Images}{"@nx" high DPI syntax}.
189
190 \sa virtual_hook(), QIconEngine::IconEngineHook, {High DPI Icons}
191 */
192
193/*!
194 \variable QIconEngine::ScaledPixmapArgument::size
195 \brief The requested size of the pixmap.
196*/
197
198/*!
199 \variable QIconEngine::ScaledPixmapArgument::mode
200 \brief The requested mode of the pixmap.
201
202 \sa QIcon::Mode
203*/
204
205/*!
206 \variable QIconEngine::ScaledPixmapArgument::state
207 \brief The requested state of the pixmap.
208
209 \sa QIcon::State
210*/
211
212/*!
213 \variable QIconEngine::ScaledPixmapArgument::scale
214 \brief The requested scale of the pixmap.
215*/
216
217/*!
218 \variable QIconEngine::ScaledPixmapArgument::pixmap
219
220 \brief The pixmap that is the best match for the given \l size, \l mode, \l
221 state, and \l scale. This is an output parameter that is set after calling
222 \l virtual_hook().
223*/
224
225
226/*!
227 Returns a key that identifies this icon engine.
228 */
229QString QIconEngine::key() const
230{
231 return QString();
232}
233
234/*! \fn QIconEngine *QIconEngine::clone() const
235
236 Reimplement this method to return a clone of this icon engine.
237 */
238
239/*!
240 Reads icon engine contents from the QDataStream \a in. Returns
241 true if the contents were read; otherwise returns \c false.
242
243 QIconEngine's default implementation always return false.
244 */
245bool QIconEngine::read(QDataStream &)
246{
247 return false;
248}
249
250/*!
251 Writes the contents of this engine to the QDataStream \a out.
252 Returns \c true if the contents were written; otherwise returns \c false.
253
254 QIconEngine's default implementation always return false.
255 */
256bool QIconEngine::write(QDataStream &) const
257{
258 return false;
259}
260
261/*!
262 \since 4.5
263
264 Additional method to allow extending QIconEngine without
265 adding new virtual methods (and without breaking binary compatibility).
266 The actual action and format of \a data depends on \a id argument
267 which is in fact a constant from IconEngineHook enum.
268
269 \sa IconEngineHook
270*/
271void QIconEngine::virtual_hook(int id, void *data)
272{
273 switch (id) {
274 case QIconEngine::ScaledPixmapHook: {
275 // We don't have any notion of scale besides "@nx", so just call pixmap() here.
276 QIconEngine::ScaledPixmapArgument &arg =
277 *reinterpret_cast<QIconEngine::ScaledPixmapArgument*>(data);
278 arg.pixmap = pixmap(arg.size, arg.mode, arg.state);
279 break;
280 }
281 default:
282 break;
283 }
284}
285
286/*!
287 \since 4.5
288
289 Returns sizes of all images that are contained in the engine for the
290 specific \a mode and \a state.
291 */
292QList<QSize> QIconEngine::availableSizes(QIcon::Mode /*mode*/, QIcon::State /*state*/)
293{
294 return {};
295}
296
297/*!
298 \since 4.7
299
300 Returns the name used to create the engine, if available.
301 */
302QString QIconEngine::iconName()
303{
304 return QString();
305}
306
307/*!
308 \since 5.7
309
310 Returns true if this icon engine represent a null QIcon.
311
312 \include qiconengine-virtualhookhelper.qdocinc
313 */
314bool QIconEngine::isNull()
315{
316 bool isNull = false;
317 virtual_hook(QIconEngine::IsNullHook, &isNull);
318 return isNull;
319}
320
321/*!
322 \since 5.9
323
324 Returns a pixmap for the given \a size, \a mode, \a state and \a scale.
325
326 The \a scale argument is typically equal to the \l {Glossary Of High DPI
327 Terms}{device pixel ratio} of the display.
328
329 \include qiconengine-virtualhookhelper.qdocinc
330
331 \note Some engines may cast \a scale to an integer.
332
333 \sa ScaledPixmapArgument
334*/
335QPixmap QIconEngine::scaledPixmap(const QSize &size, QIcon::Mode mode, QIcon::State state, qreal scale)
336{
337 ScaledPixmapArgument arg;
338 arg.size = size;
339 arg.mode = mode;
340 arg.state = state;
341 arg.scale = scale;
342 const_cast<QIconEngine *>(this)->virtual_hook(QIconEngine::ScaledPixmapHook, reinterpret_cast<void*>(&arg));
343 return arg.pixmap;
344}
345
346QT_END_NAMESPACE
347