docs/latex/wx/timer.tex

   1 \section{\class{wxTimer}}\label{wxtimer}
   2
   3 The wxTimer class allows you to execute code at specified intervals. Its
   4 precision is platform-dependent, but in general will not be better than 1ms nor
   5 worse than 1s.
   6
   7 There are three different ways to use this class:
   8
   9 \begin{enumerate}
  10 \item You may derive a new class from wxTimer and override the
  11 \helpref{Notify}{wxtimernotify} member to perform the required action.
  12 \item Or you may redirect the notifications to any
  13 \helpref{wxEvtHandler}{wxevthandler} derived object by using the non-default
  14 constructor or \helpref{SetOwner}{wxtimersetowner}. Then use the {\tt EVT\_TIMER}
  15 macro to connect it to the event handler which will receive
  16 \helpref{wxTimerEvent}{wxtimerevent} notifications.
  17 \item Or you may use a derived class and the {\tt EVT\_TIMER}
  18 macro to connect it to an event handler defined in the derived class.
  19 If the default constructor is used, the timer object will be its
  20 own owner object, since it is derived from wxEvtHandler.
  21 \end{enumerate}
  22
  23 In any case, you must start the timer with \helpref{Start}{wxtimerstart}
  24 after constructing it before it actually starts sending notifications. It can
  25 be stopped later with \helpref{Stop}{wxtimerstop}.
  26
  27 {\bf Note:} A timer can only be used from the main thread.
  28
  29 \wxheading{Derived from}
  30
  31 \helpref{wxEvtHandler}{wxevthandler}
  32 \helpref{wxObject}{wxobject}
  33
  34 \wxheading{Include files}
  35
  36 <wx/timer.h>
  37
  38 \wxheading{See also}
  39
  40 \helpref{wxStopWatch}{wxstopwatch}
  41
  42 \latexignore{\rtfignore{\wxheading{Members}}}
  43
  44 \membersection{wxTimer::wxTimer}\label{wxtimerwxtimer}
  45
  46 \func{}{wxTimer}{\void}
  47
  48 Default constructor. If you use it to construct the object and don't call
  49 \helpref{SetOwner}{wxtimersetowner} later, you must override
  50 \helpref{Notify}{wxtimernotify} method to process the notifications.
  51
  52 \func{}{wxTimer}{\param{wxEvtHandler *}{owner}, \param{int }{id = -1}}
  53
  54 Creates a timer and associates it with {\it owner}. Please see
  55 \helpref{SetOwner}{wxtimersetowner} for the description of parameters.
  56
  57 \membersection{wxTimer::\destruct{wxTimer}}\label{wxtimerdtor}
  58
  59 \func{}{\destruct{wxTimer}}{\void}
  60
  61 Destructor. Stops the timer if it is running.
  62
  63 \membersection{wxTimer::GetInterval}\label{wxtimergetinterval}
  64
  65 \constfunc{int}{GetInterval}{\void}
  66
  67 Returns the current interval for the timer (in milliseconds).
  68
  69 \membersection{wxTimer::GetOwner}\label{wxtimergetowner}
  70
  71 \constfunc{wxEvtHandler}{GetOwner}{\void}
  72
  73 Returns the current {\it owner} of the timer.
  74 If non-\NULL this is the event handler which will receive the
  75 \helpref{timer events}{wxtimerevent} when the timer is running.
  76
  77 \membersection{wxTimer::GetId}\label{wxtimergetid}
  78
  79 \constfunc{int}{GetId}{\void}
  80
  81 Returns the ID of the events generated by this timer.
  82
  83 \membersection{wxTimer::IsOneShot}\label{wxtimerisoneshot}
  84
  85 \constfunc{bool}{IsOneShot}{\void}
  86
  87 Returns {\tt true} if the timer is one shot, i.e.\ if it will stop after firing the
  88 first notification automatically.
  89
  90 \membersection{wxTimer::IsRunning}\label{wxtimerisrunning}
  91
  92 \constfunc{bool}{IsRunning}{\void}
  93
  94 Returns {\tt true} if the timer is running, {\tt false} if it is stopped.
  95
  96 \membersection{wxTimer::Notify}\label{wxtimernotify}
  97
  98 \func{void}{Notify}{\void}
  99
 100 This member should be overridden by the user if the default constructor was
 101 used and \helpref{SetOwner}{wxtimersetowner} wasn't called.
 102
 103 Perform whatever action which is to be taken periodically here.
 104
 105 \membersection{wxTimer::SetOwner}\label{wxtimersetowner}
 106
 107 \func{void}{SetOwner}{\param{wxEvtHandler *}{owner}, \param{int }{id = -1}}
 108
 109 Associates the timer with the given {\it owner}\/ object. When the timer is
 110 running, the owner will receive \helpref{timer events}{wxtimerevent} with
 111 id equal to {\it id}\/ specified here.
 112
 113 \membersection{wxTimer::Start}\label{wxtimerstart}
 114
 115 \func{bool}{Start}{\param{int }{milliseconds = -1}, \param{bool }{oneShot = {\tt false}}}
 116
 117 (Re)starts the timer. If {\it milliseconds}\/ parameter is -1 (value by default),
 118 the previous value is used. Returns {\tt false} if the timer could not be started,
 119 {\tt true} otherwise (in MS Windows timers are a limited resource).
 120
 121 If {\it oneShot}\/ is {\tt false} (the default), the \helpref{Notify}{wxtimernotify}
 122 function will be called repeatedly until the timer is stopped. If {\tt true},
 123 it will be called only once and the timer will stop automatically. To make your
 124 code more readable you may also use the following symbolic constants:
 125
 126 \twocolwidtha{5cm}
 127 \begin{twocollist}\itemsep=0pt
 128 \twocolitem{wxTIMER\_CONTINUOUS}{Start a normal, continuously running, timer}
 129 \twocolitem{wxTIMER\_ONE\_SHOT}{Start a one shot timer}
 130 \end{twocollist}
 131
 132 If the timer was already running, it will be stopped by this method before
 133 restarting it.
 134
 135 \membersection{wxTimer::Stop}\label{wxtimerstop}
 136
 137 \func{void}{Stop}{\void}
 138
 139 Stops the timer.
 140
 141
 142
 143
 144
 145 %% wxTimerEvent
 146
 147
 148 \section{\class{wxTimerEvent}}\label{wxtimerevent}
 149
 150 wxTimerEvent object is passed to the event handler of timer events.
 151
 152 For example:
 153
 154 \begin{verbatim}
 155 class MyFrame : public wxFrame
 156 {
 157 public:
 158     ...
 159     void OnTimer(wxTimerEvent& event);
 160
 161 private:
 162     wxTimer m_timer;
 163 };
 164
 165 BEGIN_EVENT_TABLE(MyFrame, wxFrame)
 166     EVT_TIMER(TIMER_ID, MyFrame::OnTimer)
 167 END_EVENT_TABLE()
 168
 169 MyFrame::MyFrame()
 170        : m_timer(this, TIMER_ID)
 171 {
 172     m_timer.Start(1000);    // 1 second interval
 173 }
 174
 175 void MyFrame::OnTimer(wxTimerEvent& event)
 176 {
 177     // do whatever you want to do every second here
 178 }
 179
 180 \end{verbatim}
 181
 182 \wxheading{Derived from}
 183
 184 \helpref{wxEvent}{wxevent}
 185
 186 \wxheading{Include files}
 187
 188 <wx/timer.h>
 189
 190 \wxheading{See also}
 191
 192 \helpref{wxTimer}{wxtimer}
 193
 194 \latexignore{\rtfignore{\wxheading{Members}}}
 195
 196 \membersection{wxTimerEvent::GetInterval}\label{wxtimereventgetinterval}
 197
 198 \constfunc{int}{GetInterval}{\void}
 199
 200 Returns the interval of the timer which generated this event.
 201
 202
 203 \membersection{wxTimerEvent::GetTimer}\label{wxtimereventgettimer}
 204
 205 \constfunc{wxTimer\&}{GetTimer}{\void}
 206
 207 Returns the timer object which generated this event.
 208