// Purpose: wxEventLoop and related classes
// Author: Vadim Zeitlin
// Copyright: (C) 2008 Vadim Zeitlin
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
Base class for all event loop implementations.
+ An event loop is a class which queries the queue of native events sent
+ to the wxWidgets application and dispatches them to the appropriate
+ wxEvtHandlers.
+
An object of this class is created by wxAppTraits::CreateEventLoop() and
used by wxApp to run the main application event loop.
+ Temporary event loops are usually created by wxDialog::ShowModal().
+
+ You can create your own event loop if you need, provided that you restore
+ the main event loop once yours is destroyed (see wxEventLoopActivator).
+
+ Notice that there can be more than one event loop at any given moment, e.g.
+ an event handler called from the main loop can show a modal dialog, which
+ starts its own loop resulting in two nested loops, with the modal dialog
+ being the active one (its IsRunning() returns @true). And a handler for a
+ button inside the modal dialog can, of course, create another modal dialog
+ with its own event loop and so on. So in general event loops form a stack
+ and only the event loop at the top of the stack is considered to be active.
+ It is also the only loop that can be directly asked to terminate by calling
+ Exit() (which is done by wxDialog::EndModal()), an outer event loop can't
+ be stopped while an inner one is still running. It is however possible to
+ ask an outer event loop to terminate as soon as all its nested loops exit
+ and the control returns back to it by using ScheduleExit().
@library{wxbase}
@category{appmanagement}
Called by wxEventLoopActivator, use an instance of this class instead
of calling this method directly to ensure that the previously active
event loop is restored.
+
+ Results in a call to wxAppConsole::OnEventLoopEnter.
*/
static void SetActive(wxEventLoopBase* loop);
+ /**
+ Returns @true if this is the main loop executed by wxApp::OnRun().
+ */
+ bool IsMain() const;
+
/**
@name Dispatch and processing
virtual bool IsOk() const;
/**
- Exit from the loop with the given exit code.
+ Exit the currently running loop with the given exit code.
+
+ The loop will exit, i.e. its Run() method will return, during the next
+ event loop iteration.
+
+ Notice that this method can only be used if this event loop is the
+ currently running one, i.e. its IsRunning() returns @true. If this is
+ not the case, an assert failure is triggered and nothing is done as
+ outer event loops can't be exited from immediately. Use ScheduleExit()
+ if you'd like to exit this loop even if it doesn't run currently.
*/
- virtual void Exit(int rc = 0) = 0;
+ virtual void Exit(int rc = 0);
+
+ /**
+ Schedule an exit from the loop with the given exit code.
+
+ This method is similar to Exit() but can be called even if this event
+ loop is not the currently running one -- and if it is the active loop,
+ then it works in exactly the same way as Exit().
+
+ The loop will exit as soon as the control flow returns to it, i.e.
+ after any nested loops terminate.
+
+ @since 2.9.5
+ */
+ virtual void ScheduleExit(int rc = 0) = 0;
/**
Return true if any events are available.
//@}
- /**
- @name Pending events
- */
- //@{
-
- /**
- Process all pending events; it is necessary to call this function to
- process posted events.
-
- This happens during each event loop iteration in GUI mode but
- it may be also called directly.
- */
- virtual void ProcessPendingEvents();
-
- /**
- Returns @true if there are pending events on the internal pending event list.
- */
- bool HasPendingEvents() const;
-
- /**
- Temporary suspends processing of the pending events.
-
- @see ResumeProcessingOfPendingEvents()
- */
- void SuspendProcessingOfPendingEvents();
-
- /**
- Resume processing of the pending events previously stopped because of a
- call to SuspendProcessingOfPendingEvents().
- */
- void ResumeProcessingOfPendingEvents();
-
- //@}
-
-
/**
@name Idle handling
*/
//@{
/**
- Returns @true if called from inside Yield().
+ Returns @true if called from inside Yield() or from inside YieldFor().
*/
virtual bool IsYielding() const;
happens normally (because of Exit() call) or abnormally (because of an
exception thrown from inside the loop).
- Default version does nothing.
+ The default implementation calls wxAppConsole::OnEventLoopExit.
*/
virtual void OnExit();
};
*/
~wxEventLoopActivator();
};
+
+/**
+ @class wxGUIEventLoop
+
+ A generic implementation of the GUI event loop.
+
+ @library{wxbase}
+ @category{appmanagement}
+*/
+class wxGUIEventLoop : public wxEventLoopBase
+{
+public:
+ wxGUIEventLoop();
+ virtual ~wxGUIEventLoop();
+};
+
+
projects / wxWidgets.git / blobdiff