interface/timer.h

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