interface/wx/evtloop.h

   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 licence
   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 };