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 object of this class is created by wxAppTraits::CreateEventLoop() and
  16     used by wxApp to run the main application event loop.
  17
  18     @library{wxbase}
  19     @category{appmanagement}
  20
  21     @see wxApp
  22 */
  23 class wxEventLoopBase
  24 {
  25 public:
  26     /**
  27         Return the currently active (running) event loop.
  28
  29         May return @NULL if there is no active event loop (e.g. during
  30         application startup or shutdown).
  31      */
  32     static wxEventLoopBase *GetActive();
  33
  34     /**
  35         Set currently active (running) event loop.
  36
  37         Called by wxEventLoopActivator, use an instance of this class instead
  38         of calling this method directly to ensure that the previously active
  39         event loop is restored.
  40      */
  41     static void SetActive(wxEventLoopBase* loop);
  42
  43
  44     /**
  45         Use this to check whether the event loop was successfully created
  46         before using it
  47      */
  48     virtual bool IsOk() const;
  49
  50     /**
  51         Start the event loop, return the exit code when it is finished.
  52
  53         Logically, this method calls Dispatch() in a loop until it returns
  54         @false and also takes care of generating idle events during each loop
  55         iteration. However not all implementations of this class really
  56         implement it like this (e.g. wxGTK does not) so you shouldn't rely on
  57         Dispatch() being called from inside this function.
  58
  59         @return The argument passed to Exit() which terminated this event loop.
  60      */
  61     virtual int Run() = 0;
  62
  63     /**
  64         Exit from the loop with the given exit code.
  65      */
  66     virtual void Exit(int rc = 0) = 0;
  67
  68     /**
  69         Return true if any events are available.
  70
  71         If this method returns @true, calling Dispatch() will not block.
  72      */
  73     virtual bool Pending() const = 0;
  74
  75     /**
  76         Dispatch a single event.
  77
  78         If there are currently no events in the queue, blocks until an event
  79         becomes available.
  80
  81         @return @false only if the event loop should terminate.
  82      */
  83     virtual bool Dispatch() = 0;
  84
  85     /**
  86         Dispatch an event but not wait longer than the specified timeout for
  87         it.
  88
  89         If an event is received before the specified @a timeout expires, it is
  90         processed and the function returns 1 normally or 0 if the event loop
  91         should quite. Otherwise, i.e. if the timeout expires, the functions
  92         returns -1 without processing any events.
  93
  94         @param timeout
  95             The maximal time to wait for the events in milliseconds.
  96
  97         @return
  98             1 if an event was processed, 0 if the event loop should quit or -1
  99             if the timeout expired.
 100      */
 101     virtual int DispatchTimeout(unsigned long timeout) = 0;
 102
 103     /**
 104         Return true if this event loop is currently running.
 105
 106         Notice that even if this event loop hasn't terminated yet but has just
 107         spawned a nested (e.g. modal) event loop, this method would return
 108         @false.
 109      */
 110     bool IsRunning() const;
 111
 112     /**
 113         Called by wxWidgets to wake up the event loop even if it is currently
 114         blocked inside Dispatch().
 115      */
 116     virtual void WakeUp() = 0;
 117
 118 protected:
 119     /**
 120         This function is called before the event loop terminates, whether this
 121         happens normally (because of Exit() call) or abnormally (because of an
 122         exception thrown from inside the loop).
 123
 124         Default version does nothing.
 125      */
 126     virtual void OnExit();
 127 };
 128
 129 /**
 130     @class wxEventLoopActivator
 131
 132     Makes an event loop temporarily active.
 133
 134     This class is used to make the event loop active during its life-time,
 135     e.g.:
 136     @code
 137         class MyEventLoop : public wxEventLoopBase { ... };
 138
 139         void RunMyLoop()
 140         {
 141             MyEventLoop loop;
 142             wxEventLoopActivator activate(&loop);
 143
 144             ...
 145         } // the previously active event loop restored here
 146     @endcode
 147
 148     @library{wxbase}
 149     @category{appmanagement}
 150
 151     @see wxEventLoopBase
 152 */
 153 class wxEventLoopActivator
 154 {
 155 public:
 156     /**
 157         Makes the loop passed as the parameter currently active.
 158
 159         This saves the current return value of wxEventLoopBase::GetActive() and
 160         then calls wxEventLoopBase::SetActive() with the given @a loop.
 161      */
 162     wxEventLoopActivator(wxEventLoopBase *loop);
 163
 164     /**
 165         Restores the previously active event loop stored by the constructor.
 166      */
 167     ~wxEventLoopActivator();
 168 };