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