Changeset 7401 for code/trunk/src/libraries/tools/Timer.h

Timestamp:

Sep 11, 2010, 12:34:00 AM (15 years ago)

Author:

landauf

Message:

merged doc branch back to trunk

Location:

code/trunk

Files:

• . (modified) (1 prop)
• src/libraries/tools/Timer.h (modified) (5 diffs)

code/trunk/src/libraries/tools/Timer.h

@@ -27 +27 @@
  */
 
-/*!
+/**
+    @defgroup Timer Timer
+    @ingroup Tools
+*/
+
+/**
     @file
-    @brief Definition and Implementation of the Timer class.
+    @ingroup Timer
+    @brief Declaration of the Timer class, used to call functions after a given time-interval.
 
-    The Timer is a callback-object, calling a given function after a given time-interval.
+    @anchor TimerExample
 
-    Usage:
+    Timer is a helper class that executes a function after a given amount of time.
+
+    Usage: <br>
     header.h:
-        class ClassName
-        {
-            public:
-                ClassName();
-                void functionName();
-                Timer myTimer;
-        };
+    @code
+    class MyClass
+    {
+        public:
+            MyClass();
+            void functionName();
+
+        private:
+            Timer myTimer;
+    };
+    @endcode
 
     source.cc:
-        #include "core/command/Executor.h"
+    @code
+    #include "core/command/Executor.h"
 
-        ClassName::ClassName()
-        {
-            myTimer.setTimer(interval_in_seconds, bLoop, createExecutor(createFunctor(&ClassName::functionName, this)));
-        }
+    MyClass::MyClass()
+    {
+        myTimer.setTimer(3, false, createExecutor(createFunctor(&ClassName::myFunction, this)));
+    }
 
-        void ClassName::functionName()
-        {
-            whateveryouwant();
-            something(else);
-        }
+    void MyClass::myFunction()
+    {
+        COUT(0) << "Hello World" << std::endl;
+    }
+    @endcode
+
+    The code in this example prints "Hello World" to the console, 3 seconds after creating
+    an instance of MyClass.
 */
 
@@ -73 +89 @@
     void executeDelayedCommand(Timer* timer, const std::string& command);
 
-    //! The Timer is a callback-object, calling a given function after a given time-interval.
+    /**
+        @brief Timer is a helper class that executes a function after a given amount of time.
+
+        @see See @ref TimerExample "Timer.h" for an example.
+    */
     class _ToolsExport Timer : public TimeFactorListener
     {
@@ -82 +102 @@
 
             /**
-                @brief Initializes the Timer with given values.
-                @param interval The timer-interval in seconds
-                @param bLoop If true, the function gets called every 'interval' seconds
-                @param object The object owning the timer and the function
-                @param executor A executor of the function to call
+                @brief Initializes and starts the timer, which will call an executor after some time.
+                @param interval         The timer-interval in seconds
+                @param bLoop            If true, the executor gets called every @a interval seconds
+                @param executor         The executor that will be called
+                @param bKillAfterCall   If true, the timer will be deleted after the executor was called
             */
             void setTimer(float interval, bool bLoop, const ExecutorPtr& executor, bool bKillAfterCall = false)
@@ -101 +121 @@
             void run();
 
-            /** @brief Starts the Timer: Function-call after 'interval' seconds. */
+            /// Re-starts the Timer: The executor will be called after @a interval seconds.
             inline void startTimer()
                 { this->bActive_ = true; this->time_ = this->interval_; }
-            /** @brief Stops the Timer. */
+            /// Stops the Timer.
             inline void stopTimer()
                 { this->bActive_ = false; this->time_ = this->interval_; }
-            /** @brief Pauses the Timer - it will continue with the actual state if you unpause it. */
+            /// Pauses the Timer - it will continue with the actual state if you call unpauseTimer().
             inline void pauseTimer()
                 { this->bActive_ = false; }
-            /** @brief Unpauses the Timer - continues with the given state. */
+            /// Unpauses the Timer - continues with the given state.
             inline void unpauseTimer()
                 { this->bActive_ = true; }
-            /** @brief Returns true if the Timer is active (= not stoped, not paused). @return True = Time is active */
+            /// Returns true if the Timer is active (neither stoped nor paused).
             inline bool isActive() const
                 { return this->bActive_; }
-            /** @brief Returns the remaining time until the Timer calls the function. @return The remaining time */
+            /// Returns the remaining time until the Timer calls the executor.
             inline float getRemainingTime() const
                 { return static_cast<float>(this->time_ / 1000000.0f); }
-            /** @brief Gives the Timer some extra time. @param time The amount of extra time in seconds */
+            /// Increases the remaining time of the Timer by the given amount of time (in seconds).
             inline void addTime(float time)
                 { if (time > 0.0f) this->time_ += static_cast<long long>(time * 1000000.0f); }
-            /** @brief Decreases the remaining time of the Timer. @param time The amount of time to remove */
+            /// Decreases the remaining time of the Timer by the given amount of time (in seconds)
             inline void removeTime(float time)
                 { if (time > 0.0f) this->time_ -= static_cast<long long>(time * 1000000.0f); }
-            /** @brief Sets the interval of the Timer. @param interval The interval */
+            /// Changes the calling interval.
             inline void setInterval(float interval)
                 { this->interval_ = static_cast<long long>(interval * 1000000.0f); }
-            /** @brief Sets bLoop to a given value. @param bLoop True = loop */
+            /// Defines if the timer call the executor every @a interval seconds or only once.
             inline void setLoop(bool bLoop)
                 { this->bLoop_ = bLoop; }
@@ -137 +157 @@
             void init();
 
-            ExecutorPtr executor_;  //!< The executor of the function that should be called when the time expires
+            ExecutorPtr executor_;  //!< The executor of the function that will be called when the time expires
 
             long long interval_;    //!< The time-interval in micro seconds
-            bool bLoop_;            //!< If true, the function gets called every 'interval' seconds
-            bool bActive_;          //!< If true, the Timer ticks and calls the function if the time's up
-            bool bKillAfterCall_;   //!< If true the timer gets deleted after it called the function
+            bool bLoop_;            //!< If true, the executor gets called every @a interval seconds
+            bool bActive_;          //!< If true, the Timer ticks and calls the executor if the time's up
+            bool bKillAfterCall_;   //!< If true the timer gets deleted after it expired and called the executor
 
-            long long time_;        //!< Internal variable, counting the time till the next function-call
+            long long time_;        //!< Internal variable, counting the time untill the next executor-call
     };
 }