X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=otk%2Ftimer.hh;h=7d3e726d224c464e0be69668d9d352dcd7e3a600;hb=4c71c71d57e87c5273e09976fbac5b3a2f83bc52;hp=610a02e6c8a10d24a0ab98b662aa8cf040b97093;hpb=b0a532db8adeb909fa2cd8e518ca6917a2d7df0a;p=chaz%2Fopenbox

diff --git a/otk/timer.hh b/otk/timer.hh
index 610a02e6..7d3e726d 100644
--- a/otk/timer.hh
+++ b/otk/timer.hh
@@ -1,4 +1,4 @@
-// -*- mode: C++; indent-tabs-mode: nil; -*-
+// -*- mode: C++; indent-tabs-mode: nil; c-basic-offset: 2; -*-
 #ifndef   __timer_hh
 #define   __timer_hh
 
@@ -17,56 +17,114 @@ extern "C" {
 
 namespace otk {
 
-class OBTimerQueueManager;
+class TimerQueueManager;
 
-//! The data passed to the OBTimeoutHandler function.
+//! The data passed to the TimeoutHandler function.
 /*!
   Note: this is a very useful place to put an object instance, and set the
   event handler to a static function in the same class.
 */
-typedef void *OBTimeoutData;
-//! The type of function which can be set as the callback for an OBTimer firing
-typedef void (*OBTimeoutHandler)(OBTimeoutData);
+typedef void *TimeoutData;
+//! The type of function which can be set as the callback for a Timer firing
+typedef void (*TimeoutHandler)(TimeoutData);
 
-class OBTimer {
+//! A Timer class which will fire a function when its time elapses
+class Timer {
 private:
-  OBTimerQueueManager *manager;
-  OBTimeoutHandler handler;
-  OBTimeoutData data;
-  bool timing, recur;
-
-  timeval _start, _timeout;
-
-  OBTimer(const OBTimer&);
-  OBTimer& operator=(const OBTimer&);
+  //! The manager which to add ourself to and remove ourself after we are done
+  TimerQueueManager *_manager;
+  //! The function to call when the time elapses
+  TimeoutHandler _handler;
+  //! The data which gets passed along to the TimeoutHandler
+  TimeoutData _data;
+  //! Determines if the timer is currently started
+  bool _timing;
+  //! When this is true, the timer will reset itself to fire again every time
+  bool _recur;
+
+  //! The time at which the timer started
+  timeval _start;
+  //! The time at which the timer is going to fire
+  timeval _timeout;
+
+  //! Disallows copying of Timer objects
+  Timer(const Timer&);
+  //! Disallows copying of Timer objects
+  Timer& operator=(const Timer&);
 
 public:
-  OBTimer(OBTimerQueueManager *m, OBTimeoutHandler h, OBTimeoutData d);
-  virtual ~OBTimer();
-
-  void fireTimeout();
-
-  inline bool isTiming() const { return timing; }
-  inline bool isRecurring() const { return recur; }
-
-  inline const timeval &getTimeout() const { return _timeout; }
-  inline const timeval &getStartTime() const { return _start; }
-
-  timeval timeRemaining(const timeval &tm) const;
+  //! Constructs a new Timer object
+  /*!
+    @param m The TimerQueueManager with which to associate. The manager
+             specified will be resposible for making this timer fire.
+    @param h The function to call when the timer fires
+    @param d The data to pass along to the function call when the timer fires
+  */
+  Timer(TimerQueueManager *m, TimeoutHandler h, TimeoutData d);
+  //! Destroys the Timer object
+  virtual ~Timer();
+
+  //! Fires the timer, calling its TimeoutHandler
+  void fire();
+
+  //! Returns if the Timer is started and timing
+  inline bool timing() const { return _timing; }
+  //! Returns if the Timer is going to repeat
+  inline bool recurring() const { return _recur; }
+
+  //! Gets the amount of time the Timer should last before firing
+  inline const timeval &timeout() const { return _timeout; }
+  //! Gets the time at which the Timer started
+  inline const timeval &startTime() const { return _start; }
+
+  //! Gets the amount of time left before the Timer fires
+  timeval remainingTime(const timeval &tm) const;
+  //! Returns if the Timer is past its timeout time, and should fire
   bool shouldFire(const timeval &tm) const;
-  timeval endpoint() const;
 
-  inline void recurring(bool b) { recur = b; }
+  //! Gets the time at which the Timer will fire
+  timeval endTime() const;
+
+  //! Sets the Timer to repeat or not
+  /*!
+    @param b If true, the timer is set to repeat; otherwise, it will fire only
+             once
+  */
+  inline void setRecurring(bool b) { _recur = b; }
 
+  //! Sets the amount of time for the Timer to last in milliseconds
+  /*!
+    @param t The number of milliseconds the timer should last
+  */
   void setTimeout(long t);
+  //! Sets the amount of time the Timer should last before firing
+  /*!
+    @param t The amount of time the timer should last
+  */
   void setTimeout(const timeval &t);
 
+  //! Causes the timer to begin
+  /*!
+    The timer fires after the time in Timer::getTimeout has passed since this
+    function was called.
+    Calling this function while the timer is already started will cause it to
+    restart its countdown.
+  */
   void start();  // manager acquires timer
+  //! Causes the timer to stop
+  /*!
+    The timer will no longer fire once this function has been called.
+    Calling this function more than once does not have any effect.
+  */
   void stop();   // manager releases timer
-  void halt();   // halts the timer
 
-  bool operator<(const OBTimer& other) const
-  { return shouldFire(other.endpoint()); }
+  //! Determines if this Timer will fire before a second Timer object
+  /*!
+    @param other The second Timer with which to compare
+    @return true if this Timer will fire before 'other'; otherwise, false
+  */
+  bool operator<(const Timer& other) const
+  { return shouldFire(other.endTime()); }
 };
 
 }