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