allow to change the event propagation level (modified patch 743086)
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@22068 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
@@ -44,6 +44,25 @@ The type of the event, such as wxEVENT\_TYPE\_BUTTON\_COMMAND.
|
||||
|
||||
Identifier for the window.
|
||||
|
||||
\membersection{wxEvent::m\_propagationLevel}
|
||||
|
||||
\member{int}{m\_propagationLevel}
|
||||
|
||||
Indicates how many levels the event can propagate. This member is protected and
|
||||
should typically only be set in the constructors of the derived classes. It
|
||||
may be temporarily changed by \helpref{StopPropagation}{wxeventstoppropagation}
|
||||
and \helpref{ResumePropagation}{wxeventresumepropagation} and tested with
|
||||
\helpref{ShouldPropagate}{wxeventshouldpropagate}.
|
||||
|
||||
The initial value is set to either {\tt wxEVENT\_PROPAGATION\_NONE} (by
|
||||
default) meaning that the event shouldn't be propagated at all or to
|
||||
{\tt wxEVENT\_PROPAGATION\_MAX} (for command events) meaning that it should be
|
||||
propagated as much as necessary.
|
||||
|
||||
Any positive number means that the event should be propagated but no more than
|
||||
the given number of times. E.g. the propagation level may be set to $1$ to
|
||||
propagate the event to its parent only, but not to its grandparent.
|
||||
|
||||
\membersection{wxEvent::m\_skipped}
|
||||
|
||||
\member{bool}{m\_skipped}
|
||||
@@ -92,13 +111,13 @@ such as wxEVENT\_TYPE\_BUTTON\_COMMAND.
|
||||
|
||||
\membersection{wxEvent::GetId}
|
||||
|
||||
\func{int}{GetId}{\void}
|
||||
\constfunc{int}{GetId}{\void}
|
||||
|
||||
Returns the identifier associated with this event, such as a button command id.
|
||||
|
||||
\membersection{wxEvent::GetSkipped}
|
||||
|
||||
\func{bool}{GetSkipped}{\void}
|
||||
\constfunc{bool}{GetSkipped}{\void}
|
||||
|
||||
Returns true if the event handler should be skipped, false otherwise.
|
||||
|
||||
@@ -108,6 +127,23 @@ Returns true if the event handler should be skipped, false otherwise.
|
||||
|
||||
Gets the timestamp for the event.
|
||||
|
||||
\membersection{wxEvent::IsCommandEvent}\label{wxeventiscommandevent}
|
||||
|
||||
\constfunc{bool}{IsCommandEvent}{\void}
|
||||
|
||||
Returns true if the event is or is derived from
|
||||
\helpref{wxCommandEvent}{wxcommandevent} else it returns false.
|
||||
Note: Exists only for optimization purposes.
|
||||
|
||||
|
||||
\membersection{wxEvent::ResumePropagation}\label{wxeventresumepropagation}
|
||||
|
||||
\func{void}{ResumePropagation}{\param{int }{propagationLevel}}
|
||||
|
||||
Sets the propagation level to the given value (for example returned from an
|
||||
earlier call to \helpref{StopPropagation}{wxeventstoppropagation}).
|
||||
|
||||
|
||||
\membersection{wxEvent::SetEventObject}
|
||||
|
||||
\func{void}{SetEventObject}{\param{wxObject* }{object}}
|
||||
@@ -134,6 +170,13 @@ Sets the timestamp for the event.
|
||||
|
||||
Sets the originating object.
|
||||
|
||||
\membersection{wxEvent::ShouldPropagate}\label{wxeventshouldpropagate}
|
||||
|
||||
\constfunc{bool}{ShouldPropagate}{\void}
|
||||
|
||||
Test if this event should be propagated or not, i.e. if the propagation level
|
||||
is currently greater than $0$.
|
||||
|
||||
\membersection{wxEvent::Skip}\label{wxeventskip}
|
||||
|
||||
\func{void}{Skip}{\param{bool}{ skip = true}}
|
||||
@@ -142,3 +185,14 @@ Called by an event handler to tell the event system that the
|
||||
event handler should be skipped, and the next valid handler used
|
||||
instead.
|
||||
|
||||
\membersection{wxEvent::StopPropagation}
|
||||
|
||||
\func{int}{StopPropagation}{\void}\label{wxeventstoppropagation}
|
||||
|
||||
Stop the event from propagating to its parent window.
|
||||
|
||||
Returns the old propagation level value which may be later passed to
|
||||
\helpref{ResumePropagation}{wxeventresumepropagation} to allow propagating the
|
||||
event again.
|
||||
|
||||
|
||||
|
@@ -142,18 +142,20 @@ class table is tried, and so on until no more tables exist or an appropriate fun
|
||||
in which case the function exits.
|
||||
\item The search is applied down the entire chain of event handlers (usually the chain has a length
|
||||
of one). If this succeeds, the function exits.
|
||||
\item If the object is a wxWindow and the event is a wxCommandEvent, {\bf ProcessEvent} is
|
||||
recursively applied to the parent window's event handler. If this returns true, the function exits.
|
||||
\item If the object is a wxWindow and the event is set to set to propagate (in the library only
|
||||
wxCommandEvent based events are set to propagate), {\bf ProcessEvent} is recursively applied
|
||||
to the parent window's event handler. If this returns true, the function exits.
|
||||
\item Finally, {\bf ProcessEvent} is called on the wxApp object.
|
||||
\end{enumerate}
|
||||
|
||||
{\bf Pay close attention to Step 5.} People often overlook or get
|
||||
confused by this powerful feature of the wxWindows event processing
|
||||
system. To put it a different way, events derived either directly or
|
||||
indirectly from wxCommandEvent will travel up the containment
|
||||
hierarchy from child to parent until an event handler is found that
|
||||
doesn't call event.Skip(). Events not derived from wxCommandEvent are
|
||||
sent only to the window they occurred in and then stop.
|
||||
system. To put it a different way, events set to propagate
|
||||
(\helpref{See: wxEvent::ShouldPropagate}{wxeventshouldpropagate})
|
||||
(most likely derived either directly or indirectly from wxCommandEvent)
|
||||
will travel up the containment hierarchy from child to parent until the
|
||||
maximal propagation level is reached or an event handler is found that
|
||||
doesn't call \helpref{event.Skip()}{wxeventskip}.
|
||||
|
||||
Finally, there is another additional complication (which, in fact, simplifies
|
||||
life of wxWindows programmers significantly): when propagating the command
|
||||
@@ -182,12 +184,13 @@ event.
|
||||
Note that your application may wish to override ProcessEvent to redirect processing of
|
||||
events. This is done in the document/view framework, for example, to allow event handlers
|
||||
to be defined in the document or view. To test for command events (which will probably
|
||||
be the only events you wish to redirect), you may use wxEvent::IsCommandEvent for
|
||||
efficiency, instead of using the slower run-time type system.
|
||||
be the only events you wish to redirect), you may use
|
||||
\helpref{wxEvent::IsCommandEvent}{wxeventiscommandevent} for efficiency,
|
||||
instead of using the slower run-time type system.
|
||||
|
||||
As mentioned above, only command events are recursively applied to the parents event
|
||||
handler. As this quite often causes confusion for users, here is a list of system
|
||||
events which will NOT get sent to the parent's event handler:
|
||||
handler in the libary itself. As this quite often causes confusion for users,
|
||||
here is a list of system events which will NOT get sent to the parent's event handler:
|
||||
|
||||
\begin{twocollist}\itemsep=0pt
|
||||
\twocolitem{\helpref{wxEvent}{wxevent}}{The event base class}
|
||||
|
Reference in New Issue
Block a user