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     (see wxTimer::SetOwner).
 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     @see wxTimer
 170 */
 171 class wxTimerEvent : public wxEvent
 172 {
 173 public:
 174     /**
 175         Returns the interval of the timer which generated this event.
 176     */
 177     int GetInterval() const;
 178
 179     /**
 180         Returns the timer object which generated this event.
 181     */
 182     wxTimer& GetTimer() const;
 183 };
 184