]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/timer.tex
fixed bug #890430, parameter documented twice
[wxWidgets.git] / 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 two 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 NB:} note that timer can only be used from the main thread currently.
28
29 \wxheading{Derived from}
30
31 \helpref{wxEvtHandler}{wxevthandler}
32
33 \wxheading{Include files}
34
35 <wx/timer.h>
36
37 \wxheading{See also}
38
39 \helpref{::wxStartTimer}{wxstarttimer}, \helpref{::wxGetElapsedTime}{wxgetelapsedtime}, \helpref{wxStopWatch}{wxstopwatch}
40
41 \latexignore{\rtfignore{\wxheading{Members}}}
42
43 \membersection{wxTimer::wxTimer}\label{wxtimerwxtimer}
44
45 \func{}{wxTimer}{\void}
46
47 Default constructor. If you use it to construct the object and don't call
48 \helpref{SetOwner}{wxtimersetowner} later, you must override
49 \helpref{Notify}{wxtimernotify} method to process the notifications.
50
51 \func{}{wxTimer}{\param{wxEvtHandler *}{owner}, \param{int }{id = -1}}
52
53 Creates a timer and associates it with {\it owner}. Please see
54 \helpref{SetOwner}{wxtimersetowner} for the description of parameters.
55
56 \membersection{wxTimer::\destruct{wxTimer}}
57
58 \func{}{\destruct{wxTimer}}{\void}
59
60 Destructor. Stops the timer if it is running.
61
62 \membersection{wxTimer::GetInterval}\label{wxtimergetinterval}
63
64 \constfunc{int}{GetInterval}{\void}
65
66 Returns the current interval for the timer (in milliseconds).
67
68 \membersection{wxTimer::IsOneShot}\label{wxtimerisoneshot}
69
70 \constfunc{bool}{IsOneShot}{\void}
71
72 Returns {\tt true} if the timer is one shot, i.e.\ if it will stop after firing the
73 first notification automatically.
74
75 \membersection{wxTimer::IsRunning}\label{wxtimerisrunning}
76
77 \constfunc{bool}{IsRunning}{\void}
78
79 Returns {\tt true} if the timer is running, {\tt false} if it is stopped.
80
81 \membersection{wxTimer::Notify}\label{wxtimernotify}
82
83 \func{void}{Notify}{\void}
84
85 This member should be overridden by the user if the default constructor was
86 used and \helpref{SetOwner}{wxtimersetowner} wasn't called.
87
88 Perform whatever action which is to be taken periodically here.
89
90 \membersection{wxTimer::SetOwner}\label{wxtimersetowner}
91
92 \func{void}{SetOwner}{\param{wxEvtHandler *}{owner}, \param{int }{id = -1}}
93
94 Associates the timer with the given {\it owner}\/ object. When the timer is
95 running, the owner will receive \helpref{timer events}{wxtimerevent} with
96 id equal to {\it id}\/ specified here.
97
98 \membersection{wxTimer::Start}\label{wxtimerstart}
99
100 \func{bool}{Start}{\param{int}{milliseconds = -1}, \param{bool }{oneShot = {\tt false}}}
101
102 (Re)starts the timer. If {\it milliseconds}\/ parameter is -1 (value by default),
103 the previous value is used. Returns {\tt false} if the timer could not be started,
104 {\tt true} otherwise (in MS Windows timers are a limited resource).
105
106 If {\it oneShot}\/ is {\tt false} (the default), the \helpref{Notify}{wxtimernotify}
107 function will be called repeatedly until the timer is stopped. If {\tt true},
108 it will be called only once and the timer will stop automatically. To make your
109 code more readable you may also use the following symbolic constants
110 \twocolwidtha{5cm}%
111 \begin{twocollist}\itemsep=0pt
112 \twocolitem{wxTIMER\_CONTINUOUS}{Start a normal, continuously running, timer}
113 \twocolitem{wxTIMER\_ONE\_SHOT}{Start a one shot timer}
114 \end{twocollist}
115
116
117 If the timer was already running, it will be stopped by this method before
118 restarting it.
119
120 \membersection{wxTimer::Stop}\label{wxtimerstop}
121
122 \func{void}{Stop}{\void}
123
124 Stops the timer.
125
126 \section{\class{wxTimerEvent}}\label{wxtimerevent}
127
128 wxTimerEvent object is passed to the event handler of timer events.
129
130 For example:
131
132 \begin{verbatim}
133 class MyFrame : public wxFrame
134 {
135 public:
136 ...
137 void OnTimer(wxTimerEvent& event);
138
139 private:
140 wxTimer m_timer;
141 };
142
143 BEGIN_EVENT_TABLE(MyFrame, wxFrame)
144 EVT_TIMER(TIMER_ID, MyFrame::OnTimer)
145 END_EVENT_TABLE()
146
147 MyFrame::MyFrame()
148 : m_timer(this, TIMER_ID)
149 {
150 m_timer.Start(1000); // 1 second interval
151 }
152
153 void MyFrame::OnTimer(wxTimerEvent& event)
154 {
155 // do whatever you want to do every second here
156 }
157
158 \end{verbatim}
159
160 \wxheading{Include files}
161
162 <wx/timer.h>
163
164 \wxheading{See also}
165
166 \helpref{wxTimer}{wxtimer}
167
168 \latexignore{\rtfignore{\wxheading{Members}}}
169
170 \membersection{wxTimerEvent::GetInterval}\label{wxtimereventgetinterval}
171
172 \constfunc{int}{GetInterval}{\void}
173
174 Returns the interval of the timer which generated this event.
175