name wxThreadEvent and YieldFor in wxProgressDialog and in thread overview; update the sample code to use new event macros; minor other changes

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@59002 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2009-02-18 19:32:00 +00:00
parent c4021a7920
commit 3a5677401f
5 changed files with 63 additions and 45 deletions

View File

@@ -441,32 +441,10 @@ or unset this flag for the dialogs that have it on by default.
Typically events that deal with a window as a window (size, motion,
paint, mouse, keyboard, etc.) are sent only to the window. Events
that have a higher level of meaning or are generated by the window
itself, (button click, menu select, tree expand, etc.) are command
itself (button click, menu select, tree expand, etc.) are command
events and are sent up to the parent to see if it is interested in the event.
As mentioned above, only command events are recursively applied to the parents
event handler in the library itself. As this quite often causes confusion for
users, here is a list of system events that will @em not get sent to the
parent's event handler:
@li wxEvent: The event base class
@li wxActivateEvent: A window or application activation event
@li wxCloseEvent: A close window or end session event
@li wxEraseEvent: An erase background event
@li wxFocusEvent: A window focus event
@li wxKeyEvent: A keypress event
@li wxIdleEvent: An idle event
@li wxInitDialogEvent: A dialog initialisation event
@li wxJoystickEvent: A joystick event
@li wxMenuEvent: A menu event
@li wxMouseEvent: A mouse event
@li wxMoveEvent: A move event
@li wxPaintEvent: A paint event
@li wxQueryLayoutInfoEvent: Used to query layout information
@li wxSetCursorEvent: Used for special cursor processing based on current mouse position
@li wxSizeEvent: A size event
@li wxScrollWinEvent: A scroll event sent by a scrolled window (not a scroll bar)
@li wxSysColourChangedEvent: A system colour change event
More precisely, as said above, all event classes @b not deriving from wxCommandEvent
(see the wxEvent inheritance map) do @b not propagate upward.
In some cases, it might be desired by the programmer to get a certain number
of system events in a parent window, for example all key events sent to, but not
@@ -763,7 +741,7 @@ your identifiers don't conflict accidentally.
@subsection overview_events_macros Event Handling Summary
@subsection overview_events_list List of wxWidgets events
For the full list of event classes, please see the
@ref group_class_events "event classes group page".

View File

@@ -13,10 +13,13 @@
/**
@page overview_thread Multithreading
@page overview_thread Multithreading Overview
Classes: wxThread, wxThreadHelper, wxMutex, wxCriticalSection, wxCondition, wxSemaphore
@section overview_thread_intro When to use multiple threads
wxWidgets provides a complete set of classes encapsulating objects necessary in
multithreaded (MT) programs: the wxThread class itself and different
synchronization objects: mutexes (see wxMutex) and critical sections (see
@@ -45,13 +48,17 @@ two possible implementation choices:
- use wxIdleEvent (e.g. to perform a long calculation while updating a progress dialog)
- do everything at once but call wxWindow::Update() or wxApp::YieldFor(wxEVT_CATEGORY_UI)
periodically to update the screen.
If instead you choose to use threads in your application, please read also
the following sections of this overview.
If instead you choose to use threads in your application, it is strongly recommended
@section overview_thread_notes Important notes for multithreaded applications
When writing a multi-threaded application, it is strongly recommended
that <b>no secondary threads call GUI functions</b>.
The design which uses one GUI thread and several worker threads which communicate
with the main one using @b events is much more robust and will undoubtedly save you
countless problems (example: under Win32 a thread can only access GDI objects such
as pens, brushes, c created by itself and not by the other threads).
as pens, brushes, device contexts created by itself and not by the other threads).
For communication between secondary threads and the main thread, you may use
wxEvtHandler::QueueEvent or its short version ::wxQueueEvent. These functions
@@ -62,6 +69,19 @@ synchronization classes to implement the solution which suits your needs
yourself. In particular, please note that it is not enough to derive
your class from wxThread and wxEvtHandler to send messages to it: in fact, this
does not work at all.
You're instead encouraged to use wxThreadHelper as it greatly simplifies the
communication and the sharing of resources.
You should also look at the wxThread docs for important notes about secondary
threads and their deletion.
Last, remember that if wxEventLoopBase::YieldFor() is used directly or indirectly
(e.g. through wxProgressDialog) in your code, then you may have both re-entrancy
problems and also problems caused by the processing of events out of order.
To resolve the last problem wxThreadEvent can be used: thanks to its implementation
of the wxThreadEvent::GetEventCategory function wxThreadEvent classes in fact
do not get processed by wxEventLoopBase::YieldFor() unless you specify the
@c wxEVT_CATEGORY_THREAD flag.
See also the @sample{thread} for a sample showing some simple interactions
between the main and secondary threads.