1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxEventLoop and related classes
4 // Author: Vadim Zeitlin
5 // Copyright: (C) 2008 Vadim Zeitlin
7 // Licence: wxWindows licence
8 /////////////////////////////////////////////////////////////////////////////
11 @class wxEventLoopBase
13 Base class for all event loop implementations.
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
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().
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).
27 @category{appmanagement}
29 @see wxApp, wxEventLoopActivator
35 Return the currently active (running) event loop.
37 May return @NULL if there is no active event loop (e.g. during
38 application startup or shutdown).
40 static wxEventLoopBase
*GetActive();
43 Set currently active (running) event loop.
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.
49 Results in a call to wxAppConsole::OnEventLoopEnter.
51 static void SetActive(wxEventLoopBase
* loop
);
54 Returns @true if this is the main loop executed by wxApp::OnRun().
60 @name Dispatch and processing
65 Start the event loop, return the exit code when it is finished.
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.
73 @return The argument passed to Exit() which terminated this event loop.
75 virtual int Run() = 0;
78 Return true if this event loop is currently running.
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
84 bool IsRunning() const;
87 Use this to check whether the event loop was successfully created
90 virtual bool IsOk() const;
93 Exit from the loop with the given exit code.
95 virtual void Exit(int rc
= 0) = 0;
98 Return true if any events are available.
100 If this method returns @true, calling Dispatch() will not block.
102 virtual bool Pending() const = 0;
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).
109 This can be used for programming event loops, e.g.
112 while (evtloop->Pending())
116 @return @false if the event loop should stop and @true otherwise.
118 @see Pending(), wxEventLoopBase
120 virtual bool Dispatch() = 0;
123 Dispatch an event but not wait longer than the specified timeout for
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.
132 The maximal time to wait for the events in milliseconds.
135 1 if an event was processed, 0 if the event loop should quit or -1
136 if the timeout expired.
138 virtual int DispatchTimeout(unsigned long timeout
) = 0;
141 Called by wxWidgets to wake up the event loop even if it is currently
142 blocked inside Dispatch().
144 virtual void WakeUp() = 0;
155 Makes sure that idle events are sent again.
157 virtual void WakeUpIdle();
160 This virtual function is called when the application becomes idle and
161 normally just sends wxIdleEvent to all interested parties.
163 It should return @true if more idle events are needed, @false if not.
165 virtual bool ProcessIdle();
171 @name Yield-related hooks
176 Returns @true if called from inside Yield() or from inside YieldFor().
178 virtual bool IsYielding() const;
181 Yields control to pending messages in the windowing system.
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.
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().
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.
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.
205 bool Yield(bool onlyIfNeeded
= false);
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).
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.
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.
222 @see wxEvent::GetEventCategory
224 bool YieldFor(long eventsToProcess
);
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()).
231 @see wxEvent::GetEventCategory
233 virtual bool IsEventAllowedInsideYield(wxEventCategory cat
) const;
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).
244 The default implementation calls wxAppConsole::OnEventLoopExit.
246 virtual void OnExit();
250 @class wxEventLoopActivator
252 Makes an event loop temporarily active.
254 This class is used to make the event loop active during its life-time,
257 class MyEventLoop : public wxEventLoopBase { ... };
262 wxEventLoopActivator activate(&loop);
265 } // the previously active event loop restored here
269 @category{appmanagement}
273 class wxEventLoopActivator
277 Makes the loop passed as the parameter currently active.
279 This saves the current return value of wxEventLoopBase::GetActive() and
280 then calls wxEventLoopBase::SetActive() with the given @a loop.
282 wxEventLoopActivator(wxEventLoopBase
*loop
);
285 Restores the previously active event loop stored by the constructor.
287 ~wxEventLoopActivator();
291 @class wxGUIEventLoop
293 A generic implementation of the GUI event loop.
296 @category{appmanagement}
298 class wxGUIEventLoop
: public wxEventLoopBase
302 virtual ~wxGUIEventLoop();