.. include:: headings.inc .. _EventLoopBase: ========================================================================================================================================== |phoenix_title| **EventLoopBase** ========================================================================================================================================== Base class for all event loop implementations. An event loop is a class which queries the queue of native events sent to the wxWidgets application and dispatches them to the appropriate EvtHandlers. An object of this class is created by :meth:`AppTraits.CreateEventLoop` and used by :ref:`App` to run the main application event loop. Temporary event loops are usually created by :meth:`Dialog.ShowModal` . You can create your own event loop if you need, provided that you restore the main event loop once yours is destroyed (see :ref:`EventLoopActivator`). .. seealso:: :ref:`App`, :ref:`EventLoopActivator` | |class_hierarchy| Inheritance Diagram ===================================== Inheritance diagram for class **EventLoopBase** .. raw:: html

Inheritance diagram of EventLoopBase

| |method_summary| Methods Summary ================================ ================================================================================ ================================================================================ :meth:`~EventLoopBase.Dispatch` Dispatches the next event in the windowing system event queue. :meth:`~EventLoopBase.DispatchTimeout` Dispatch an event but not wait longer than the specified timeout for it. :meth:`~EventLoopBase.Exit` Exit from the loop with the given exit code. :meth:`~EventLoopBase.GetActive` Return the currently active (running) event loop. :meth:`~EventLoopBase.IsEventAllowedInsideYield` Returns ``True`` if the given event category is allowed inside a :meth:`YieldFor` call (i.e. :meth:`~EventLoopBase.IsMain` Returns ``True`` if this is the main loop executed by :meth:`App.OnRun` . :meth:`~EventLoopBase.IsOk` Use this to check whether the event loop was successfully created before using it. :meth:`~EventLoopBase.IsRunning` Return ``True`` if this event loop is currently running. :meth:`~EventLoopBase.IsYielding` Returns ``True`` if called from inside :meth:`Yield` or from inside :meth:`YieldFor` . :meth:`~EventLoopBase.Pending` Return ``True`` if any events are available. :meth:`~EventLoopBase.ProcessIdle` This virtual function is called when the application becomes idle and normally just sends :ref:`IdleEvent` to all interested parties. :meth:`~EventLoopBase.Run` Start the event loop, return the exit code when it is finished. :meth:`~EventLoopBase.SetActive` Set currently active (running) event loop. :meth:`~EventLoopBase.WakeUp` Called by wxWidgets to wake up the event loop even if it is currently blocked inside :meth:`Dispatch` . :meth:`~EventLoopBase.WakeUpIdle` Makes sure that idle events are sent again. :meth:`~EventLoopBase.Yield` Yields control to pending messages in the windowing system. :meth:`~EventLoopBase.YieldFor` Works like :meth:`Yield` with `onlyIfNeeded` == ``True``, except that it allows the caller to specify a mask of the :ref:`EventCategory` values which indicates which events should be processed and which should instead be "delayed" (i.e. ================================================================================ ================================================================================ | |api| Class API =============== .. class:: EventLoopBase(object) Base class for all event loop implementations. .. method:: Dispatch(self) Dispatches the next event in the windowing system event queue. Blocks until an event appears if there are none currently (use :meth:`Pending` if this is not wanted). This can be used for programming event loops, e.g. :: while evtloop.Pending(): evtloop.Dispatch() :rtype: `bool` :returns: ``False`` if the event loop should stop and ``True`` otherwise. .. seealso:: :meth:`Pending` , :ref:`EventLoopBase` .. method:: DispatchTimeout(self, timeout) Dispatch an event but not wait longer than the specified timeout for it. If an event is received before the specified `timeout` expires, it is processed and the function returns 1 normally or 0 if the event loop should quite. Otherwise, i.e. if the timeout expires, the functions returns -1 without processing any events. :param `timeout`: The maximal time to wait for the events in milliseconds. :type `timeout`: long :rtype: `int` :returns: 1 if an event was processed, 0 if the event loop should quit or -1 if the timeout expired. .. method:: Exit(self, rc=0) Exit from the loop with the given exit code. :param `rc`: :type `rc`: int .. staticmethod:: GetActive() Return the currently active (running) event loop. May return ``None`` if there is no active event loop (e.g. during application startup or shutdown). :rtype: :ref:`EventLoopBase` .. method:: IsEventAllowedInsideYield(self, cat) Returns ``True`` if the given event category is allowed inside a :meth:`YieldFor` call (i.e. compares the given category against the last mask passed to :meth:`YieldFor` ). :param `cat`: :type `cat`: EventCategory :rtype: `bool` .. seealso:: :meth:`Event.GetEventCategory` .. method:: IsMain(self) Returns ``True`` if this is the main loop executed by :meth:`App.OnRun` . :rtype: `bool` .. method:: IsOk(self) Use this to check whether the event loop was successfully created before using it. :rtype: `bool` .. method:: IsRunning(self) Return ``True`` if this event loop is currently running. Notice that even if this event loop hasn't terminated yet but has just spawned a nested (e.g. modal) event loop, this method would return ``False``. :rtype: `bool` .. method:: IsYielding(self) Returns ``True`` if called from inside :meth:`Yield` or from inside :meth:`YieldFor` . :rtype: `bool` .. method:: Pending(self) Return ``True`` if any events are available. If this method returns ``True``, calling :meth:`Dispatch` will not block. :rtype: `bool` .. method:: ProcessIdle(self) This virtual function is called when the application becomes idle and normally just sends :ref:`IdleEvent` to all interested parties. It should return ``True`` if more idle events are needed, ``False`` if not. :rtype: `bool` .. method:: Run(self) Start the event loop, return the exit code when it is finished. Logically, this method calls :meth:`Dispatch` in a loop until it returns ``False`` and also takes care of generating idle events during each loop iteration. However not all implementations of this class really implement it like this (e.g. wxGTK does not) so you shouldn't rely on :meth:`Dispatch` being called from inside this function. :rtype: `int` :returns: The argument passed to :meth:`Exit` which terminated this event loop. .. staticmethod:: SetActive(loop) Set currently active (running) event loop. Called by :ref:`EventLoopActivator`, use an instance of this class instead of calling this method directly to ensure that the previously active event loop is restored. Results in a call to :meth:`AppConsole.OnEventLoopEnter` . :param `loop`: :type `loop`: EventLoopBase .. method:: WakeUp(self) Called by wxWidgets to wake up the event loop even if it is currently blocked inside :meth:`Dispatch` . .. method:: WakeUpIdle(self) Makes sure that idle events are sent again. .. method:: Yield(self, onlyIfNeeded=False) Yields control to pending messages in the windowing system. This can be useful, for example, when a time-consuming process writes to a text window. Without an occasional yield, the text window will not be updated properly, and on systems with cooperative multitasking, such as Windows 3.1 other processes will not respond. Caution should be exercised, however, since yielding may allow the user to perform actions which are not compatible with the current task. Disabling menu items or whole menus during processing can avoid unwanted reentrance of code: see :func:`SafeYield` for a better function. You can avoid unwanted reentrancies also using :meth:`IsYielding` . Note that :meth:`Yield` will not flush the message logs. This is intentional as calling :meth:`Yield` is usually done to quickly update the screen and popping up a message box dialog may be undesirable. If you do wish to flush the log messages immediately (otherwise it will be done during the next idle loop iteration), call :meth:`Log.FlushActive` . Calling :meth:`Yield` recursively is normally an error and an assert failure is raised in debug build if such situation is detected. However if the `onlyIfNeeded` parameter is ``True``, the method will just silently return ``False`` instead. :param `onlyIfNeeded`: :type `onlyIfNeeded`: bool :rtype: `bool` .. method:: YieldFor(self, eventsToProcess) Works like :meth:`Yield` with `onlyIfNeeded` == ``True``, except that it allows the caller to specify a mask of the :ref:`EventCategory` values which indicates which events should be processed and which should instead be "delayed" (i.e. processed by the main loop later). Note that this is a safer alternative to :meth:`Yield` since it ensures that only the events you're interested to will be processed; i.e. this method helps to avoid unwanted reentrancies. Note that currently only wxMSW and wxGTK do support selective yield of native events coming from the underlying GUI toolkit. wxWidgets events posted using :meth:`EvtHandler.AddPendingEvent` or :meth:`EvtHandler.QueueEvent` are instead selectively processed by all ports. :param `eventsToProcess`: :type `eventsToProcess`: long :rtype: `bool` .. seealso:: :meth:`Event.GetEventCategory`