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         Notice that throwing exceptions from this method is currently not
  97         supported, use event-based timer handling approach if an exception can
  98         be thrown while handling timer notifications.
  99     */
 100     virtual void Notify();
 101
 102     /**
 103         Associates the timer with the given @a owner object.
 104
 105         When the timer is running, the owner will receive timer events (see wxTimerEvent)
 106         with @a id equal to @a id specified here.
 107     */
 108     void SetOwner(wxEvtHandler* owner, int id = -1);
 109
 110     /**
 111         (Re)starts the timer. If @a milliseconds parameter is -1 (value by default),
 112         the previous value is used. Returns @false if the timer could not be started,
 113         @true otherwise (in MS Windows timers are a limited resource).
 114
 115         If @a oneShot is @false (the default), the Notify() function will be called
 116         repeatedly until the timer is stopped.
 117         If @true, it will be called only once and the timer will stop automatically.
 118
 119         To make your code more readable you may also use the following symbolic constants:
 120         - wxTIMER_CONTINUOUS: Start a normal, continuously running, timer
 121         - wxTIMER_ONE_SHOT: Start a one shot timer
 122         If the timer was already running, it will be stopped by this method before
 123         restarting it.
 124     */
 125     virtual bool Start(int milliseconds = -1, bool oneShot = false);
 126
 127     /**
 128         Stops the timer.
 129     */
 130     virtual void Stop();
 131 };
 132
 133
 134
 135 /**
 136     @class wxTimerEvent
 137
 138     wxTimerEvent object is passed to the event handler of timer events
 139     (see wxTimer::SetOwner).
 140
 141     For example:
 142
 143     @code
 144     class MyFrame : public wxFrame
 145     {
 146     public:
 147         ...
 148         void OnTimer(wxTimerEvent& event);
 149
 150     private:
 151         wxTimer m_timer;
 152     };
 153
 154     BEGIN_EVENT_TABLE(MyFrame, wxFrame)
 155         EVT_TIMER(TIMER_ID, MyFrame::OnTimer)
 156     END_EVENT_TABLE()
 157
 158     MyFrame::MyFrame()
 159            : m_timer(this, TIMER_ID)
 160     {
 161         m_timer.Start(1000);    // 1 second interval
 162     }
 163
 164     void MyFrame::OnTimer(wxTimerEvent& event)
 165     {
 166         // do whatever you want to do every second here
 167     }
 168     @endcode
 169
 170     @library{wxbase}
 171     @category{events}
 172
 173     @see wxTimer
 174 */
 175 class wxTimerEvent : public wxEvent
 176 {
 177 public:
 178     /**
 179         Returns the interval of the timer which generated this event.
 180     */
 181     int GetInterval() const;
 182
 183     /**
 184         Returns the timer object which generated this event.
 185     */
 186     wxTimer& GetTimer() const;
 187 };
 188