Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

second part of #10320: move wxApp event handling functions to wxEventLoopBase (in particular move Yield() functions); add backward compatible redirections to wxApp; update docs; remove global lists wxPendingEvents and wxPendingEventsLocker

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@58911 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2009-02-15 14:25:08 +00:00
parent 145bbf1fdf
commit dde19c2180
50 changed files with 1104 additions and 1070 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
interface/wx/app.h
View File

@@ -57,31 +57,26 @@ public:
/**
@name Event-handling
Note that you should look at wxEvtLoopBase for more event-processing
documentation.
*/
//@{
/**
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).
Called by wxWidgets on creation of the application. Override this if you wish
to provide your own (environment-dependent) main loop.
This can be used for programming event loops, e.g.
@code
while (app.Pending())
Dispatch();
@endcode
@return @false if the event loop should stop and @true otherwise.
@see Pending(), wxEventLoopBase
@return 0 under X, and the wParam of the WM_QUIT message under Windows.
*/
virtual bool Dispatch();
virtual int MainLoop();
/**
Call this to explicitly exit the main message (event) loop.
You should normally exit the main loop (and the application) by deleting
the top window.
This function simply calls wxEvtLoopBase::Exit() on the active loop.
*/
virtual void ExitMainLoop();
@@ -108,81 +103,6 @@ public:
wxEventFunction func,
wxEvent& event) const;
/**
Returns @true if called from inside Yield().
*/
virtual bool IsYielding() const;
/**
Process all pending events; it is necessary to call this function to
process posted events.
This happens during each event loop iteration in GUI mode but if there is
no main loop, it may be also called directly.
*/
virtual void ProcessPendingEvents();
/**
Called by wxWidgets on creation of the application. Override this if you wish
to provide your own (environment-dependent) main loop.
@return 0 under X, and the wParam of the WM_QUIT message under Windows.
*/
virtual int MainLoop();
/**
Returns @true if unprocessed events are in the window system event queue.
@see Dispatch()
*/
virtual bool Pending();
/**
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 ::wxSafeYield for a better function.
You can avoid unwanted reentrancies also using IsYielding().
Note that Yield() will not flush the message logs. This is intentional as
calling 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 wxLog::FlushActive.
Calling Yield() recursively is normally an error and an assert failure is
raised in debug build if such situation is detected. However if the
@a onlyIfNeeded parameter is @true, the method will just silently
return @false instead.
*/
bool Yield(bool onlyIfNeeded = false);
/**
Works like Yield() with @e onlyIfNeeded == @true, except that it allows
the caller to specify a mask of the ::wxEventCategory 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 Yield() since it ensures that
only the events you're interested to are processed; i.e. helps to avoid
unwanted reentrancies.
*/
bool YieldFor(long eventsToProcess);
/**
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()).
*/
virtual bool IsEventAllowedInsideYield(wxEventCategory cat) const;
//@}

12
interface/wx/event.h
View File

@@ -23,7 +23,7 @@ enum wxEventPropagation
/**
The different categories for a wxEvent; see wxEvent::GetEventCategory.
@note They are used as OR-combinable flags by wxApp::Yield.
@note They are used as OR-combinable flags by wxEventLoopBase::YieldFor.
*/
enum wxEventCategory
{
@@ -58,8 +58,8 @@ enum wxEventCategory
wxEVT_CATEGORY_THREAD = 16,
/**
This mask is used in wxApp::Yield to specify that all event categories should
be processed.
This mask is used in wxEventLoopBase::YieldFor to specify that all event
categories should be processed.
*/
wxEVT_CATEGORY_ALL =
wxEVT_CATEGORY_UI|wxEVT_CATEGORY_USER_INPUT|wxEVT_CATEGORY_SOCKET| \
@@ -148,7 +148,7 @@ public:
/**
Returns a generic category for this event.
This function is used to selectively process events in wxApp::Yield.
This function is used to selectively process events in wxEventLoopBase::YieldFor.
*/
virtual wxEventCategory GetEventCategory() const;
@@ -2537,7 +2537,7 @@ public:
@library{wxcore}
@category{events}
@see @ref overview_thread, wxApp::YieldFor
@see @ref overview_thread, wxEventLoopBase::YieldFor
*/
class wxThreadEvent : public wxCommandEvent
{
@@ -2558,7 +2558,7 @@ public:
Returns @c wxEVT_CATEGORY_THREAD.
This is important to avoid unwanted processing of thread events
when calling wxApp::YieldFor().
when calling wxEventLoopBase::YieldFor().
*/
virtual wxEventCategory GetEventCategory() const;
};

178
interface/wx/evtloop.h
View File

@@ -18,7 +18,7 @@
@library{wxbase}
@category{appmanagement}
@see wxApp
@see wxApp, wxEventLoopActivator
*/
class wxEventLoopBase
{
@@ -42,10 +42,9 @@ public:
/**
Use this to check whether the event loop was successfully created
before using it
*/
virtual bool IsOk() const;
@name Dispatch and processing
*/
//@{
/**
Start the event loop, return the exit code when it is finished.
@@ -60,6 +59,21 @@ public:
*/
virtual int Run() = 0;
/**
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.
*/
bool IsRunning() const;
/**
Use this to check whether the event loop was successfully created
before using it
*/
virtual bool IsOk() const;
/**
Exit from the loop with the given exit code.
*/
@@ -73,13 +87,21 @@ public:
virtual bool Pending() const = 0;
/**
Dispatch a single event.
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).
If there are currently no events in the queue, blocks until an event
becomes available.
This can be used for programming event loops, e.g.
@return @false only if the event loop should terminate.
*/
@code
while (evtloop->Pending())
evtloop->Dispatch();
@endcode
@return @false if the event loop should stop and @true otherwise.
@see Pending(), wxEventLoopBase
*/
virtual bool Dispatch() = 0;
/**
@@ -100,21 +122,139 @@ public:
*/
virtual int DispatchTimeout(unsigned long timeout) = 0;
/**
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.
*/
bool IsRunning() const;
/**
Called by wxWidgets to wake up the event loop even if it is currently
blocked inside Dispatch().
*/
virtual void WakeUp() = 0;
//@}
/**
@name Pending events
*/
//@{
/**
Process all pending events; it is necessary to call this function to
process posted events.
This happens during each event loop iteration in GUI mode but
it may be also called directly.
*/
virtual void ProcessPendingEvents();
/**
Returns @true if there are pending events on the internal pending event list.
*/
bool HasPendingEvents() const;
/**
Temporary suspends processing of the pending events.
@see ResumeProcessingOfPendingEvents()
*/
void SuspendProcessingOfPendingEvents();
/**
Resume processing of the pending events previously stopped because of a
call to SuspendProcessingOfPendingEvents().
*/
void ResumeProcessingOfPendingEvents();
//@}
/**
@name Idle handling
*/
//@{
/**
Makes sure that idle events are sent again.
*/
virtual void WakeUpIdle();
/**
This virtual function is called when the application becomes idle and
normally just sends wxIdleEvent to all interested parties.
It should return @true if more idle events are needed, @false if not.
*/
virtual bool ProcessIdle();
//@}
/**
@name Yield-related hooks
*/
//@{
/**
Returns @true if called from inside Yield().
*/
virtual bool IsYielding() const;
/**
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 ::wxSafeYield for a better function.
You can avoid unwanted reentrancies also using IsYielding().
Note that Yield() will not flush the message logs. This is intentional as
calling 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 wxLog::FlushActive.
Calling Yield() recursively is normally an error and an assert failure is
raised in debug build if such situation is detected. However if the
@a onlyIfNeeded parameter is @true, the method will just silently
return @false instead.
*/
bool Yield(bool onlyIfNeeded = false);
/**
Works like Yield() with @e onlyIfNeeded == @true, except that it allows
the caller to specify a mask of the ::wxEventCategory 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 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 wxEvtHandler::AddPendingEvent or
wxEvtHandler::QueueEvent are instead selectively processed by all ports.
@see wxEvent::GetEventCategory
*/
bool YieldFor(long eventsToProcess);
/**
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()).
@see wxEvent::GetEventCategory
*/
virtual bool IsEventAllowedInsideYield(wxEventCategory cat) const;
//@}
protected:
/**
This function is called before the event loop terminates, whether this