Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Dec 10, 2007, 3:21:33 PM (17 years ago)
Author:
landauf
Message:

More documentation and comments (it's so much fun!)

File:
1 edited

Legend:

Unmodified
Added
Removed

  • code/branches/objecthierarchy/src/orxonox/objects/Timer.h

    r443 r452  
     1/*!
     2    @file Timer.h
     3    @brief Definition and Implementation of the Timer class.
     4
     5    The Timer is a callback-object, calling a given function after a given time-interval.
     6
     7    Usage:
     8    header.h:
     9        class ClassName
     10        {
     11            public:
     12                ClassName();
     13                void functionName();
     14                Timer myTimer;
     15        };
     16
     17    source.cc:
     18        ClassName::ClassName()
     19        {
     20            myTimer.setTimer(interval_in_seconds, bLoop, this, &ClassName::functionName);
     21        }
     22
     23        void ClassName::functionName()
     24        {
     25            whateveryouwant();
     26            something(else);
     27        }
     28*/
     29
    130#ifndef _Timer_H__
    231#define _Timer_H__
    … …  
    736namespace orxonox
    837{
     38    //! TimerBase is the parent of the Timer class.
    939    class TimerBase : public OrxonoxClass
    1040    {
    … …  
    1242
    1343        public:
     44            /** @brief Constructor: Sets the default-values. */
    1445            TimerBase()
    1546            {
    … …  
    2556            virtual void run() const = 0;
    2657
     58            /** @brief Starts the Timer: Function-call after 'interval' seconds. */
    2759            inline void startTimer() { this->bActive_ = true; this->time_ = this->interval_; }
     60            /** @brief Stops the Timer. */
    2861            inline void stopTimer() { this->bActive_ = false; this->time_ = this->interval_; }
     62            /** @brief Pauses the Timer - it will continue with the actual state if you unpause it. */
    2963            inline void pauseTimer() { this->bActive_ = false; }
     64            /** @brief Unpauses the Timer - continues with the given state. */
    3065            inline void unpauseTimer() { this->bActive_ = true; }
     66            /** @returns true if the Timer is active (= not stoped, not paused). */
    3167            inline bool isActive() const { return this->bActive_; }
    3268
    3369        protected:
    34             float interval_;
    35             bool bLoop_;
    36             bool bActive_;
     70            float interval_;    //!< The time-interval in seconds
     71            bool bLoop_;        //!< If true, the function gets called every 'interval' seconds
     72            bool bActive_;      //!< If true, the Timer ticks and calls the function if the time's up
    3773
    38             float time_;
     74            float time_;        //!< Internal variable, counting the time till the next function-call
    3975    };
    4076
     77    //! The Timer is a callback-object, calling a given function after a given time-interval.
    4178    template <class T = BaseObject>
    4279    class Timer : public TimerBase
    4380    {
    4481        public:
     82            /** @brief Constructor: Sets the default-values. */
    4583            Timer()
    4684            {
    … …  
    4987            }
    5088
     89            /**
     90                @brief Constructor: Initializes the Timer with given values.
     91                @param interval The timer-interval in seconds
     92                @param bLoop If true, the function gets called every 'interval' seconds
     93                @param object The object owning the timer and the function
     94                @param timerFunction A function pointer to the function to call
     95            */
    5196            Timer(float interval, bool bLoop, T* object, void (T::*timerFunction)())
    5297            {
    … …  
    5499            }
    55100
     101            /**
     102                @brief Initializes the Timer with given values.
     103                @param interval The timer-interval in seconds
     104                @param bLoop If true, the function gets called every 'interval' seconds
     105                @param object The object owning the timer and the function
     106                @param timerFunction A function pointer to the function to call
     107            */
    56108            void setTimer(float interval, bool bLoop, T* object, void (T::*timerFunction)())
    57109            {
    … …  
    65117            }
    66118
     119            /** @brief Calls the given function of the given object. */
    67120            void run() const
    68121            {
    … …  
    75128    };
    76129
     130    //! The TimerFrameListener manages all Timers in the game.
    77131    class TimerFrameListener : public Ogre::FrameListener
    78132    {
    79133        private:
     134            /** @brief Gets called before a frame gets rendered. */
    80135            bool frameStarted(const Ogre::FrameEvent &evt)
    81136            {
     137                // Iterate through all Timers
    82138                for (Iterator<TimerBase> it = ObjectList<TimerBase>::start(); it; ++it)
    83139                {
    84140                    if (it->isActive())
    85141                    {
     142                        // If active: Decrease the timer by the duration of the last frame
    86143                        it->time_ -= evt.timeSinceLastFrame;
    87144
    88145                        if (it->time_ <= 0)
    89146                        {
     147                            // It's time to call the function
    90148                            if (it->bLoop_)
    91                                 it->time_ += it->interval_;
     149                                it->time_ += it->interval_; // Q: Why '+=' and not '='? A: Think about it. It's more accurate like that. Seriously.
    92150                            else
    93                                 it->stopTimer();
     151                                it->stopTimer(); // Stop the timer if we don't want to loop
    94152
    95153                            it->run();
Note: See TracChangeset for help on using the changeset viewer.