Add wxEvent::GetEventUserData() and improve user data documentation.

Provide a public and documented accessor for wxEvent::m_callbackUserData.

Also document better the user data semantics and how it can be used.

Closes #14748.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@72693 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

include/wx/event.h

@@ -930,6 +930,10 @@ public:
     int GetId() const { return m_id; }
     void SetId(int Id) { m_id = Id; }
 
+    // Returns the user data optionally associated with the event handler when
+    // using Connect() or Bind().
+    wxObject *GetEventUserData() const { return m_callbackUserData; }
+
     // Can instruct event processor that we wish to ignore this event
     // (treat as if the event table entry had not been found): this must be done
     // to allow the event processing by the base classes (calling event.Skip()

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.
     */
@@ -671,7 +684,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 +837,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 +876,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