X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ecad27577fd4e949d8e3a271d32f685b42972d57..0f57172b936f38881051c49f1e79a4465b812b03:/interface/wx/event.h diff --git a/interface/wx/event.h b/interface/wx/event.h index 73f66d5fe9..3aae72f4a1 100644 --- a/interface/wx/event.h +++ b/interface/wx/event.h @@ -159,6 +159,19 @@ public: */ int GetId() const; + /** + Return the user data associated with a dynamically connected event handler. + + wxEvtHandler::Connect() and wxEvtHandler::Bind() allow associating + optional @c userData pointer with the handler and this method returns + the value of this pointer. + + The returned pointer is owned by wxWidgets and must not be deleted. + + @since 2.9.5 + */ + wxObject *GetEventUserData() const; + /** Returns @true if the event handler should be skipped, @false otherwise. */ @@ -464,6 +477,53 @@ public: */ virtual void AddPendingEvent(const wxEvent& event); + /** + Asynchronously call the given method. + + Calling this function on an object schedules an asynchronous call to + the method specified as CallAfter() argument at a (slightly) later + time. This is useful when processing some events as certain actions + typically can't be performed inside their handlers, e.g. you shouldn't + show a modal dialog from a mouse click event handler as this would + break the mouse capture state -- but you can call a method showing + this message dialog after the current event handler completes. + + The method being called must be the method of the object on which + CallAfter() itself is called. + + Notice that it is safe to use CallAfter() from other, non-GUI, + threads, but that the method will be always called in the main, GUI, + thread context. + + Example of use: + @code + class MyFrame : public wxFrame { + void OnClick(wxMouseEvent& event) { + CallAfter(&MyFrame::ShowPosition, event.GetPosition()); + } + + void ShowPosition(const wxPoint& pos) { + if ( wxMessageBox( + wxString::Format("Perform click at (%d, %d)?", + pos.x, pos.y), "", wxYES_NO) == wxYES ) + { + ... do take this click into account ... + } + } + }; + @endcode + + @param method The method to call. + @param x1 The (optional) first parameter to pass to the method. + @param x2 The (optional) second parameter to pass to the method. + + Note that currently only up to 2 arguments can be passed. + + @since 2.9.5 + */ + template + void CallAfter(void (T::*method)(T1, ...), T1 x1, ...); + /** Processes an event, searching event tables and calling zero or more suitable event handler function(s). @@ -671,7 +731,11 @@ public: be explicitly converted to the correct type which can be done using a macro called @c wxFooEventHandler for the handler for any @c wxFooEvent. @param userData - Data to be associated with the event table entry. + Optional data to be associated with the event table entry. + wxWidgets will take ownership of this pointer, i.e. it will be + destroyed when the event handler is disconnected or at the program + termination. This pointer can be retrieved using + wxEvent::GetEventUserData() later. @param eventSink Object whose member function should be called. It must be specified when connecting an event generated by one object to a member @@ -820,7 +884,11 @@ public: The last ID of the identifier range to be associated with the event handler. @param userData - Data to be associated with the event table entry. + Optional data to be associated with the event table entry. + wxWidgets will take ownership of this pointer, i.e. it will be + destroyed when the event handler is disconnected or at the program + termination. This pointer can be retrieved using + wxEvent::GetEventUserData() later. @see @ref overview_cpp_rtti_disabled @@ -855,7 +923,11 @@ public: The last ID of the identifier range to be associated with the event handler. @param userData - Data to be associated with the event table entry. + Optional data to be associated with the event table entry. + wxWidgets will take ownership of this pointer, i.e. it will be + destroyed when the event handler is disconnected or at the program + termination. This pointer can be retrieved using + wxEvent::GetEventUserData() later. @see @ref overview_cpp_rtti_disabled @@ -2861,11 +2933,15 @@ public: means that the event originated from a keyboard context button event, and you should compute a suitable position yourself, for example by calling wxGetMousePosition(). - When a keyboard context menu button is pressed on Windows, a right-click event - with default position is sent first, and if this event is not processed, the - context menu event is sent. So if you process mouse events and you find your - context menu event handler is not being called, you could call wxEvent::Skip() - for mouse right-down events. + Notice that the exact sequence of mouse events is different across the + platforms. For example, under MSW the context menu event is generated after + @c EVT_RIGHT_UP event and only if it was not handled but under GTK the + context menu event is generated after @c EVT_RIGHT_DOWN event. This is + correct in the sense that it ensures that the context menu is shown + according to the current platform UI conventions and also means that you + must not handle (or call wxEvent::Skip() in your handler if you do have + one) neither right mouse down nor right mouse up event if you plan on + handling @c EVT_CONTEXT_MENU event. @beginEventTable{wxContextMenuEvent} @event{EVT_CONTEXT_MENU(func)}