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