interface/wx/timer.h

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