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{Library}
  39
  40 \helpref{wxBase}{librarieslist}
  41
  42 \wxheading{See also}
  43
  44 \helpref{wxStopWatch}{wxstopwatch}
  45
  46 \latexignore{\rtfignore{\wxheading{Members}}}
  47
  48 \membersection{wxTimer::wxTimer}\label{wxtimerwxtimer}
  49
  50 \func{}{wxTimer}{\void}
  51
  52 Default constructor. If you use it to construct the object and don't call
  53 \helpref{SetOwner}{wxtimersetowner} later, you must override
  54 \helpref{Notify}{wxtimernotify} method to process the notifications.
  55
  56 \func{}{wxTimer}{\param{wxEvtHandler *}{owner}, \param{int }{id = -1}}
  57
  58 Creates a timer and associates it with {\it owner}. Please see
  59 \helpref{SetOwner}{wxtimersetowner} for the description of parameters.
  60
  61 \membersection{wxTimer::\destruct{wxTimer}}\label{wxtimerdtor}
  62
  63 \func{}{\destruct{wxTimer}}{\void}
  64
  65 Destructor. Stops the timer if it is running.
  66
  67 \membersection{wxTimer::GetInterval}\label{wxtimergetinterval}
  68
  69 \constfunc{int}{GetInterval}{\void}
  70
  71 Returns the current interval for the timer (in milliseconds).
  72
  73 \membersection{wxTimer::GetOwner}\label{wxtimergetowner}
  74
  75 \constfunc{wxEvtHandler}{GetOwner}{\void}
  76
  77 Returns the current {\it owner} of the timer.
  78 If non-\NULL this is the event handler which will receive the
  79 \helpref{timer events}{wxtimerevent} when the timer is running.
  80
  81 \membersection{wxTimer::GetId}\label{wxtimergetid}
  82
  83 \constfunc{int}{GetId}{\void}
  84
  85 Returns the ID of the events generated by this timer.
  86
  87 \membersection{wxTimer::IsOneShot}\label{wxtimerisoneshot}
  88
  89 \constfunc{bool}{IsOneShot}{\void}
  90
  91 Returns {\tt true} if the timer is one shot, i.e.\ if it will stop after firing the
  92 first notification automatically.
  93
  94 \membersection{wxTimer::IsRunning}\label{wxtimerisrunning}
  95
  96 \constfunc{bool}{IsRunning}{\void}
  97
  98 Returns {\tt true} if the timer is running, {\tt false} if it is stopped.
  99
 100 \membersection{wxTimer::Notify}\label{wxtimernotify}
 101
 102 \func{void}{Notify}{\void}
 103
 104 This member should be overridden by the user if the default constructor was
 105 used and \helpref{SetOwner}{wxtimersetowner} wasn't called.
 106
 107 Perform whatever action which is to be taken periodically here.
 108
 109 \membersection{wxTimer::SetOwner}\label{wxtimersetowner}
 110
 111 \func{void}{SetOwner}{\param{wxEvtHandler *}{owner}, \param{int }{id = -1}}
 112
 113 Associates the timer with the given {\it owner}\/ object. When the timer is
 114 running, the owner will receive \helpref{timer events}{wxtimerevent} with
 115 id equal to {\it id}\/ specified here.
 116
 117 \membersection{wxTimer::Start}\label{wxtimerstart}
 118
 119 \func{bool}{Start}{\param{int }{milliseconds = -1}, \param{bool }{oneShot = {\tt false}}}
 120
 121 (Re)starts the timer. If {\it milliseconds}\/ parameter is -1 (value by default),
 122 the previous value is used. Returns {\tt false} if the timer could not be started,
 123 {\tt true} otherwise (in MS Windows timers are a limited resource).
 124
 125 If {\it oneShot}\/ is {\tt false} (the default), the \helpref{Notify}{wxtimernotify}
 126 function will be called repeatedly until the timer is stopped. If {\tt true},
 127 it will be called only once and the timer will stop automatically. To make your
 128 code more readable you may also use the following symbolic constants:
 129
 130 \twocolwidtha{5cm}
 131 \begin{twocollist}\itemsep=0pt
 132 \twocolitem{wxTIMER\_CONTINUOUS}{Start a normal, continuously running, timer}
 133 \twocolitem{wxTIMER\_ONE\_SHOT}{Start a one shot timer}
 134 \end{twocollist}
 135
 136 If the timer was already running, it will be stopped by this method before
 137 restarting it.
 138
 139 \membersection{wxTimer::Stop}\label{wxtimerstop}
 140
 141 \func{void}{Stop}{\void}
 142
 143 Stops the timer.
 144
 145
 146
 147
 148
 149 %% wxTimerEvent
 150
 151
 152 \section{\class{wxTimerEvent}}\label{wxtimerevent}
 153
 154 wxTimerEvent object is passed to the event handler of timer events.
 155
 156 For example:
 157
 158 \begin{verbatim}
 159 class MyFrame : public wxFrame
 160 {
 161 public:
 162     ...
 163     void OnTimer(wxTimerEvent& event);
 164
 165 private:
 166     wxTimer m_timer;
 167 };
 168
 169 BEGIN_EVENT_TABLE(MyFrame, wxFrame)
 170     EVT_TIMER(TIMER_ID, MyFrame::OnTimer)
 171 END_EVENT_TABLE()
 172
 173 MyFrame::MyFrame()
 174        : m_timer(this, TIMER_ID)
 175 {
 176     m_timer.Start(1000);    // 1 second interval
 177 }
 178
 179 void MyFrame::OnTimer(wxTimerEvent& event)
 180 {
 181     // do whatever you want to do every second here
 182 }
 183
 184 \end{verbatim}
 185
 186 \wxheading{Derived from}
 187
 188 \helpref{wxEvent}{wxevent}
 189
 190 \wxheading{Include files}
 191
 192 <wx/timer.h>
 193
 194 \wxheading{Library}
 195
 196 \helpref{wxBase}{librarieslist}
 197
 198 \wxheading{See also}
 199
 200 \helpref{wxTimer}{wxtimer}
 201
 202 \latexignore{\rtfignore{\wxheading{Members}}}
 203
 204 \membersection{wxTimerEvent::GetInterval}\label{wxtimereventgetinterval}
 205
 206 \constfunc{int}{GetInterval}{\void}
 207
 208 Returns the interval of the timer which generated this event.
 209
 210
 211 \membersection{wxTimerEvent::GetTimer}\label{wxtimereventgettimer}
 212
 213 \constfunc{wxTimer\&}{GetTimer}{\void}
 214
 215 Returns the timer object which generated this event.
 216