update for bakefile 0.2.6
[wxWidgets.git] / interface / wx / timer.h
0 / 184 (  0%)
CommitLineData
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*/
40class wxTimer : public wxEvtHandler
41{
42public:
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*/
171class wxTimerEvent : public wxEvent
172{
173public:
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