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  Q_PROPERTY(QVariant source READ source WRITE setSource NOTIFY sourceChanged)
51 
52  /**
53  * The name of a fallback icon to load from the icon theme when the `source`
54  * cannot be found. The default fallback icon is `"unknown"`.
55  *
56  * @include icon/Fallback.qml
57  *
58  * @note This will only be loaded if source is unavailable (e.g. it doesn't exist, or network issues have prevented loading).
59  */
60  Q_PROPERTY(QString fallback READ fallback WRITE setFallback NOTIFY fallbackChanged)
61 
62  /**
63  * The name of an icon from the icon theme to show while the icon set in `source` is
64  * being loaded. This is primarily relevant for remote sources, or those using slow-
65  * loading image providers. The default temporary icon is `"image-x-icon"`
66  *
67  * @note This will only be loaded if the source is a type which can be so long-loading
68  * that a temporary image makes sense (e.g. a remote image, or from an ImageProvider
69  * of the type QQmlImageProviderBase::ImageResponse)
70  *
71  * @since 5.15
72  */
73  Q_PROPERTY(QString placeholder READ placeholder WRITE setPlaceholder NOTIFY placeholderChanged)
74 
75  /**
76  * Whether this icon will use the QIcon::Active mode when drawing the icon,
77  * resulting in a graphical effect being applied to the icon to indicate that
78  * it is currently active.
79  *
80  * This is typically used to indicate when an item is being hovered or pressed.
81  *
82  * @image html icon/active.png
83  *
84  * The color differences under the default KDE color palette, Breeze. Note
85  * that a dull highlight background is typically displayed behind active icons and
86  * it is recommended to add one if you are creating a custom component.
87  */
88  Q_PROPERTY(bool active READ active WRITE setActive NOTIFY activeChanged)
89 
90  /**
91  * Whether this icon's `source` is valid and it is being used.
92  */
93  Q_PROPERTY(bool valid READ valid NOTIFY validChanged)
94 
95  /**
96  * Whether this icon will use the QIcon::Selected mode when drawing the icon,
97  * resulting in a graphical effect being applied to the icon to indicate that
98  * it is currently selected.
99  *
100  * This is typically used to indicate when a list item is currently selected.
101  *
102  * @image html icon/selected.png
103  *
104  * The color differences under the default KDE color palette, Breeze. Note
105  * that a blue background is typically displayed behind selected elements.
106  */
107  Q_PROPERTY(bool selected READ selected WRITE setSelected NOTIFY selectedChanged)
108 
109  /**
110  * Whether this icon will be treated as a mask. When an icon is being used
111  * as a mask, all non-transparent colors are replaced with the color provided in the Icon's
112  * @link Icon::color color @endlink property.
113  *
114  * @see color
115  */
116  Q_PROPERTY(bool isMask READ isMask WRITE setIsMask NOTIFY isMaskChanged)
117 
118  /**
119  * The color to use when drawing this icon when `isMask` is enabled.
120  * If this property is not set or is `Qt::transparent`, the icon will use
121  * the text or the selected text color, depending on if `selected` is set to
122  * true.
123  */
124  Q_PROPERTY(QColor color READ color WRITE setColor NOTIFY colorChanged)
125 
126  /**
127  * Whether the icon is correctly loaded, is asyncronously loading or there was an error.
128  * Note that image loading will not be initiated until the item is shown, so if the Icon is not visible,
129  * it can only have Null or Loading states.
130  * @since 5.15
131  */
132  Q_PROPERTY(Icon::Status status READ status NOTIFY statusChanged)
133 
134  /**
135  * The width of the painted area measured in pixels. This will be smaller than or
136  * equal to the width of the area taken up by the Item itself. This can be 0.
137  *
138  * @since 5.15
139  */
140  Q_PROPERTY(qreal paintedWidth READ paintedWidth NOTIFY paintedAreaChanged)
141 
142  /**
143  * The height of the painted area measured in pixels. This will be smaller than or
144  * equal to the height of the area taken up by the Item itself. This can be 0.
145  *
146  * @since 5.15
147  */
148  Q_PROPERTY(qreal paintedHeight READ paintedHeight NOTIFY paintedAreaChanged)
149 public:
150  enum Status {
151  Null = 0, /// No icon has been set
152  Ready, /// The icon loaded correctly
153  Loading, // The icon is being loaded, but not ready yet
154  Error, /// There was an error while loading the icon, for instance a non existent themed name, or an invalid url
155  };
156  Q_ENUM(Status)
157 
158  Icon(QQuickItem *parent = nullptr);
159  ~Icon();
160 
161  void setSource(const QVariant &source);
162  QVariant source() const;
163 
164  void setActive(bool active = true);
165  bool active() const;
166 
167  bool valid() const;
168 
169  void setSelected(bool selected = true);
170  bool selected() const;
171 
172  void setIsMask(bool mask);
173  bool isMask() const;
174 
175  void setColor(const QColor &color);
176  QColor color() const;
177 
178  QString fallback() const;
179  void setFallback(const QString &fallback);
180 
181  QString placeholder() const;
182  void setPlaceholder(const QString &placeholder);
183 
184  Status status() const;
185 
186  qreal paintedWidth() const;
187  qreal paintedHeight() const;
188 
189  QSGNode *updatePaintNode(QSGNode *node, UpdatePaintNodeData *data) override;
190 
191 Q_SIGNALS:
192  void sourceChanged();
193  void activeChanged();
194  void validChanged();
195  void selectedChanged();
196  void isMaskChanged();
197  void colorChanged();
198  void fallbackChanged(const QString &fallback);
199  void placeholderChanged(const QString &placeholder);
200  void statusChanged();
201  void paintedAreaChanged();
202 
203 protected:
204  void geometryChanged(const QRectF &newGeometry, const QRectF &oldGeometry) override;
205  QImage findIcon(const QSize &size);
206  void handleFinished(QNetworkReply *reply);
207  void handleRedirect(QNetworkReply *reply);
208  QIcon::Mode iconMode() const;
209  bool guessMonochrome(const QImage &img);
210  void setStatus(Status status);
211  void updatePolish() override;
212  void updatePaintedGeometry();
213 
214 private:
215  Kirigami::PlatformTheme *m_theme = nullptr;
216  QPointer<QNetworkReply> m_networkReply;
217  QHash<int, bool> m_monochromeHeuristics;
218  QVariant m_source;
219  Status m_status = Null;
220  bool m_changed;
221  bool m_active;
222  bool m_selected;
223  bool m_isMask;
224  bool m_isMaskHeuristic = false;
225  QImage m_loadedImage;
226  QColor m_color = Qt::transparent;
227  QString m_fallback = QStringLiteral("unknown");
228  QString m_placeholder = QStringLiteral("image-x-icon");
229  qreal m_paintedWidth = 0.0;
230  qreal m_paintedHeight = 0.0;
231 
232  QImage m_icon;
233 };
No icon has been set.
Definition: icon.h:152
Definition: icon.h:18
Status
Definition: icon.h:150
Class for rendering an icon in UI.
Definition: icon.h:26
The icon loaded correctly.
Definition: icon.h:153
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Jun 20 2021 22:38:03 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.