MauiKit Controls

icon.h
1/*
2 * SPDX-FileCopyrightText: 2011 Marco Martin <mart@kde.org>
3 * SPDX-FileCopyrightText: 2014 Aleix Pol Gonzalez <aleixpol@blue-systems.com>
4 * SPDX-FileCopyrightText: 2020 Carson Black <uhhadd@gmail.com>
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
16class QNetworkReply;
17namespace Maui
18{
19class PlatformTheme;
20}
21
22/**
23 * Class for rendering an icon in UI.
24 */
25class Icon : public QQuickItem
26{
28 QML_NAMED_ELEMENT(PrivateIcon)
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)
155public:
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
197public Q_SLOTS:
198 void refresh();
199
201 void sourceChanged();
202 void activeChanged();
203 void validChanged();
204 void selectedChanged();
205 void isMaskChanged();
206 void colorChanged();
207 void fallbackChanged(const QString &fallback);
208 void placeholderChanged(const QString &placeholder);
209 void statusChanged();
210 void paintedAreaChanged();
211
212protected:
213 void geometryChange(const QRectF &newGeometry, const QRectF &oldGeometry) override;
214 QImage findIcon(const QSize &size);
215 void handleFinished(QNetworkReply *reply);
216 void handleRedirect(QNetworkReply *reply);
217 QIcon::Mode iconMode() const;
218 bool guessMonochrome(const QImage &img);
219 void setStatus(Status status);
220 void updatePolish() override;
221 void updatePaintedGeometry();
222 void itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value) override;
223
224private:
225 Maui::PlatformTheme *m_theme = nullptr;
226 QPointer<QNetworkReply> m_networkReply;
227 QHash<int, bool> m_monochromeHeuristics;
228 QVariant m_source;
229 Status m_status = Null;
230 bool m_changed;
231 bool m_active;
232 bool m_selected;
233 bool m_isMask;
234 bool m_isMaskHeuristic = false;
235 QImage m_loadedImage;
236 QColor m_color = Qt::transparent;
237 QString m_fallback = QStringLiteral("unknown");
238 QString m_placeholder = QStringLiteral("image-png");
239 qreal m_paintedWidth = 0.0;
240 qreal m_paintedHeight = 0.0;
241
242 QImage m_icon;
243
244};
qreal paintedHeight
Definition icon.h:154
QString placeholder
Definition icon.h:79
qreal paintedWidth
Definition icon.h:146
bool selected
Definition icon.h:113
bool valid
Definition icon.h:99
QColor color
Definition icon.h:130
Icon::Status status
Definition icon.h:138
QString fallback
Definition icon.h:66
QML_ELEMENTQVariant source
bool isMask
Definition icon.h:122
bool active
Definition icon.h:94
This class is the base for color management in Maui, different platforms can reimplement this class t...
Q_ENUM(...)
Q_OBJECTQ_OBJECT
Q_PROPERTY(...)
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
QSizeF size() const const
transparent
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 19 2024 12:00:22 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.