The normal order of event table searching is as follows:
-# wxApp::FilterEvent() is called. If it returns anything but @c -1
(default) the processing stops here.
- -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
- the function skips to step (7).
-# TryBefore() is called (this is where wxValidator are taken into
account for wxWindow objects). If this returns @true, the function exits.
- -# Dynamic event table of the handlers binded using Bind<>() is
+ -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
+ the function skips to step (7).
+ -# Dynamic event table of the handlers bound using Bind<>() is
searched. If a handler is found, it is executed and the function
returns @true unless the handler used wxEvent::Skip() to indicate
that it didn't handle the event in which case the search continues.
- -# Static events table of the handlers binded using event table
+ -# Static events table of the handlers bound using event table
macros is searched for this event handler. If this fails, the base
class event table table is tried, and so on until no more tables
exist or an appropriate function was found. If a handler is found,
processed, ProcessEvent() on wxTheApp object is called as the last
step.
- Notice that steps (2)-(6) are performed in ProcessEventHere() which is
- called by this function.
+ Notice that steps (2)-(6) are performed in ProcessEventLocally()
+ which is called by this function.
@param event
Event to process.
virtual bool ProcessEvent(wxEvent& event);
/**
- Try to process the event in this event handler.
+ Try to process the event in this handler and all those chained to it.
+
+ As explained in ProcessEvent() documentation, the event handlers may be
+ chained in a doubly-linked list. This function tries to process the
+ event in this handler (including performing any pre-processing done in
+ TryBefore(), e.g. applying validators) and all those following it in
+ the chain until the event is processed or the chain is exhausted.
- This method is called from ProcessEvent(), please see the detailed
- description of the event processing logic there.
+ This function is called from ProcessEvent() and, in turn, calls
+ TryThis() for each handler in turn. It is not virtual and so cannot be
+ overridden but can, and should, be called to forward an event to
+ another handler instead of ProcessEvent() which would result in a
+ duplicate call to TryAfter(), e.g. resulting in all unprocessed events
+ being sent to the application object multiple times.
- It is @em not virtual and so may not be overridden but it does call
- virtual TryBefore() which may be overridden.
+ @since 2.9.1
@param event
Event to process.
@return
- @true if this object itself defines a handler for this event and
- the handler didn't skip the event.
+ @true if this handler of one of those chained to it processed the
+ event.
*/
- bool ProcessEventHere(wxEvent& event);
+ bool ProcessEventLocally(wxEvent& event);
/**
Processes an event by calling ProcessEvent() and handles any exceptions
@param userData
Data to be associated with the event table entry.
+ @see @ref overview_cpp_rtti_disabled
+
@since 2.9.0
*/
template <typename EventTag, typename Functor>
@param userData
Data to be associated with the event table entry.
+ @see @ref overview_cpp_rtti_disabled
+
@since 2.9.0
*/
template <typename EventTag, typename Class, typename EventArg, typename EventHandler>
This method can only unbind functions, functors or methods which have
been added using the Bind<>() method. There is no way to unbind
- functions binded using the (static) event tables.
+ functions bound using the (static) event tables.
@param eventType
The event type associated with this event handler.
@param userData
Data associated with the event table entry.
+ @see @ref overview_cpp_rtti_disabled
+
@since 2.9.0
*/
template <typename EventTag, typename Functor>
@param userData
Data associated with the event table entry.
+ @see @ref overview_cpp_rtti_disabled
+
@since 2.9.0
*/
template <typename EventTag, typename Class, typename EventArg, typename EventHandler>
};
@endcode
- @see ProcessEvent(), ProcessEventHere()
+ @see ProcessEvent()
*/
virtual bool TryBefore(wxEvent& event);
+ /**
+ Try to process the event in this event handler.
+
+ This method is called from ProcessEventLocally() and thus, indirectly,
+ from ProcessEvent(), please see the detailed description of the event
+ processing logic there.
+
+ It is currently @em not virtual and so may not be overridden.
+
+ @since 2.9.1
+
+ @param event
+ Event to process.
+ @return
+ @true if this object itself defines a handler for this event and
+ the handler didn't skip the event.
+ */
+ bool TryThis(wxEvent& event);
+
/**
Method called by ProcessEvent() as last resort.
};
@endcode
- @see ProcessEvent(), ProcessEventHere()
+ @see ProcessEvent()
*/
virtual bool TryAfter(wxEvent& event);
};
A paint event is sent when a window's contents needs to be repainted.
- Please notice that in general it is impossible to change the drawing of a
- standard control (such as wxButton) and so you shouldn't attempt to handle
- paint events for them as even if it might work on some platforms, this is
- inherently not portable and won't work everywhere.
-
- @remarks
- Note that in a paint event handler, the application must always create a
- wxPaintDC object, even if you do not use it. Otherwise, under MS Windows,
- refreshing for this and other windows will go wrong.
- For example:
+ The handler of this event must create a wxPaintDC object and use it for
+ painting the window contents. For example:
@code
void MyWindow::OnPaint(wxPaintEvent& event)
{
DrawMyDocument(dc);
}
@endcode
+
+ Notice that you must @e not create other kinds of wxDC (e.g. wxClientDC or
+ wxWindowDC) in EVT_PAINT handlers and also don't create wxPaintDC outside
+ of this event handlers.
+
+
You can optimize painting by retrieving the rectangles that have been damaged
and only repainting these. The rectangles are in terms of the client area,
and are unscrolled, so you will need to do some calculations using the current
}
@endcode
+ @remarks
+ Please notice that in general it is impossible to change the drawing of a
+ standard control (such as wxButton) and so you shouldn't attempt to handle
+ paint events for them as even if it might work on some platforms, this is
+ inherently not portable and won't work everywhere.
+
@beginEventTable{wxPaintEvent}
@event{EVT_PAINT(func)}
when calling wxEventLoopBase::YieldFor().
*/
virtual wxEventCategory GetEventCategory() const;
+
+ /**
+ Sets custom data payload.
+
+ The @a payload argument may be of any type that wxAny can handle
+ (i.e. pretty much anything). Note that T's copy constructor must be
+ thread-safe, i.e. create a copy that doesn't share anything with
+ the original (see Clone()).
+
+ @note This method is not available with Visual C++ 6.
+
+ @since 2.9.1
+
+ @see GetPayload(), wxAny
+ */
+ template<typename T>
+ void SetPayload(const T& payload);
+
+ /**
+ Get custom data payload.
+
+ Correct type is checked in debug builds.
+
+ @note This method is not available with Visual C++ 6.
+
+ @since 2.9.1
+
+ @see SetPayload(), wxAny
+ */
+ template<typename T>
+ T GetPayload() const;
};
@beginEventTable{wxCloseEvent}
@event{EVT_CLOSE(func)}
- Process a close event, supplying the member function.
+ Process a @c wxEVT_CLOSE_WINDOW command event, supplying the member function.
This event applies to wxFrame and wxDialog classes.
@event{EVT_QUERY_END_SESSION(func)}
- Process a query end session event, supplying the member function.
+ Process a @c wxEVT_QUERY_END_SESSION session event, supplying the member function.
This event can be handled in wxApp-derived class only.
@event{EVT_END_SESSION(func)}
- Process an end session event, supplying the member function.
+ Process a @c wxEVT_END_SESSION session event, supplying the member function.
This event can be handled in wxApp-derived class only.
@endEventTable
projects / wxWidgets.git / blobdiff