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(wxTimer& timer); 212 213 /** 214 Returns the interval of the timer which generated this event. 215 */ 216 int GetInterval() const; 217 218 /** 219 Returns the timer object which generated this event. 220 */ 221 wxTimer& GetTimer() const; 222 }; 223 224