include/wx/timer.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/timer.h
   3 // Purpose:     wxTimer, wxStopWatch and global time-related functions
   4 // Author:      Julian Smart
   5 // Modified by: Vadim Zeitlin (wxTimerBase)
   6 //              Guillermo Rodriguez (global clean up)
   7 // Created:     04/01/98
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) Julian Smart
  10 // Licence:     wxWindows licence
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 #ifndef _WX_TIMER_H_BASE_
  14 #define _WX_TIMER_H_BASE_
  15
  16 #include "wx/defs.h"
  17
  18 #if wxUSE_TIMER
  19
  20 #include "wx/object.h"
  21 #include "wx/longlong.h"
  22 #include "wx/event.h"
  23 #include "wx/stopwatch.h" // for backwards compatibility
  24 #include "wx/utils.h"
  25
  26
  27 // more readable flags for Start():
  28
  29 // generate notifications periodically until the timer is stopped (default)
  30 #define wxTIMER_CONTINUOUS false
  31
  32 // only send the notification once and then stop the timer
  33 #define wxTIMER_ONE_SHOT true
  34
  35 class WXDLLIMPEXP_BASE wxTimerImpl;
  36
  37 // the interface of wxTimer class
  38 class WXDLLIMPEXP_BASE wxTimer : public wxEvtHandler
  39 {
  40 public:
  41     // ctors and initializers
  42     // ----------------------
  43
  44     // default: if you don't call SetOwner(), your only chance to get timer
  45     // notifications is to override Notify() in the derived class
  46     wxTimer()
  47     {
  48         Init();
  49         SetOwner(this);
  50     }
  51
  52     // ctor which allows to avoid having to override Notify() in the derived
  53     // class: the owner will get timer notifications which can be handled with
  54     // EVT_TIMER
  55     wxTimer(wxEvtHandler *owner, int timerid = wxID_ANY)
  56     {
  57         Init();
  58         SetOwner(owner, timerid);
  59     }
  60
  61     // same as ctor above
  62     void SetOwner(wxEvtHandler *owner, int timerid = wxID_ANY);
  63
  64     virtual ~wxTimer();
  65
  66
  67     // working with the timer
  68     // ----------------------
  69
  70     // NB: Start() and Stop() are not supposed to be overridden, they are only
  71     //     virtual for historical reasons, only Notify() can be overridden
  72
  73     // start the timer: if milliseconds == -1, use the same value as for the
  74     // last Start()
  75     //
  76     // it is now valid to call Start() multiple times: this just restarts the
  77     // timer if it is already running
  78     virtual bool Start(int milliseconds = -1, bool oneShot = false);
  79
  80     // stop the timer, does nothing if the timer is not running
  81     virtual void Stop();
  82
  83     // override this in your wxTimer-derived class if you want to process timer
  84     // messages in it, use non default ctor or SetOwner() otherwise
  85     virtual void Notify();
  86
  87
  88     // accessors
  89     // ---------
  90
  91     // get the object notified about the timer events
  92     wxEvtHandler *GetOwner() const;
  93
  94     // return true if the timer is running
  95     bool IsRunning() const;
  96
  97     // return the timer ID
  98     int GetId() const;
  99
 100     // get the (last) timer interval in milliseconds
 101     int GetInterval() const;
 102
 103     // return true if the timer is one shot
 104     bool IsOneShot() const;
 105
 106 protected:
 107     // common part of all ctors
 108     void Init();
 109
 110     wxTimerImpl *m_impl;
 111
 112     DECLARE_NO_COPY_CLASS(wxTimer)
 113 };
 114
 115 // ----------------------------------------------------------------------------
 116 // wxTimerRunner: starts the timer in its ctor, stops in the dtor
 117 // ----------------------------------------------------------------------------
 118
 119 class WXDLLEXPORT wxTimerRunner
 120 {
 121 public:
 122     wxTimerRunner(wxTimer& timer) : m_timer(timer) { }
 123     wxTimerRunner(wxTimer& timer, int milli, bool oneShot = false)
 124         : m_timer(timer)
 125     {
 126         m_timer.Start(milli, oneShot);
 127     }
 128
 129     void Start(int milli, bool oneShot = false)
 130     {
 131         m_timer.Start(milli, oneShot);
 132     }
 133
 134     ~wxTimerRunner()
 135     {
 136         if ( m_timer.IsRunning() )
 137         {
 138             m_timer.Stop();
 139         }
 140     }
 141
 142 private:
 143     wxTimer& m_timer;
 144
 145     DECLARE_NO_COPY_CLASS(wxTimerRunner)
 146 };
 147
 148 // ----------------------------------------------------------------------------
 149 // wxTimerEvent
 150 // ----------------------------------------------------------------------------
 151
 152 class WXDLLIMPEXP_BASE wxTimerEvent : public wxEvent
 153 {
 154 public:
 155     wxTimerEvent(wxTimer& timer)
 156         : wxEvent(timer.GetId(), wxEVT_TIMER),
 157           m_timer(timer)
 158     {
 159         SetEventObject(timer.GetOwner());
 160     }
 161
 162     // accessors
 163     int GetInterval() const { return m_timer.GetInterval(); }
 164     wxTimer& GetTimer() const { return m_timer; }
 165
 166     // implement the base class pure virtual
 167     virtual wxEvent *Clone() const { return new wxTimerEvent(*this); }
 168
 169 private:
 170     wxTimer& m_timer;
 171
 172     DECLARE_ABSTRACT_CLASS(wxTimerEvent)
 173     DECLARE_NO_ASSIGN_CLASS(wxTimerEvent)
 174 };
 175
 176 typedef void (wxEvtHandler::*wxTimerEventFunction)(wxTimerEvent&);
 177
 178 #define wxTimerEventHandler(func) \
 179     (wxObjectEventFunction)(wxEventFunction)wxStaticCastEvent(wxTimerEventFunction, &func)
 180
 181 #define EVT_TIMER(timerid, func) \
 182     wx__DECLARE_EVT1(wxEVT_TIMER, timerid, wxTimerEventHandler(func))
 183
 184 #endif // wxUSE_TIMER
 185
 186 #endif // _WX_TIMER_H_BASE_