Kirigami2

icon.h
1 /*
2  * SPDX-FileCopyrightText: 2011 Marco Martin <[email protected]>
3  * SPDX-FileCopyrightText: 2014 Aleix Pol Gonzalez <[email protected]>
4  * SPDX-FileCopyrightText: 2020 Carson Black <[email protected]>
5  *
6  * SPDX-License-Identifier: LGPL-2.0-or-later
7  */
8 
9 #pragma once
10 
11 #include <QIcon>
12 #include <QPointer>
13 #include <QQuickItem>
14 #include <QVariant>
15 
16 class QNetworkReply;
17 
18 namespace Kirigami
19 {
20 class PlatformTheme;
21 }
22 
23 /**
24  * Class for rendering an icon in UI.
25  */
26 class Icon : public QQuickItem
27 {
28  Q_OBJECT
29 
30  /**
31  * The source of this icon. An `Icon` can pull from:
32  *
33  * * The icon theme:
34  * @include icon/IconThemeSource.qml
35  * * The filesystem:
36  * @include icon/FilesystemSource.qml
37  * * Remote URIs:
38  * @include icon/InternetSource.qml
39  * * Custom providers:
40  * @include icon/CustomSource.qml
41  * * Your application's bundled resources:
42  * @include icon/ResourceSource.qml
43  *
44  * @note See https://doc.qt.io/qt-5/qtquickcontrols2-icons.html for how to
45  * bundle icon themes in your application to refer to them by name instead of
46  * by resource URL.
47  *
48  * @note Use `fallback` to provide a fallback theme name for icons.
49  *
50  * @note Cuttlefish is a KDE application that lets you view all the icons that
51  * you can use for your application. It offers a number of useful features such
52  * as previews of their appearance across different installed themes, previews
53  * at different sizes, and more. You might find it a useful tool when deciding
54  * on which icons to use in your application.
55  */
56  Q_PROPERTY(QVariant source READ source WRITE setSource NOTIFY sourceChanged)
57 
58  /**
59  * The name of a fallback icon to load from the icon theme when the `source`
60  * cannot be found. The default fallback icon is `"unknown"`.
61  *
62  * @include icon/Fallback.qml
63  *
64  * @note This will only be loaded if source is unavailable (e.g. it doesn't exist, or network issues have prevented loading).
65  */
66  Q_PROPERTY(QString fallback READ fallback WRITE setFallback NOTIFY fallbackChanged)
67 
68  /**
69  * The name of an icon from the icon theme to show while the icon set in `source` is
70  * being loaded. This is primarily relevant for remote sources, or those using slow-
71  * loading image providers. The default temporary icon is `"image-x-icon"`
72  *
73  * @note This will only be loaded if the source is a type which can be so long-loading
74  * that a temporary image makes sense (e.g. a remote image, or from an ImageProvider
75  * of the type QQmlImageProviderBase::ImageResponse)
76  *
77  * @since 5.15
78  */
79  Q_PROPERTY(QString placeholder READ placeholder WRITE setPlaceholder NOTIFY placeholderChanged)
80 
81  /**
82  * Whether this icon will use the QIcon::Active mode when drawing the icon,
83  * resulting in a graphical effect being applied to the icon to indicate that
84  * it is currently active.
85  *
86  * This is typically used to indicate when an item is being hovered or pressed.
87  *
88  * @image html icon/active.png
89  *
90  * The color differences under the default KDE color palette, Breeze. Note
91  * that a dull highlight background is typically displayed behind active icons and
92  * it is recommended to add one if you are creating a custom component.
93  */
94  Q_PROPERTY(bool active READ active WRITE setActive NOTIFY activeChanged)
95 
96  /**
97  * Whether this icon's `source` is valid and it is being used.
98  */
99  Q_PROPERTY(bool valid READ valid NOTIFY validChanged)
100 
101  /**
102  * Whether this icon will use the QIcon::Selected mode when drawing the icon,
103  * resulting in a graphical effect being applied to the icon to indicate that
104  * it is currently selected.
105  *
106  * This is typically used to indicate when a list item is currently selected.
107  *
108  * @image html icon/selected.png
109  *
110  * The color differences under the default KDE color palette, Breeze. Note
111  * that a blue background is typically displayed behind selected elements.
112  */
113  Q_PROPERTY(bool selected READ selected WRITE setSelected NOTIFY selectedChanged)
114 
115  /**
116  * Whether this icon will be treated as a mask. When an icon is being used
117  * as a mask, all non-transparent colors are replaced with the color provided in the Icon's
118  * @link Icon::color color @endlink property.
119  *
120  * @see color
121  */
122  Q_PROPERTY(bool isMask READ isMask WRITE setIsMask NOTIFY isMaskChanged)
123 
124  /**
125  * The color to use when drawing this icon when `isMask` is enabled.
126  * If this property is not set or is `Qt::transparent`, the icon will use
127  * the text or the selected text color, depending on if `selected` is set to
128  * true.
129  */
130  Q_PROPERTY(QColor color READ color WRITE setColor NOTIFY colorChanged)
131 
132  /**
133  * Whether the icon is correctly loaded, is asynchronously loading or there was an error.
134  * Note that image loading will not be initiated until the item is shown, so if the Icon is not visible,
135  * it can only have Null or Loading states.
136  * @since 5.15
137  */
138  Q_PROPERTY(Icon::Status status READ status NOTIFY statusChanged)
139 
140  /**
141  * The width of the painted area measured in pixels. This will be smaller than or
142  * equal to the width of the area taken up by the Item itself. This can be 0.
143  *
144  * @since 5.15
145  */
146  Q_PROPERTY(qreal paintedWidth READ paintedWidth NOTIFY paintedAreaChanged)
147 
148  /**
149  * The height of the painted area measured in pixels. This will be smaller than or
150  * equal to the height of the area taken up by the Item itself. This can be 0.
151  *
152  * @since 5.15
153  */
154  Q_PROPERTY(qreal paintedHeight READ paintedHeight NOTIFY paintedAreaChanged)
155 public:
156  enum Status {
157  Null = 0, /// No icon has been set
158  Ready, /// The icon loaded correctly
159  Loading, // The icon is being loaded, but not ready yet
160  Error, /// There was an error while loading the icon, for instance a non existent themed name, or an invalid url
161  };
162  Q_ENUM(Status)
163 
164  Icon(QQuickItem *parent = nullptr);
165  ~Icon() override;
166 
167  void setSource(const QVariant &source);
168  QVariant source() const;
169 
170  void setActive(bool active = true);
171  bool active() const;
172 
173  bool valid() const;
174 
175  void setSelected(bool selected = true);
176  bool selected() const;
177 
178  void setIsMask(bool mask);
179  bool isMask() const;
180 
181  void setColor(const QColor &color);
182  QColor color() const;
183 
184  QString fallback() const;
185  void setFallback(const QString &fallback);
186 
187  QString placeholder() const;
188  void setPlaceholder(const QString &placeholder);
189 
190  Status status() const;
191 
192  qreal paintedWidth() const;
193  qreal paintedHeight() const;
194 
195  QSGNode *updatePaintNode(QSGNode *node, UpdatePaintNodeData *data) override;
196 
197 Q_SIGNALS:
198  void sourceChanged();
199  void activeChanged();
200  void validChanged();
201  void selectedChanged();
202  void isMaskChanged();
203  void colorChanged();
204  void fallbackChanged(const QString &fallback);
205  void placeholderChanged(const QString &placeholder);
206  void statusChanged();
207  void paintedAreaChanged();
208 
209 protected:
210 #if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
211  void geometryChanged(const QRectF &newGeometry, const QRectF &oldGeometry) override;
212 #else
213  void geometryChange(const QRectF &newGeometry, const QRectF &oldGeometry) override;
214 #endif
215  QImage findIcon(const QSize &size);
216  void handleFinished(QNetworkReply *reply);
217  void handleRedirect(QNetworkReply *reply);
218  QIcon::Mode iconMode() const;
219  bool guessMonochrome(const QImage &img);
220  void setStatus(Status status);
221  void updatePolish() override;
222  void updatePaintedGeometry();
223  void itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value) override;
224 
225 private:
226  Kirigami::PlatformTheme *m_theme = nullptr;
227  QPointer<QNetworkReply> m_networkReply;
228  QHash<int, bool> m_monochromeHeuristics;
229  QVariant m_source;
230  Status m_status = Null;
231  bool m_changed;
232  bool m_active;
233  bool m_selected;
234  bool m_isMask;
235  bool m_isMaskHeuristic = false;
236  QImage m_loadedImage;
237  QColor m_color = Qt::transparent;
238  QString m_fallback = QStringLiteral("unknown");
239  QString m_placeholder = QStringLiteral("image-png");
240  qreal m_paintedWidth = 0.0;
241  qreal m_paintedHeight = 0.0;
242 
243  QImage m_icon;
244 };
Q_OBJECTQ_OBJECT
Status
Definition: icon.h:156
Q_PROPERTY(...)
Q_ENUM(...)
QSizeF size() const const
bool valid
Whether this icon's source is valid and it is being used.
Definition: icon.h:99
QString placeholder
The name of an icon from the icon theme to show while the icon set in source is being loaded.
Definition: icon.h:79
bool isMask
Whether this icon will be treated as a mask.
Definition: icon.h:122
bool selected
Whether this icon will use the QIcon::Selected mode when drawing the icon, resulting in a graphical e...
Definition: icon.h:113
QColor color
The color to use when drawing this icon when isMask is enabled.
Definition: icon.h:130
@ Ready
No icon has been set.
Definition: icon.h:158
bool active
Whether this icon will use the QIcon::Active mode when drawing the icon, resulting in a graphical eff...
Definition: icon.h:94
virtual void geometryChanged(const QRectF &newGeometry, const QRectF &oldGeometry)
@ Loading
The icon loaded correctly.
Definition: icon.h:159
Q_SIGNALSQ_SIGNALS
QString fallback
The name of a fallback icon to load from the icon theme when the source cannot be found.
Definition: icon.h:66
qreal paintedWidth
The width of the painted area measured in pixels.
Definition: icon.h:146
Icon::Status status
Whether the icon is correctly loaded, is asynchronously loading or there was an error.
Definition: icon.h:138
qreal paintedHeight
The height of the painted area measured in pixels.
Definition: icon.h:154
Class for rendering an icon in UI.
Definition: icon.h:26
QVariant source
The source of this icon.
Definition: icon.h:56
transparent
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Jan 29 2023 04:11:03 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.