1/* This file is part of the KDE libraries
2 Copyright (C) 1998 Jörg Habenicht (j.habenicht@europemail.com)
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KLED_H
21#define KLED_H
22
23#include <kdeui_export.h>
24
25#include <QtGui/QWidget>
26
27class QColor;
28
29/**
30 * @short An LED widget.
31 *
32 * Displays a round or rectangular light emitting diode.
33 *
34 * It is configurable to arbitrary colors, the two on/off states and three
35 * styles (or "looks");
36 *
37 * It may display itself in a performant flat view, a round view with
38 * light spot or a round view sunken in the screen.
39 *
40 * \image html kled.png "KDE LED Widget"
41 *
42 * @author Joerg Habenicht, Richard J. Moore (rich@kde.org) 1998, 1999
43 */
44class KDEUI_EXPORT KLed : public QWidget
45{
46 Q_OBJECT
47 Q_ENUMS( State Shape Look )
48 Q_PROPERTY( State state READ state WRITE setState )
49 Q_PROPERTY( Shape shape READ shape WRITE setShape )
50 Q_PROPERTY( Look look READ look WRITE setLook )
51 Q_PROPERTY( QColor color READ color WRITE setColor )
52 Q_PROPERTY( int darkFactor READ darkFactor WRITE setDarkFactor )
53
54 public:
55
56 /**
57 * Status of the light is on/off.
58 * @short LED on/off.
59 */
60 enum State { Off, On };
61
62 /**
63 * Shades of the lamp.
64 * @short LED shape
65 */
66 enum Shape { Rectangular, Circular };
67
68 /**
69 * Displays a flat, round or sunken LED.
70 *
71 * Displaying the LED flat is less time and color consuming,
72 * but not so nice to see.
73 *
74 * The sunken LED itself is (certainly) smaller than the round LED
75 * because of the 3 shading circles and is
76 * most time consuming. Makes sense for LED > 15x15 pixels.
77 *
78 * \b Timings: \n
79 * ( AMD K5/133, Diamond Stealth 64 PCI Graphics, widgetsize 29x29 )
80 * @li flat Approximately 0.7 msec per paint
81 * @li round Approximately 2.9 msec per paint
82 * @li sunken Approximately 3.3 msec per paint
83 *
84 * The widget will be updated on the next repaining event.
85 *
86 * @short LED look.
87 */
88 enum Look { Flat, Raised, Sunken };
89
90 /**
91 * Constructs a green, round LED widget which will initially
92 * be turned on.
93 *
94 * @param parent The parent widget.
95 */
96 explicit KLed( QWidget *parent = 0 );
97
98 /**
99 * Constructs a round LED widget with the supplied color which will
100 * initially be turned on.
101 *
102 * @param color Initial color of the LED.
103 * @param parent The parent widget.
104 * @short Constructor
105 */
106 explicit KLed( const QColor &color, QWidget *parent = 0 );
107
108 /**
109 * Constructor with the color, state and look.
110 *
111 * Differs from above only in the parameters, which configure all settings.
112 *
113 * @param color Initial color of the LED.
114 * @param state Sets the State.
115 * @param look Sets the Look.
116 * @param shape Sets the Shape (rectangular or circular).
117 * @param parent The parent widget.
118 * @short Constructor
119 */
120 KLed( const QColor& color, KLed::State state, KLed::Look look, KLed::Shape shape,
121 QWidget *parent = 0 );
122
123 /**
124 * Destroys the LED widget.
125 * @short Destructor
126 */
127 ~KLed();
128
129 /**
130 * Returns the current color of the widget.
131 *
132 * @see Color
133 * @short Returns LED color.
134 */
135 QColor color() const;
136
137 /**
138 * Returns the current state of the widget (on/off).
139 *
140 * @see State
141 * @short Returns LED state.
142 */
143 State state() const;
144
145 /**
146 * Returns the current look of the widget.
147 *
148 * @see Look
149 * @short Returns LED look.
150 */
151 Look look() const;
152
153 /**
154 * Returns the current shape of the widget.
155 *
156 * @see Shape
157 * @short Returns LED shape.
158 */
159 Shape shape() const;
160
161 /**
162 * Returns the factor to darken the LED.
163 *
164 * @see setDarkFactor()
165 * @short Returns dark factor.
166 */
167 int darkFactor() const;
168
169 /**
170 * Set the color of the widget.
171 *
172 * The LED is shown with Color when in the KLed::On state
173 * or with the darken Color (@see setDarkFactor) in KLed::Off
174 * state.
175 *
176 * The widget calls the update() method, so it will
177 * be updated when entering the main event loop.
178 *
179 * @see Color
180 *
181 * @param color New color of the LED.
182 * @short Sets the LED color.
183 */
184 void setColor( const QColor& color );
185
186 /**
187 * Sets the state of the widget to On or Off.
188 *
189 * The widget will be painted immediately.
190 * @see on() off() toggle()
191 *
192 * @param state The LED state: on or off.
193 * @short Set LED state.
194 */
195 void setState( State state );
196
197 /**
198 * Sets the look of the widget.
199 *
200 * The look may be Flat, Raised or Sunken.
201 *
202 * The widget calls the update() method, so it will
203 * be updated when entering the main event loop.
204 *
205 * @see Look
206 *
207 * @param look New look of the LED.
208 * @short Sets LED look.
209 */
210 void setLook( Look look );
211
212 /**
213 * Set the shape of the LED.
214 *
215 * @param shape The LED shape.
216 * @short Set LED shape.
217 */
218 void setShape( Shape shape );
219
220 /**
221 * Sets the factor to darken the LED in KLed::Off state.
222 *
223 * The @param darkFactor should be greater than 100, otherwise the LED
224 * becomes lighter in KLed::Off state.
225 *
226 * Defaults to 300.
227 *
228 * @see QColor
229 *
230 * @param darkFactor Sets the factor to darken the LED.
231 * @short Sets the factor to darken the LED.
232 */
233 void setDarkFactor( int darkFactor );
234
235 virtual QSize sizeHint() const;
236 virtual QSize minimumSizeHint() const;
237
238 public Q_SLOTS:
239
240 /**
241 * Toggles the state of the led from Off to On or vice versa.
242 *
243 * The widget repaints itself immediately.
244 */
245 void toggle();
246
247 /**
248 * Sets the state of the widget to On.
249 *
250 * The widget will be painted immediately.
251 * @see off() toggle() setState()
252 */
253 void on();
254
255 /**
256 * Sets the state of the widget to Off.
257 *
258 * The widget will be painted immediately.
259 * @see on() toggle() setState()
260 */
261 void off();
262
263 protected:
264 /**
265 * Returns the width of the led.
266 */
267 virtual int ledWidth() const;
268
269 /**
270 * Paints a circular, flat LED.
271 */
272 virtual void paintFlat();
273
274 /**
275 * Paints a circular, raised LED.
276 */
277 virtual void paintRaised();
278
279 /**
280 * Paints a circular, sunken LED.
281 */
282 virtual void paintSunken();
283
284 /**
285 * Paints a rectangular, flat LED.
286 */
287 virtual void paintRect();
288
289 /**
290 * Paints a rectangular LED, either raised or
291 * sunken, depending on its argument.
292 */
293 virtual void paintRectFrame( bool raised );
294
295 void paintEvent( QPaintEvent* );
296 void resizeEvent( QResizeEvent* );
297
298 /**
299 * Paint the cached antialiased pixmap corresponding to the state if any
300 * @return true if the pixmap was painted, false if it hasn't been created yet
301 */
302 bool paintCachedPixmap();
303
304 /**
305 * @internal
306 * invalidates caches after property changes and calls update()
307 */
308 void updateCachedPixmap();
309
310 /**
311 * @internal
312 */
313 void paintLed(Shape shape, Look look);
314
315 private:
316 class Private;
317 Private * const d;
318};
319
320#endif
321