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