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         Return true if this event loop is currently running.
  87
  88         Notice that even if this event loop hasn't terminated yet but has just
  89         spawned a nested (e.g. modal) event loop, this method would return
  90         @false.
  91      */
  92     bool IsRunning() const;
  93
  94     /**
  95         Called by wxWidgets to wake up the event loop even if it is currently
  96         blocked inside Dispatch().
  97      */
  98     virtual void WakeUp() = 0;
  99
 100 protected:
 101     /**
 102         This function is called before the event loop terminates, whether this
 103         happens normally (because of Exit() call) or abnormally (because of an
 104         exception thrown from inside the loop).
 105
 106         Default version does nothing.
 107      */
 108     virtual void OnExit();
 109 };
 110
 111 /**
 112     @class wxEventLoopActivator
 113
 114     Makes an event loop temporarily active.
 115
 116     This class is used to make the event loop active during its life-time,
 117     e.g.:
 118     @code
 119         class MyEventLoop : public wxEventLoopBase { ... };
 120
 121         void RunMyLoop()
 122         {
 123             MyEventLoop loop;
 124             wxEventLoopActivator activate(&loop);
 125
 126             ...
 127         } // the previously active event loop restored here
 128     @endcode
 129
 130     @library{wxbase}
 131     @category{appmanagement}
 132
 133     @see wxEventLoopBase
 134 */
 135 class wxEventLoopActivator
 136 {
 137 public:
 138     /**
 139         Makes the loop passed as the parameter currently active.
 140
 141         This saves the current return value of wxEventLoopBase::GetActive() and
 142         then calls wxEventLoopBase::SetActive() with the given @a loop.
 143      */
 144     wxEventLoopActivator(wxEventLoopBase *loop);
 145
 146     /**
 147         Restores the previously active event loop stored by the constructor.
 148      */
 149     ~wxEventLoopActivator();
 150 };