runtime/kcontrol/componentchooser/ktimerdialog.h

   1 /*
   2  *  This file is part of the KDE Libraries
   3  *  Copyright (C) 2002 Hamish Rodda <rodda@kde.org>
   4  *
   5  *  This library is free software; you can redistribute it and/or
   6  *  modify it under the terms of the GNU Library General Public
   7  *  License as published by the Free Software Foundation; either
   8  *  version 2 of the License, or (at your option) any later version.
   9  *
  10  *  This library is distributed in the hope that it will be useful,
  11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  *  Library General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU Library General Public License
  16  *  along with this library; see the file COPYING.LIB.  If not, write to
  17  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18  *  Boston, MA 02110-1301, USA.
  19  *
  20  */
  21 #ifndef _KTIMERDIALOG_H_
  22 #define _KTIMERDIALOG_H_
  23
  24 #include <QLabel>
  25
  26 #include <kdialog.h>
  27 #include <kvbox.h>
  28
  29 class QTimer;
  30 class KHBox;
  31 class QProgressBar;
  32 class QLabel;
  33
  34 /**
  35  * Provides a dialog that is only available for a specified amount
  36  * of time, and reports the time remaining to the user.
  37  *
  38  * The timer is capable of counting up or down, for any number of milliseconds.
  39  *
  40  * The button which is activated upon timeout can be specified, as can the
  41  * update interval for the dialog box.
  42  *
  43  * In addition, this class retains all of the functionality of @see KDialog.
  44  *
  45  * @short A dialog with a time limit and corresponding UI features.
  46  * @author Hamish Rodda <rodda@kde.org>
  47  */
  48 class KTimerDialog : public KDialog
  49 {
  50   Q_OBJECT
  51
  52   public:
  53
  54     /**
  55      * @li @p CountDown - The timer counts downwards from the seconds given.
  56      * @li @p CountUp - The timer counts up to the number of seconds given.
  57      * @li @p Manual - The timer is not invoked; the caller must update the
  58      * progress.
  59      */
  60     enum TimerStyle
  61     {
  62         CountDown,
  63         CountUp,
  64         Manual
  65     };
  66
  67     /**
  68      * Constructor for the standard mode where you must specify the main
  69      * widget with @ref setMainWidget() . See @see KDialog for further details.
  70      *
  71      * For the rest of the arguments, See @see KDialog .
  72      */
  73     explicit KTimerDialog( int msec, TimerStyle style=CountDown, QWidget *parent=0,
  74                            const QString &caption=QString(),
  75                            int buttonMask=Ok|Apply|Cancel, ButtonCode defaultButton=Ok,
  76                            bool separator=false,
  77                            const KGuiItem &user1=KGuiItem(),
  78                            const KGuiItem &user2=KGuiItem(),
  79                            const KGuiItem &user3=KGuiItem() );
  80
  81     /**
  82      * Destructor.
  83      */
  84     ~KTimerDialog();
  85
  86     /**
  87      * Execute the dialog modelessly - see @see QDialog .
  88      */
  89     virtual void setVisible( bool visible );
  90
  91     /**
  92      * Set the refresh interval for the timer progress. Defaults to one second.
  93      */
  94     void setRefreshInterval( int msec );
  95
  96     /**
  97      * Retrieves the @ref ButtonCode which will be activated once the timer
  98      * times out. @see setTimeoutButton
  99      */
 100     int timeoutButton() const;
 101
 102     /**
 103      * Sets the @ref ButtonCode to determine which button will be activated
 104      * once the timer times out. @see timeoutButton
 105      */
 106     void setTimeoutButton( ButtonCode newButton );
 107
 108     /**
 109      * Retrieves the current @ref TimerStyle. @see setTimerStyle
 110      */
 111     int timerStyle() const;
 112
 113     /**
 114      * Sets the @ref TimerStyle. @see timerStyle
 115      */
 116     void setTimerStyle( TimerStyle newStyle );
 117
 118     /**
 119      * Overridden function which is used to set the main widget of the dialog.
 120      * @see KDialog::setMainWidget.
 121      */
 122     void setMainWidget( QWidget *widget );
 123
 124   Q_SIGNALS:
 125     /**
 126      * Signal which is emitted once the timer has timed out.
 127      */
 128     void timerTimeout();
 129
 130   public Q_SLOTS:
 131     /**
 132      * Execute the dialog modally - see @see QDialog .
 133      */
 134     int exec();
 135
 136   private Q_SLOTS:
 137     /**
 138      * Updates the dialog with the current progress levels.
 139      */
 140     void slotUpdateTime( bool update = true );
 141
 142     /**
 143      * The internal
 144      */
 145     void slotInternalTimeout();
 146
 147   private:
 148     /**
 149      * Prepares the layout that manages the widgets of the dialog
 150      */
 151     void setupLayout();
 152
 153     QTimer *totalTimer;
 154     QTimer *updateTimer;
 155     int msecRemaining, updateInterval, msecTotal;
 156
 157     ButtonCode buttonOnTimeout;
 158     TimerStyle tStyle;
 159
 160     KHBox *timerWidget;
 161     QProgressBar *timerProgress;
 162     QLabel *timerLabel;
 163     KVBox *mainWidget;
 164
 165     class KTimerDialogPrivate;
 166     KTimerDialogPrivate *d;
 167 };
 168
 169 #endif
 170
 171
 172