]>
Commit | Line | Data |
---|---|---|
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 | */ | |
31 | class wxEventLoopBase | |
32 | { | |
33 | public: | |
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 | ||
238 | protected: | |
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 | */ | |
273 | class wxEventLoopActivator | |
274 | { | |
275 | public: | |
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 | }; |