interface/wx/timer.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        timer.h
   3 // Purpose:     interface of wxTimer
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 // generate notifications periodically until the timer is stopped (default)
   9 #define wxTIMER_CONTINUOUS false
  10
  11 // only send the notification once and then stop the timer
  12 #define wxTIMER_ONE_SHOT true
  13
  14 wxEventType wxEVT_TIMER;
  15
  16
  17 /**
  18     @class wxTimer
  19
  20     The wxTimer class allows you to execute code at specified intervals.
  21     Its precision is platform-dependent, but in general will not be better than
  22     @c 1ms nor worse than @c 1s.
  23
  24     There are three different ways to use this class:
  25
  26     - You may derive a new class from wxTimer and override the
  27       wxTimer::Notify member to perform the required action.
  28     - You may redirect the notifications to any wxEvtHandler derived object by
  29       using the non-default constructor or wxTimer::SetOwner.
  30       Then use the @c EVT_TIMER macro to connect it to the event handler which
  31       will receive wxTimerEvent notifications.
  32     - You may use a derived class and the @c EVT_TIMER macro to connect it to
  33       an event handler defined in the derived class. If the default constructor
  34       is used, the timer object will be its own owner object, since it is
  35       derived from wxEvtHandler.
  36
  37     In any case, you must start the timer with wxTimer::Start() after constructing
  38     it before it actually starts sending notifications.
  39     It can be stopped later with wxTimer::Stop().
  40
  41     @note A timer can only be used from the main thread.
  42
  43     @library{wxbase}
  44     @category{misc}
  45
  46     @see wxStopWatch
  47 */
  48 class wxTimer : public wxEvtHandler
  49 {
  50 public:
  51     /**
  52         Default constructor.
  53         If you use it to construct the object and don't call SetOwner() later,
  54         you must override Notify() method to process the notifications.
  55     */
  56     wxTimer();
  57
  58     /**
  59         Creates a timer and associates it with @a owner.
  60         Please see SetOwner() for the description of parameters.
  61     */
  62     wxTimer(wxEvtHandler* owner, int id = -1);
  63
  64     /**
  65         Destructor. Stops the timer if it is running.
  66     */
  67     virtual ~wxTimer();
  68
  69     /**
  70         Returns the ID of the events generated by this timer.
  71     */
  72     int GetId() const;
  73
  74     /**
  75         Returns the current interval for the timer (in milliseconds).
  76     */
  77     int GetInterval() const;
  78
  79     /**
  80         Returns the current @e owner of the timer.
  81
  82         If non-@NULL this is the event handler which will receive the
  83         timer events (see wxTimerEvent) when the timer is running.
  84     */
  85     wxEvtHandler* GetOwner() const;
  86
  87     /**
  88         Returns @true if the timer is one shot, i.e.\ if it will stop after firing
  89         the first notification automatically.
  90     */
  91     bool IsOneShot() const;
  92
  93     /**
  94         Returns @true if the timer is running, @false if it is stopped.
  95     */
  96     bool IsRunning() const;
  97
  98     /**
  99         This member should be overridden by the user if the default constructor was
 100         used and SetOwner() wasn't called.
 101
 102         Perform whatever action which is to be taken periodically here.
 103
 104         Notice that throwing exceptions from this method is currently not
 105         supported, use event-based timer handling approach if an exception can
 106         be thrown while handling timer notifications.
 107     */
 108     virtual void Notify();
 109
 110     /**
 111         Associates the timer with the given @a owner object.
 112
 113         When the timer is running, the owner will receive timer events (see wxTimerEvent)
 114         with @a id equal to @a id specified here.
 115     */
 116     void SetOwner(wxEvtHandler* owner, int id = -1);
 117
 118     /**
 119         (Re)starts the timer. If @a milliseconds parameter is -1 (value by default),
 120         the previous value is used. Returns @false if the timer could not be started,
 121         @true otherwise (in MS Windows timers are a limited resource).
 122
 123         If @a oneShot is @false (the default), the Notify() function will be called
 124         repeatedly until the timer is stopped.
 125         If @true, it will be called only once and the timer will stop automatically.
 126
 127         To make your code more readable you may also use the following symbolic constants:
 128         - wxTIMER_CONTINUOUS: Start a normal, continuously running, timer
 129         - wxTIMER_ONE_SHOT: Start a one shot timer
 130         Alternatively, use StartOnce().
 131
 132         If the timer was already running, it will be stopped by this method before
 133         restarting it.
 134     */
 135     virtual bool Start(int milliseconds = -1, bool oneShot = wxTIMER_CONTINUOUS);
 136
 137     /**
 138         Starts the timer for a once-only notification.
 139
 140         This is a simple wrapper for Start() with @c wxTIMER_ONE_SHOT parameter.
 141
 142         @since 2.9.5
 143      */
 144     bool StartOnce(int milliseconds = -1);
 145
 146     /**
 147         Stops the timer.
 148     */
 149     virtual void Stop();
 150 };
 151
 152
 153 /**
 154    @class wxTimerRunner
 155
 156    Starts the timer in its ctor, stops in the dtor.
 157 */
 158 class wxTimerRunner
 159 {
 160 public:
 161     wxTimerRunner(wxTimer& timer);
 162     wxTimerRunner(wxTimer& timer, int milli, bool oneShot = false);
 163     void Start(int milli, bool oneShot = false);
 164     ~wxTimerRunner();
 165 };
 166
 167 /**
 168     @class wxTimerEvent
 169
 170     wxTimerEvent object is passed to the event handler of timer events
 171     (see wxTimer::SetOwner).
 172
 173     For example:
 174
 175     @code
 176     class MyFrame : public wxFrame
 177     {
 178     public:
 179         ...
 180         void OnTimer(wxTimerEvent& event);
 181
 182     private:
 183         wxTimer m_timer;
 184         wxDECLARE_EVENT_TABLE();
 185     };
 186
 187     wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
 188         EVT_TIMER(TIMER_ID, MyFrame::OnTimer)
 189     wxEND_EVENT_TABLE()
 190
 191     MyFrame::MyFrame()
 192            : m_timer(this, TIMER_ID)
 193     {
 194         m_timer.Start(1000);    // 1 second interval
 195     }
 196
 197     void MyFrame::OnTimer(wxTimerEvent& event)
 198     {
 199         // do whatever you want to do every second here
 200     }
 201     @endcode
 202
 203     @library{wxbase}
 204     @category{events}
 205
 206     @see wxTimer
 207 */
 208 class wxTimerEvent : public wxEvent
 209 {
 210 public:
 211     wxTimerEvent();
 212     wxTimerEvent(wxTimer& timer);
 213
 214     /**
 215         Returns the interval of the timer which generated this event.
 216     */
 217     int GetInterval() const;
 218
 219     /**
 220         Returns the timer object which generated this event.
 221     */
 222     wxTimer& GetTimer() const;
 223 };
 224