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

diff --git a/otk/timer.hh b/otk/timer.hh
index 610a02e6..d518dc5a 100644
--- a/otk/timer.hh
+++ b/otk/timer.hh
@@ -28,45 +28,103 @@ typedef void *OBTimeoutData;
 //! The type of function which can be set as the callback for an OBTimer firing
 typedef void (*OBTimeoutHandler)(OBTimeoutData);
 
+//! A Timer class which will fire a function when its time elapses
 class OBTimer {
 private:
-  OBTimerQueueManager *manager;
-  OBTimeoutHandler handler;
-  OBTimeoutData data;
-  bool timing, recur;
-
-  timeval _start, _timeout;
-
+  //! The manager which to add ourself to and remove ourself after we are done
+  OBTimerQueueManager *_manager;
+  //! The function to call when the time elapses
+  OBTimeoutHandler _handler;
+  //! The data which gets passed along to the OBTimeoutHandler
+  OBTimeoutData _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 OBTimer objects
   OBTimer(const OBTimer&);
+  //! Disallows copying of OBTimer objects
   OBTimer& operator=(const OBTimer&);
 
 public:
+  //! Constructs a new OBTimer object
+  /*!
+    @param m The OBTimerQueueManager 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
+  */
   OBTimer(OBTimerQueueManager *m, OBTimeoutHandler h, OBTimeoutData d);
+  //! Destroys the OBTimer object
   virtual ~OBTimer();
 
-  void fireTimeout();
+  //! Fires the timer, calling its OBTimeoutHandler
+  void fire();
 
-  inline bool isTiming() const { return timing; }
-  inline bool isRecurring() const { return recur; }
+  //! Returns if the OBTimer is started and timing
+  inline bool timing() const { return _timing; }
+  //! Returns if the OBTimer is going to repeat
+  inline bool recurring() const { return _recur; }
 
-  inline const timeval &getTimeout() const { return _timeout; }
-  inline const timeval &getStartTime() const { return _start; }
+  //! Gets the amount of time the OBTimer should last before firing
+  inline const timeval &timeout() const { return _timeout; }
+  //! Gets the time at which the OBTimer started
+  inline const timeval &startTime() const { return _start; }
 
-  timeval timeRemaining(const timeval &tm) const;
+  //! Gets the amount of time left before the OBTimer fires
+  timeval remainingTime(const timeval &tm) const;
+  //! Returns if the OBTimer 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 OBTimer will fire
+  timeval endTime() const;
+
+  //! Sets the OBTimer 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 OBTimer to last in milliseconds
+  /*!
+    @param t The number of milliseconds the timer should last
+  */
   void setTimeout(long t);
+  //! Sets the amount of time the OBTimer 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 OBTimer::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
 
+  //! Determines if this OBTimer will fire before a second OBTimer object
+  /*!
+    @param other The second OBTimer with which to compare
+    @return true if this OBTimer will fire before 'other'; otherwise, false
+  */
   bool operator<(const OBTimer& other) const
-  { return shouldFire(other.endpoint()); }
+  { return shouldFire(other.endTime()); }
 };
 
 }