phoenix_title wx.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 wx.AppTraits.CreateEventLoop and used by wx.App to run the main application event loop. Temporary event loops are usually created by wx.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 wx.EventLoopActivator).

Notice that there can be more than one event loop at any given moment, e.g. an event handler called from the main loop can show a modal dialog, which starts its own loop resulting in two nested loops, with the modal dialog being the active one (its IsRunning returns True). And a handler for a button inside the modal dialog can, of course, create another modal dialog with its own event loop and so on. So in general event loops form a stack and only the event loop at the top of the stack is considered to be active. It is also the only loop that can be directly asked to terminate by calling wx.Exit (which is done by wx.Dialog.EndModal ), an outer event loop can’t be stopped while an inner one is still running. It is however possible to ask an outer event loop to terminate as soon as all its nested loops exit and the control returns back to it by using ScheduleExit.

See also

wx.App, wx.EventLoopActivator


class_hierarchy Class Hierarchy

Inheritance diagram for class EventLoopBase:

sub_classes Known Subclasses

wx.GUIEventLoop


method_summary Methods Summary

Dispatch

Dispatches the next event in the windowing system event queue.

DispatchTimeout

Dispatch an event but not wait longer than the specified timeout for it.

Exit

Exit the currently running loop with the given exit code.

GetActive

Return the currently active (running) event loop.

IsEventAllowedInsideYield

Returns True if the given event category is allowed inside a YieldFor call (i.e.

IsMain

Returns True if this is the main loop executed by wx.App.OnRun .

IsOk

Use this to check whether the event loop was successfully created before using it.

IsRunning

Return True if this event loop is currently running.

IsYielding

Returns True if called from inside wx.Yield or from inside YieldFor .

OnExit

This function is called before the event loop terminates, whether this happens normally (because of wx.Exit call) or abnormally (because of an exception thrown from inside the loop).

Pending

Return True if any events are available.

ProcessIdle

This virtual function is called when the application becomes idle and normally just sends wx.IdleEvent to all interested parties.

Run

Start the event loop, return the exit code when it is finished.

ScheduleExit

Schedule an exit from the loop with the given exit code.

SetActive

Set currently active (running) event loop.

WakeUp

Called by wxWidgets to wake up the event loop even if it is currently blocked inside Dispatch .

WakeUpIdle

Makes sure that idle events are sent again.

Yield

Yields control to pending messages in the windowing system.

YieldFor

Works like wx.Yield with onlyIfNeeded == True, except that it allows the caller to specify a mask of the wx.EventCategory values which indicates which events should be processed and which should instead be “delayed” (i.e.


api Class API

class wx.EventLoopBase(object)

Base class for all event loop implementations.


Methods

Dispatch(self)

Dispatches the next event in the windowing system event queue.

Blocks until an event appears if there are none currently (use Pending if this is not wanted).

This can be used for programming event loops, e.g.

while evtloop.Pending():
    evtloop.Dispatch()
Return type:

bool

Returns:

False if the event loop should stop and True otherwise.



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.

Parameters:

timeout (long) – The maximal time to wait for the events in milliseconds.

Return type:

int

Returns:

1 if an event was processed, 0 if the event loop should quit or -1 if the timeout expired.



Exit(self, rc=0)

Exit the currently running loop with the given exit code.

The loop will exit, i.e. its Run method will return, during the next event loop iteration.

Notice that this method can only be used if this event loop is the currently running one, i.e. its IsRunning returns True. If this is not the case, an assert failure is triggered and nothing is done as outer event loops can’t be exited from immediately. Use ScheduleExit if you’d like to exit this loop even if it doesn’t run currently.

Parameters:

rc (int) –



static 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).

Return type:

wx.EventLoopBase



IsEventAllowedInsideYield(self, cat)

Returns True if the given event category is allowed inside a YieldFor call (i.e.

compares the given category against the last mask passed to YieldFor ).

Parameters:

cat (EventCategory) –

Return type:

bool



IsMain(self)

Returns True if this is the main loop executed by wx.App.OnRun .

Return type:

bool



IsOk(self)

Use this to check whether the event loop was successfully created before using it.

Return type:

bool



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.

Return type:

bool



IsYielding(self)

Returns True if called from inside wx.Yield or from inside YieldFor .

Return type:

bool



OnExit(self)

This function is called before the event loop terminates, whether this happens normally (because of wx.Exit call) or abnormally (because of an exception thrown from inside the loop).

The default implementation calls wx.AppConsole.OnEventLoopExit .



Pending(self)

Return True if any events are available.

If this method returns True, calling Dispatch will not block.

Return type:

bool



ProcessIdle(self)

This virtual function is called when the application becomes idle and normally just sends wx.IdleEvent to all interested parties.

It should return True if more idle events are needed, False if not.

Return type:

bool



Run(self)

Start the event loop, return the exit code when it is finished.

Logically, this method calls 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 Dispatch being called from inside this function.

Return type:

int

Returns:

The argument passed to wx.Exit which terminated this event loop.



ScheduleExit(self, rc=0)

Schedule an exit from the loop with the given exit code.

This method is similar to wx.Exit but can be called even if this event loop is not the currently running one – and if it is the active loop, then it works in exactly the same way as wx.Exit .

The loop will exit as soon as the control flow returns to it, i.e. after any nested loops terminate.

Parameters:

rc (int) –

New in version 2.9.5.



static SetActive(loop)

Set currently active (running) event loop.

Called by wx.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 wx.AppConsole.OnEventLoopEnter .

Parameters:

loop (wx.EventLoopBase) –



WakeUp(self)

Called by wxWidgets to wake up the event loop even if it is currently blocked inside Dispatch .



WakeUpIdle(self)

Makes sure that idle events are sent again.



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, 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 wx.SafeYield for a better function.

Note that wx.Yield will not flush the message logs. This is intentional as calling wx.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 wx.Log.FlushActive .

If onlyIfNeeded parameter is True and the flow control is already inside wx.Yield , i.e. IsYielding returns True, the method just silently returns False and doesn’t do anything.

Parameters:

onlyIfNeeded (bool) –

Return type:

bool



YieldFor(self, eventsToProcess)

Works like wx.Yield with onlyIfNeeded == True, except that it allows the caller to specify a mask of the wx.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 wx.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 wx.EvtHandler.AddPendingEvent or wx.EvtHandler.QueueEvent are instead selectively processed by all ports.

Parameters:

eventsToProcess (long) –

Return type:

bool