kalarm/lib/synchtimer.h

   1 /*
   2  *  synchtimer.h  -  timers which synchronize to time boundaries
   3  *  Program:  kalarm
   4  *  Copyright © 2004,2005 by David Jarvie <djarvie@kde.org>
   5  *
   6  *  This program is free software; you can redistribute it and/or modify
   7  *  it under the terms of the GNU General Public License as published by
   8  *  the Free Software Foundation; either version 2 of the License, or
   9  *  (at your option) any later version.
  10  *
  11  *  This program is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  *  GNU General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU General Public License along
  17  *  with this program; if not, write to the Free Software Foundation, Inc.,
  18  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  19  */
  20
  21 #ifndef SYNCHTIMER_H
  22 #define SYNCHTIMER_H
  23
  24 /* @file synchtimer.h - timers which synchronize to time boundaries */
  25
  26 #include <QObject>
  27 #include <QList>
  28 #include <QByteArray>
  29 #include <QDateTime>
  30 class QTimer;
  31
  32 /** SynchTimer is a virtual base class for application-wide timers synchronized
  33  *  to a time boundary.
  34  *
  35  *  @author David Jarvie <djarvie@kde.org>
  36  */
  37 class SynchTimer : public QObject
  38 {
  39         Q_OBJECT
  40     public:
  41         virtual ~SynchTimer();
  42
  43         struct Connection
  44         {
  45             Connection() { }
  46             Connection(QObject* r, const char* s) : receiver(r), slot(s) { }
  47             bool operator==(const Connection& c) const  { return receiver == c.receiver && slot == c.slot; }
  48             QObject*   receiver;
  49             QByteArray slot;
  50         };
  51     protected:
  52         SynchTimer();
  53         virtual void        start() = 0;
  54         void                connecT(QObject* receiver, const char* member);
  55         void                disconnecT(QObject* receiver, const char* member = Q_NULLPTR);
  56         bool                hasConnections() const   { return !mConnections.isEmpty(); }
  57
  58         QTimer*             mTimer;
  59
  60     protected Q_SLOTS:
  61         virtual void        slotTimer() = 0;
  62
  63     private Q_SLOTS:
  64         void                slotReceiverGone(QObject* r)  { disconnecT(r); }
  65
  66     private:
  67         SynchTimer(const SynchTimer&);   // prohibit copying
  68         QList<Connection>   mConnections;  // list of current clients
  69 };
  70
  71
  72 /** MinuteTimer is an application-wide timer synchronized to the minute boundary.
  73  *
  74  *  @author David Jarvie <djarvie@kde.org>
  75  */
  76 class MinuteTimer : public SynchTimer
  77 {
  78         Q_OBJECT
  79     public:
  80         virtual ~MinuteTimer()  { mInstance = Q_NULLPTR; }
  81         /** Connect to the timer signal.
  82          *  @param receiver Receiving object.
  83          *  @param member Slot to activate.
  84          */
  85         static void connect(QObject* receiver, const char* member)
  86                            { instance()->connecT(receiver, member); }
  87         /** Disconnect from the timer signal.
  88          *  @param receiver Receiving object.
  89          *  @param member Slot to disconnect. If null, all slots belonging to
  90          *                @p receiver will be disconnected.
  91          */
  92         static void disconnect(QObject* receiver, const char* member = Q_NULLPTR)
  93                            { if (mInstance) mInstance->disconnecT(receiver, member); }
  94
  95     protected:
  96         MinuteTimer() : SynchTimer() { }
  97         static MinuteTimer* instance();
  98         void        start() Q_DECL_OVERRIDE    { slotTimer(); }
  99
 100     protected Q_SLOTS:
 101         void        slotTimer() Q_DECL_OVERRIDE;
 102
 103     private:
 104         static MinuteTimer* mInstance;     // the one and only instance
 105 };
 106
 107
 108 /** DailyTimer is an application-wide timer synchronized to a specified time of day, local time.
 109  *
 110  *  Daily timers come in two flavors: fixed, which can only be accessed through static methods,
 111  *  and variable, whose time can be adjusted and which are accessed through non-static methods.
 112  *
 113  *  @author David Jarvie <djarvie@kde.org>
 114  */
 115 class DailyTimer : public SynchTimer
 116 {
 117         Q_OBJECT
 118     public:
 119         virtual ~DailyTimer();
 120         /** Connect to the timer signal which triggers at the given fixed time of day.
 121          *  A new timer is created if necessary.
 122          *  @param timeOfDay Time at which the timer is to trigger.
 123          *  @param receiver Receiving object.
 124          *  @param member Slot to activate.
 125          */
 126         static void connect(const QTime& timeOfDay, QObject* receiver, const char* member)
 127                            { fixedInstance(timeOfDay)->connecT(receiver, member); }
 128         /** Disconnect from the timer signal which triggers at the given fixed time of day.
 129          *  If there are no remaining connections to that timer, it is destroyed.
 130          *  @param timeOfDay Time at which the timer triggers.
 131          *  @param receiver Receiving object.
 132          *  @param member Slot to disconnect. If null, all slots belonging to
 133          *                @p receiver will be disconnected.
 134          */
 135         static void disconnect(const QTime& timeOfDay, QObject* receiver, const char* member = Q_NULLPTR);
 136         /** Change the time at which this variable timer triggers.
 137          *  @param newTimeOfDay New time at which the timer should trigger.
 138          *  @param triggerMissed If true, and if @p newTimeOfDay < @p oldTimeOfDay, and if the current
 139          *                       time is between @p newTimeOfDay and @p oldTimeOfDay, the timer will be
 140          *                       triggered immediately so as to avoid missing today's trigger.
 141          */
 142         void changeTime(const QTime& newTimeOfDay, bool triggerMissed = true);
 143         /** Return the current time of day at which this variable timer triggers. */
 144         QTime timeOfDay() const  { return mTime; }
 145
 146     protected:
 147         /** Construct an instance.
 148          *  The constructor is protected to ensure that for variable timers, only derived classes
 149          *  can construct instances. This ensures that multiple timers are not created for the same
 150          *  use.
 151          */
 152         DailyTimer(const QTime&, bool fixed);
 153         /** Return the instance which triggers at the specified fixed time of day,
 154          *  optionally creating a new instance if necessary.
 155          *  @param timeOfDay Time at which the timer triggers.
 156          *  @param create    If true, create a new instance if none already exists
 157          *                   for @p timeOfDay.
 158          *  @return The instance for @p timeOfDay, or 0 if it does not exist.
 159          */
 160         static DailyTimer* fixedInstance(const QTime& timeOfDay, bool create = true);
 161         void start() Q_DECL_OVERRIDE;
 162
 163     protected Q_SLOTS:
 164         void slotTimer() Q_DECL_OVERRIDE;
 165
 166     private:
 167         static QList<DailyTimer*>  mFixedTimers;   // list of timers whose trigger time is fixed
 168         QTime  mTime;
 169         QDate  mLastDate;  // the date on which the timer was last triggered
 170         bool   mFixed;     // the time at which the timer triggers cannot be changed
 171 };
 172
 173
 174 /** MidnightTimer is an application-wide timer synchronized to midnight, local time.
 175  *
 176  *  @author David Jarvie <djarvie@kde.org>
 177  */
 178 class MidnightTimer
 179 {
 180     public:
 181         /** Connect to the timer signal.
 182          *  @param receiver Receiving object.
 183          *  @param member Slot to activate.
 184          */
 185         static void connect(QObject* receiver, const char* member)
 186                            { DailyTimer::connect(QTime(0,0), receiver, member); }
 187         /** Disconnect from the timer signal.
 188          *  @param receiver Receiving object.
 189          *  @param member Slot to disconnect. If null, all slots belonging to
 190          *                @p receiver will be disconnected.
 191          */
 192         static void disconnect(QObject* receiver, const char* member = Q_NULLPTR)
 193                            { DailyTimer::disconnect(QTime(0,0), receiver, member); }
 194
 195 };
 196
 197 #endif // SYNCHTIMER_H
 198
 199 // vim: et sw=4: