]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/evtloop.h
undo the last change as it results in buildbot configuration error
[wxWidgets.git] / interface / wx / evtloop.h
... / ...
CommitLineData
1/////////////////////////////////////////////////////////////////////////////
2// Name: wx/evtloop.h
3// Purpose: wxEventLoop and related classes
4// Author: Vadim Zeitlin
5// Copyright: (C) 2008 Vadim Zeitlin
6// RCS-ID: $Id$
7// Licence: wxWindows license
8/////////////////////////////////////////////////////////////////////////////
9
10/**
11 @class wxEventLoopBase
12
13 Base class for all event loop implementations.
14
15 An event loop is a class which queries the queue of native events sent
16 to the wxWidgets application and dispatches them to the appropriate
17 wxEvtHandlers.
18
19 An object of this class is created by wxAppTraits::CreateEventLoop() and
20 used by wxApp to run the main application event loop.
21 Temporary event loops are usually created by wxDialog::ShowModal().
22
23 You can create your own event loop if you need, provided that you restore
24 the main event loop once yours is destroyed (see wxEventLoopActivator).
25
26 @library{wxbase}
27 @category{appmanagement}
28
29 @see wxApp, wxEventLoopActivator
30*/
31class wxEventLoopBase
32{
33public:
34 /**
35 Return the currently active (running) event loop.
36
37 May return @NULL if there is no active event loop (e.g. during
38 application startup or shutdown).
39 */
40 static wxEventLoopBase *GetActive();
41
42 /**
43 Set currently active (running) event loop.
44
45 Called by wxEventLoopActivator, use an instance of this class instead
46 of calling this method directly to ensure that the previously active
47 event loop is restored.
48
49 Results in a call to wxAppConsole::OnEventLoopEnter.
50 */
51 static void SetActive(wxEventLoopBase* loop);
52
53 /**
54 Returns @true if this is the main loop executed by wxApp::OnRun().
55 */
56 bool IsMain() const;
57
58
59 /**
60 @name Dispatch and processing
61 */
62 //@{
63
64 /**
65 Start the event loop, return the exit code when it is finished.
66
67 Logically, this method calls Dispatch() in a loop until it returns
68 @false and also takes care of generating idle events during each loop
69 iteration. However not all implementations of this class really
70 implement it like this (e.g. wxGTK does not) so you shouldn't rely on
71 Dispatch() being called from inside this function.
72
73 @return The argument passed to Exit() which terminated this event loop.
74 */
75 virtual int Run() = 0;
76
77 /**
78 Return true if this event loop is currently running.
79
80 Notice that even if this event loop hasn't terminated yet but has just
81 spawned a nested (e.g. modal) event loop, this method would return
82 @false.
83 */
84 bool IsRunning() const;
85
86 /**
87 Use this to check whether the event loop was successfully created
88 before using it
89 */
90 virtual bool IsOk() const;
91
92 /**
93 Exit from the loop with the given exit code.
94 */
95 virtual void Exit(int rc = 0) = 0;
96
97 /**
98 Return true if any events are available.
99
100 If this method returns @true, calling Dispatch() will not block.
101 */
102 virtual bool Pending() const = 0;
103
104 /**
105 Dispatches the next event in the windowing system event queue.
106 Blocks until an event appears if there are none currently
107 (use Pending() if this is not wanted).
108
109 This can be used for programming event loops, e.g.
110
111 @code
112 while (evtloop->Pending())
113 evtloop->Dispatch();
114 @endcode
115
116 @return @false if the event loop should stop and @true otherwise.
117
118 @see Pending(), wxEventLoopBase
119 */
120 virtual bool Dispatch() = 0;
121
122 /**
123 Dispatch an event but not wait longer than the specified timeout for
124 it.
125
126 If an event is received before the specified @a timeout expires, it is
127 processed and the function returns 1 normally or 0 if the event loop
128 should quite. Otherwise, i.e. if the timeout expires, the functions
129 returns -1 without processing any events.
130
131 @param timeout
132 The maximal time to wait for the events in milliseconds.
133
134 @return
135 1 if an event was processed, 0 if the event loop should quit or -1
136 if the timeout expired.
137 */
138 virtual int DispatchTimeout(unsigned long timeout) = 0;
139
140 /**
141 Called by wxWidgets to wake up the event loop even if it is currently
142 blocked inside Dispatch().
143 */
144 virtual void WakeUp() = 0;
145
146 //@}
147
148
149 /**
150 @name Idle handling
151 */
152 //@{
153
154 /**
155 Makes sure that idle events are sent again.
156 */
157 virtual void WakeUpIdle();
158
159 /**
160 This virtual function is called when the application becomes idle and
161 normally just sends wxIdleEvent to all interested parties.
162
163 It should return @true if more idle events are needed, @false if not.
164 */
165 virtual bool ProcessIdle();
166
167 //@}
168
169
170 /**
171 @name Yield-related hooks
172 */
173 //@{
174
175 /**
176 Returns @true if called from inside Yield() or from inside YieldFor().
177 */
178 virtual bool IsYielding() const;
179
180 /**
181 Yields control to pending messages in the windowing system.
182
183 This can be useful, for example, when a time-consuming process writes to a
184 text window. Without an occasional yield, the text window will not be updated
185 properly, and on systems with cooperative multitasking, such as Windows 3.1
186 other processes will not respond.
187
188 Caution should be exercised, however, since yielding may allow the
189 user to perform actions which are not compatible with the current task.
190 Disabling menu items or whole menus during processing can avoid unwanted
191 reentrance of code: see ::wxSafeYield for a better function.
192 You can avoid unwanted reentrancies also using IsYielding().
193
194 Note that Yield() will not flush the message logs. This is intentional as
195 calling Yield() is usually done to quickly update the screen and popping up
196 a message box dialog may be undesirable. If you do wish to flush the log
197 messages immediately (otherwise it will be done during the next idle loop
198 iteration), call wxLog::FlushActive.
199
200 Calling Yield() recursively is normally an error and an assert failure is
201 raised in debug build if such situation is detected. However if the
202 @a onlyIfNeeded parameter is @true, the method will just silently
203 return @false instead.
204 */
205 bool Yield(bool onlyIfNeeded = false);
206
207 /**
208 Works like Yield() with @e onlyIfNeeded == @true, except that it allows
209 the caller to specify a mask of the ::wxEventCategory values which
210 indicates which events should be processed and which should instead
211 be "delayed" (i.e. processed by the main loop later).
212
213 Note that this is a safer alternative to Yield() since it ensures that
214 only the events you're interested to will be processed; i.e. this method
215 helps to avoid unwanted reentrancies.
216
217 Note that currently only wxMSW and wxGTK do support selective yield of
218 native events coming from the underlying GUI toolkit.
219 wxWidgets events posted using wxEvtHandler::AddPendingEvent or
220 wxEvtHandler::QueueEvent are instead selectively processed by all ports.
221
222 @see wxEvent::GetEventCategory
223 */
224 bool YieldFor(long eventsToProcess);
225
226 /**
227 Returns @true if the given event category is allowed inside
228 a YieldFor() call (i.e. compares the given category against the
229 last mask passed to YieldFor()).
230
231 @see wxEvent::GetEventCategory
232 */
233 virtual bool IsEventAllowedInsideYield(wxEventCategory cat) const;
234
235 //@}
236
237
238protected:
239 /**
240 This function is called before the event loop terminates, whether this
241 happens normally (because of Exit() call) or abnormally (because of an
242 exception thrown from inside the loop).
243
244 The default implementation calls wxAppConsole::OnEventLoopExit.
245 */
246 virtual void OnExit();
247};
248
249/**
250 @class wxEventLoopActivator
251
252 Makes an event loop temporarily active.
253
254 This class is used to make the event loop active during its life-time,
255 e.g.:
256 @code
257 class MyEventLoop : public wxEventLoopBase { ... };
258
259 void RunMyLoop()
260 {
261 MyEventLoop loop;
262 wxEventLoopActivator activate(&loop);
263
264 ...
265 } // the previously active event loop restored here
266 @endcode
267
268 @library{wxbase}
269 @category{appmanagement}
270
271 @see wxEventLoopBase
272*/
273class wxEventLoopActivator
274{
275public:
276 /**
277 Makes the loop passed as the parameter currently active.
278
279 This saves the current return value of wxEventLoopBase::GetActive() and
280 then calls wxEventLoopBase::SetActive() with the given @a loop.
281 */
282 wxEventLoopActivator(wxEventLoopBase *loop);
283
284 /**
285 Restores the previously active event loop stored by the constructor.
286 */
287 ~wxEventLoopActivator();
288};