kdeui/widgets/kled.h

   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
  27 class 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  */
  44 class 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
 297     /**
 298      * Paint the cached antialiased pixmap corresponding to the state if any
 299      * @return true if the pixmap was painted, false if it hasn't been created yet
 300      */
 301     bool paintCachedPixmap();
 302
 303   private:
 304     class Private;
 305     Private * const d;
 306 };
 307
 308 #endif