1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1998 Jörg Habenicht <j.habenicht@europemail.com>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KLED_H
9#define KLED_H
10
11#include <kwidgetsaddons_export.h>
12
13#include <QWidget>
14#include <memory>
15
16class QColor;
17
18/*!
19 * \class KLed
20 * \inmodule KWidgetsAddons
21 *
22 * \brief An LED widget.
23 *
24 * Displays a round or rectangular light emitting diode.
25 *
26 * It is configurable to arbitrary colors, the two on/off states and three
27 * styles (or "looks");
28 *
29 * It may display itself in a performant flat view, a round view with
30 * light spot or a round view sunken in the screen.
31 *
32 * \image kled.png "KLed Widget"
33 */
34class KWIDGETSADDONS_EXPORT KLed : public QWidget
35{
36 Q_OBJECT
37
38 /*!
39 * \property KLed::state
40 */
41 Q_PROPERTY(State state READ state WRITE setState)
42
43 /*!
44 * \property KLed::shape
45 */
46 Q_PROPERTY(Shape shape READ shape WRITE setShape)
47
48 /*!
49 * \property KLed::look
50 */
51 Q_PROPERTY(Look look READ look WRITE setLook)
52
53 /*!
54 * \property KLed::color
55 */
56 Q_PROPERTY(QColor color READ color WRITE setColor)
57
58 /*!
59 * \property KLed::darkFactor
60 */
61 Q_PROPERTY(int darkFactor READ darkFactor WRITE setDarkFactor)
62
63public:
64 /*!
65 * Status of the light is on/off.
66 * \brief LED on/off.
67 *
68 * \value Off
69 * \value On
70 */
71 enum State {
72 Off,
73 On
74 };
75 Q_ENUM(State)
76
77 /*!
78 * Shades of the lamp.
79 * \brief LED shape
80 *
81 * \value Rectangular
82 * \value Circular
83 */
84 enum Shape {
85 Rectangular,
86 Circular
87 };
88 Q_ENUM(Shape)
89
90 /*!
91 * Displays a flat, round or sunken LED.
92 *
93 * \brief LED look.
94 *
95 * \value Flat
96 * \value Raised
97 * \value Sunken
98 */
99 enum Look {
100 Flat,
101 Raised,
102 Sunken,
103 };
104 Q_ENUM(Look)
105
106 /*!
107 * Constructs a green, round LED widget which will initially
108 * be turned on.
109 *
110 * \a parent The parent widget.
111 */
112 explicit KLed(QWidget *parent = nullptr);
113
114 /*!
115 * Constructs a round LED widget with the supplied color which will
116 * initially be turned on.
117 *
118 * \a color Initial color of the LED.
119 *
120 * \a parent The parent widget.
121 */
122 explicit KLed(const QColor &color, QWidget *parent = nullptr);
123
124 /*!
125 * Constructor with the color, state and look.
126 *
127 * Differs from above only in the parameters, which configure all settings.
128 *
129 * \a color Initial color of the LED.
130 *
131 * \a state Sets the State.
132 *
133 * \a look Sets the Look.
134 *
135 * \a shape Sets the Shape (rectangular or circular).
136 *
137 * \a parent The parent widget.
138 */
139 KLed(const QColor &color, KLed::State state, KLed::Look look, KLed::Shape shape, QWidget *parent = nullptr);
140
141 ~KLed() override;
142
143 /*!
144 * Returns the current color of the widget.
145 * \sa setColor()
146 */
147 QColor color() const;
148
149 /*!
150 * Returns the current state of the widget (on/off).
151 *
152 * \sa State
153 */
154 State state() const;
155
156 /*!
157 * Returns the current look of the widget.
158 *
159 * \sa Look
160 */
161 Look look() const;
162
163 /*!
164 * Returns the current shape of the widget.
165 *
166 * \sa Shape
167 */
168 Shape shape() const;
169
170 /*!
171 * Returns the factor to darken the LED.
172 *
173 * \sa setDarkFactor()
174 */
175 int darkFactor() const;
176
177 /*!
178 * Set the color of the widget.
179 *
180 * The LED is shown with \a color when in the KLed::On state
181 * or with the darken color in KLed::Off state.
182 *
183 * The widget calls the update() method, so it will
184 * be updated when entering the main event loop.
185 *
186 * \a color New color of the LED.
187 *
188 * \sa color() darkFactor()
189 */
190 void setColor(const QColor &color);
191
192 /*!
193 * Sets the state of the widget to On or Off.
194 *
195 * \a state The LED state: on or off.
196 *
197 * \sa on() off() toggle()
198 */
199 void setState(State state);
200
201 /*!
202 * Sets the look of the widget.
203 *
204 * The look may be Flat, Raised or Sunken.
205 *
206 * The widget calls the update() method, so it will
207 * be updated when entering the main event loop.
208 *
209 * \a look New look of the LED.
210 *
211 * \sa Look
212 */
213 void setLook(Look look);
214
215 /*!
216 * Set the shape of the LED.
217 *
218 * \a shape The LED shape.
219 * \brief Set LED shape.
220 */
221 void setShape(Shape shape);
222
223 /*!
224 * Sets the factor to darken the LED in KLed::Off state.
225 *
226 * The \a darkFactor should be greater than 100, otherwise the LED
227 * becomes lighter in KLed::Off state.
228 *
229 * Defaults to 300.
230 *
231 * \a darkFactor Sets the factor to darken the LED.
232 *
233 * \sa setColor
234 */
235 void setDarkFactor(int darkFactor);
236
237 QSize sizeHint() const override;
238 QSize minimumSizeHint() const override;
239
240public Q_SLOTS:
241
242 /*!
243 * Toggles the state of the led from Off to On or vice versa.
244 */
245 void toggle();
246
247 /*!
248 * Sets the state of the widget to On.
249 *
250 * \sa off(), toggle(), setState()
251 */
252 void on();
253
254 /*!
255 * Sets the state of the widget to Off.
256 *
257 * \sa on(), toggle(), setState()
258 */
259 void off();
260
261protected:
262 void paintEvent(QPaintEvent *) override;
263 void resizeEvent(QResizeEvent *) override;
264
265private:
266 /*
267 * invalidates caches after property changes and calls update()
268 */
269 KWIDGETSADDONS_NO_EXPORT void updateCachedPixmap();
270
271 KWIDGETSADDONS_NO_EXPORT void updateAccessibleName();
272
273private:
274 std::unique_ptr<class KLedPrivate> const d;
275};
276
277#endif
278

source code of kwidgetsaddons/src/kled.h