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.
- This method is called from ProcessEvent(), please see the detailed
- description of the event processing logic there.
+ 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.
- It is @em not virtual and so may not be overridden but it does call
- virtual TryBefore() which may be overridden.
+ 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.
+
+ @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
when connecting an event generated by one object to a member
function of a different object. If it is omitted, @c this is used.
+ @beginWxPerlOnly
+ In wxPerl this function takes 4 arguments: @a id, @a lastid,
+ @a type, @a method; if @a method is undef, the handler is
+ disconnected.}
+ @endWxPerlOnly
+
@see Bind<>()
*/
void Connect(int id, int lastId, wxEventType eventType,
wxEVT_COMMAND_MENU_SELECTED,
wxCommandEventHandler(MyFrame::OnQuit) );
@endcode
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
*/
void Connect(int id, wxEventType eventType,
wxObjectEventFunction function,
This overload will connect the given event handler so that regardless of the
ID of the event source, the handler will be called.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
*/
void Connect(wxEventType eventType,
wxObjectEventFunction function,
Data associated with the event table entry.
@param eventSink
Object whose member function should be called.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
*/
bool Disconnect(wxEventType eventType,
wxObjectEventFunction function,
overload for more info.
This overload takes the additional @a id parameter.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
*/
bool Disconnect(int id = wxID_ANY,
wxEventType eventType = wxEVT_NULL,
overload for more info.
This overload takes an additional range of source IDs.
+
+ @beginWxPerlOnly
+ In wxPerl this function takes 3 arguments: @a id,
+ @a lastid, @a type.
+ @endWxPerlOnly
*/
bool Disconnect(int id, int lastId,
wxEventType eventType,
@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);
};
/// home and end keys, on and off numeric keypads
WXK_CATEGORY_JUMP,
- /// tab key
+ /// tab key, on and off numeric keypads
WXK_CATEGORY_TAB,
/// backspace and delete keys, on and off numeric keypads
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)}
@event{EVT_TOOL_RANGE(id1, id2, func)}
Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of identifiers. Pass the ids of the tools.
@event{EVT_TOOL_RCLICKED(id, func)}
- Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool.
+ Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool. (Not available on wxOSX.)
@event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}
- Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools.
+ Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools. (Not available on wxOSX.)
@event{EVT_TOOL_ENTER(id, func)}
Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself.
The value of wxCommandEvent::GetSelection() is the tool id, or -1 if the mouse cursor
- has moved off a tool.
+ has moved off a tool. (Not available on wxOSX.)
@event{EVT_COMMAND_LEFT_CLICK(id, func)}
Process a @c wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (wxMSW only).
@event{EVT_COMMAND_LEFT_DCLICK(id, 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
You may wish to use this for frames to resize their child windows as appropriate.
- Note that the size passed is of the whole window: call wxWindow::GetClientSize
+ Note that the size passed is of the whole window: call wxWindow::GetClientSize()
for the area which may be used by the application.
When a window is resized, usually only a small part of the window is damaged
/**
Returns the entire size of the window generating the size change event.
+
+ This is the new total size of the window, i.e. the same size as would
+ be returned by wxWindow::GetSize() if it were called now. Use
+ wxWindow::GetClientSize() if you catch this event in a top level window
+ such as wxFrame to find the size available for the window contents.
*/
wxSize GetSize() const;
};
projects / wxWidgets.git / blobdiff