GetTmpDefaultItem

[wxWidgets.git] / wxPython / src / _event.i

diff --git a/wxPython/src/_event.i b/wxPython/src/_event.i
index d8443aef031999d955fcc4dd85ee26dd94241e1e..979fbf16049de7adcd1e937fedcf9b28a258f1fd 100644 (file)
--- a/wxPython/src/_event.i
+++ b/wxPython/src/_event.i
@@ -99,8 +99,16 @@ wxEventType wxNewEventType();
 %constant wxEventType wxEVT_NAVIGATION_KEY;
 %constant wxEventType wxEVT_KEY_DOWN;
 %constant wxEventType wxEVT_KEY_UP;
 %constant wxEventType wxEVT_NAVIGATION_KEY;
 %constant wxEventType wxEVT_KEY_DOWN;
 %constant wxEventType wxEVT_KEY_UP;

+
+%{
+#if ! wxUSE_HOTKEY
+#define wxEVT_HOTKEY -9999
+#endif
+%}
+

 %constant wxEventType wxEVT_HOTKEY;
 %constant wxEventType wxEVT_HOTKEY;

-    
+
+

 // Set cursor event
 %constant wxEventType wxEVT_SET_CURSOR;
 
 // Set cursor event
 %constant wxEventType wxEVT_SET_CURSOR;
 


@@ -113,7 +121,9 @@ wxEventType wxNewEventType();
 %constant wxEventType wxEVT_SCROLL_PAGEDOWN;
 %constant wxEventType wxEVT_SCROLL_THUMBTRACK;
 %constant wxEventType wxEVT_SCROLL_THUMBRELEASE;
 %constant wxEventType wxEVT_SCROLL_PAGEDOWN;
 %constant wxEventType wxEVT_SCROLL_THUMBTRACK;
 %constant wxEventType wxEVT_SCROLL_THUMBRELEASE;

-%constant wxEventType wxEVT_SCROLL_ENDSCROLL;
+%constant wxEventType wxEVT_SCROLL_CHANGED;
+%pythoncode { wxEVT_SCROLL_ENDSCROLL = wxEVT_SCROLL_CHANGED }
+

 
 // Scroll events from wxWindow
 %constant wxEventType wxEVT_SCROLLWIN_TOP;
 
 // Scroll events from wxWindow
 %constant wxEventType wxEVT_SCROLLWIN_TOP;


@@ -132,7 +142,6 @@ wxEventType wxNewEventType();
 %constant wxEventType wxEVT_END_SESSION;
 %constant wxEventType wxEVT_QUERY_END_SESSION;
 %constant wxEventType wxEVT_ACTIVATE_APP;
 %constant wxEventType wxEVT_END_SESSION;
 %constant wxEventType wxEVT_QUERY_END_SESSION;
 %constant wxEventType wxEVT_ACTIVATE_APP;

-%constant wxEventType wxEVT_POWER;

 %constant wxEventType wxEVT_ACTIVATE;
 %constant wxEventType wxEVT_CREATE;
 %constant wxEventType wxEVT_DESTROY;
 %constant wxEventType wxEVT_ACTIVATE;
 %constant wxEventType wxEVT_CREATE;
 %constant wxEventType wxEVT_DESTROY;


@@ -163,6 +172,12 @@ wxEventType wxNewEventType();
 %constant wxEventType wxEVT_UPDATE_UI;
 %constant wxEventType wxEVT_SIZING;
 %constant wxEventType wxEVT_MOVING;
 %constant wxEventType wxEVT_UPDATE_UI;
 %constant wxEventType wxEVT_SIZING;
 %constant wxEventType wxEVT_MOVING;

+%constant wxEventType wxEVT_HIBERNATE;
+
+%constant wxEventType wxEVT_COMMAND_TEXT_COPY;
+%constant wxEventType wxEVT_COMMAND_TEXT_CUT;
+%constant wxEventType wxEVT_COMMAND_TEXT_PASTE;
+

 
 // Generic command events
 // Note: a click is a higher-level event than button down/up
 
 // Generic command events
 // Note: a click is a higher-level event than button down/up


@@ -192,7 +207,7 @@ EVT_ERASE_BACKGROUND = wx.PyEventBinder( wxEVT_ERASE_BACKGROUND )
 EVT_CHAR = wx.PyEventBinder( wxEVT_CHAR )
 EVT_KEY_DOWN = wx.PyEventBinder( wxEVT_KEY_DOWN )
 EVT_KEY_UP = wx.PyEventBinder( wxEVT_KEY_UP )
 EVT_CHAR = wx.PyEventBinder( wxEVT_CHAR )
 EVT_KEY_DOWN = wx.PyEventBinder( wxEVT_KEY_DOWN )
 EVT_KEY_UP = wx.PyEventBinder( wxEVT_KEY_UP )

-EVT_HOTKEY = wx.PyEventBinder( wxEVT_HOTKEY, 1) 
+EVT_HOTKEY = wx.PyEventBinder( wxEVT_HOTKEY, 1)

 EVT_CHAR_HOOK = wx.PyEventBinder( wxEVT_CHAR_HOOK )
 EVT_MENU_OPEN = wx.PyEventBinder( wxEVT_MENU_OPEN )
 EVT_MENU_CLOSE = wx.PyEventBinder( wxEVT_MENU_CLOSE )
 EVT_CHAR_HOOK = wx.PyEventBinder( wxEVT_CHAR_HOOK )
 EVT_MENU_OPEN = wx.PyEventBinder( wxEVT_MENU_OPEN )
 EVT_MENU_CLOSE = wx.PyEventBinder( wxEVT_MENU_CLOSE )


@@ -203,6 +218,7 @@ EVT_KILL_FOCUS = wx.PyEventBinder( wxEVT_KILL_FOCUS )
 EVT_CHILD_FOCUS = wx.PyEventBinder( wxEVT_CHILD_FOCUS )
 EVT_ACTIVATE = wx.PyEventBinder( wxEVT_ACTIVATE )
 EVT_ACTIVATE_APP = wx.PyEventBinder( wxEVT_ACTIVATE_APP )
 EVT_CHILD_FOCUS = wx.PyEventBinder( wxEVT_CHILD_FOCUS )
 EVT_ACTIVATE = wx.PyEventBinder( wxEVT_ACTIVATE )
 EVT_ACTIVATE_APP = wx.PyEventBinder( wxEVT_ACTIVATE_APP )

+EVT_HIBERNATE = wx.PyEventBinder( wxEVT_HIBERNATE )

 EVT_END_SESSION = wx.PyEventBinder( wxEVT_END_SESSION )
 EVT_QUERY_END_SESSION = wx.PyEventBinder( wxEVT_QUERY_END_SESSION )
 EVT_DROP_FILES = wx.PyEventBinder( wxEVT_DROP_FILES )
 EVT_END_SESSION = wx.PyEventBinder( wxEVT_END_SESSION )
 EVT_QUERY_END_SESSION = wx.PyEventBinder( wxEVT_QUERY_END_SESSION )
 EVT_DROP_FILES = wx.PyEventBinder( wxEVT_DROP_FILES )


@@ -251,11 +267,11 @@ EVT_MOUSE_EVENTS = wx.PyEventBinder([ wxEVT_LEFT_DOWN,
 
 
 %# Scrolling from wxWindow (sent to wxScrolledWindow)
 
 
 %# Scrolling from wxWindow (sent to wxScrolledWindow)

-EVT_SCROLLWIN = wx.PyEventBinder([ wxEVT_SCROLLWIN_TOP, 
+EVT_SCROLLWIN = wx.PyEventBinder([ wxEVT_SCROLLWIN_TOP,

                                   wxEVT_SCROLLWIN_BOTTOM,
                                   wxEVT_SCROLLWIN_LINEUP,
                                   wxEVT_SCROLLWIN_LINEDOWN,
                                   wxEVT_SCROLLWIN_BOTTOM,
                                   wxEVT_SCROLLWIN_LINEUP,
                                   wxEVT_SCROLLWIN_LINEDOWN,

-                                  wxEVT_SCROLLWIN_PAGEUP, 
+                                  wxEVT_SCROLLWIN_PAGEUP,

                                   wxEVT_SCROLLWIN_PAGEDOWN,
                                   wxEVT_SCROLLWIN_THUMBTRACK,
                                   wxEVT_SCROLLWIN_THUMBRELEASE,
                                   wxEVT_SCROLLWIN_PAGEDOWN,
                                   wxEVT_SCROLLWIN_THUMBTRACK,
                                   wxEVT_SCROLLWIN_THUMBRELEASE,


@@ -270,16 +286,16 @@ EVT_SCROLLWIN_PAGEDOWN = wx.PyEventBinder( wxEVT_SCROLLWIN_PAGEDOWN )
 EVT_SCROLLWIN_THUMBTRACK = wx.PyEventBinder( wxEVT_SCROLLWIN_THUMBTRACK )
 EVT_SCROLLWIN_THUMBRELEASE = wx.PyEventBinder( wxEVT_SCROLLWIN_THUMBRELEASE )
 
 EVT_SCROLLWIN_THUMBTRACK = wx.PyEventBinder( wxEVT_SCROLLWIN_THUMBTRACK )
 EVT_SCROLLWIN_THUMBRELEASE = wx.PyEventBinder( wxEVT_SCROLLWIN_THUMBRELEASE )
 

-%# Scrolling from wxSlider and wxScrollBar
-EVT_SCROLL = wx.PyEventBinder([ wxEVT_SCROLL_TOP, 
-                               wxEVT_SCROLL_BOTTOM, 
-                               wxEVT_SCROLL_LINEUP, 
-                               wxEVT_SCROLL_LINEDOWN, 
-                               wxEVT_SCROLL_PAGEUP, 
-                               wxEVT_SCROLL_PAGEDOWN, 
-                               wxEVT_SCROLL_THUMBTRACK, 
-                               wxEVT_SCROLL_THUMBRELEASE, 
-                               wxEVT_SCROLL_ENDSCROLL,
+%# Scrolling from wx.Slider and wx.ScrollBar
+EVT_SCROLL = wx.PyEventBinder([ wxEVT_SCROLL_TOP,
+                               wxEVT_SCROLL_BOTTOM,
+                               wxEVT_SCROLL_LINEUP,
+                               wxEVT_SCROLL_LINEDOWN,
+                               wxEVT_SCROLL_PAGEUP,
+                               wxEVT_SCROLL_PAGEDOWN,
+                               wxEVT_SCROLL_THUMBTRACK,
+                               wxEVT_SCROLL_THUMBRELEASE,
+                               wxEVT_SCROLL_CHANGED,

                                ])
 
 EVT_SCROLL_TOP = wx.PyEventBinder( wxEVT_SCROLL_TOP )
                                ])
 
 EVT_SCROLL_TOP = wx.PyEventBinder( wxEVT_SCROLL_TOP )


@@ -290,18 +306,19 @@ EVT_SCROLL_PAGEUP = wx.PyEventBinder( wxEVT_SCROLL_PAGEUP )
 EVT_SCROLL_PAGEDOWN = wx.PyEventBinder( wxEVT_SCROLL_PAGEDOWN )
 EVT_SCROLL_THUMBTRACK = wx.PyEventBinder( wxEVT_SCROLL_THUMBTRACK )
 EVT_SCROLL_THUMBRELEASE = wx.PyEventBinder( wxEVT_SCROLL_THUMBRELEASE )
 EVT_SCROLL_PAGEDOWN = wx.PyEventBinder( wxEVT_SCROLL_PAGEDOWN )
 EVT_SCROLL_THUMBTRACK = wx.PyEventBinder( wxEVT_SCROLL_THUMBTRACK )
 EVT_SCROLL_THUMBRELEASE = wx.PyEventBinder( wxEVT_SCROLL_THUMBRELEASE )

-EVT_SCROLL_ENDSCROLL = wx.PyEventBinder( wxEVT_SCROLL_ENDSCROLL )
-
-%# Scrolling from wxSlider and wxScrollBar, with an id
-EVT_COMMAND_SCROLL = wx.PyEventBinder([ wxEVT_SCROLL_TOP, 
-                                       wxEVT_SCROLL_BOTTOM, 
-                                       wxEVT_SCROLL_LINEUP, 
-                                       wxEVT_SCROLL_LINEDOWN, 
-                                       wxEVT_SCROLL_PAGEUP, 
-                                       wxEVT_SCROLL_PAGEDOWN, 
-                                       wxEVT_SCROLL_THUMBTRACK, 
+EVT_SCROLL_CHANGED = wx.PyEventBinder( wxEVT_SCROLL_CHANGED )
+EVT_SCROLL_ENDSCROLL = EVT_SCROLL_CHANGED
+
+%# Scrolling from wx.Slider and wx.ScrollBar, with an id
+EVT_COMMAND_SCROLL = wx.PyEventBinder([ wxEVT_SCROLL_TOP,
+                                       wxEVT_SCROLL_BOTTOM,
+                                       wxEVT_SCROLL_LINEUP,
+                                       wxEVT_SCROLL_LINEDOWN,
+                                       wxEVT_SCROLL_PAGEUP,
+                                       wxEVT_SCROLL_PAGEDOWN,
+                                       wxEVT_SCROLL_THUMBTRACK,

                                        wxEVT_SCROLL_THUMBRELEASE,
                                        wxEVT_SCROLL_THUMBRELEASE,

-                                       wxEVT_SCROLL_ENDSCROLL,
+                                       wxEVT_SCROLL_CHANGED,

                                        ], 1)
 
 EVT_COMMAND_SCROLL_TOP = wx.PyEventBinder( wxEVT_SCROLL_TOP, 1)
                                        ], 1)
 
 EVT_COMMAND_SCROLL_TOP = wx.PyEventBinder( wxEVT_SCROLL_TOP, 1)


@@ -312,7 +329,8 @@ EVT_COMMAND_SCROLL_PAGEUP = wx.PyEventBinder( wxEVT_SCROLL_PAGEUP, 1)
 EVT_COMMAND_SCROLL_PAGEDOWN = wx.PyEventBinder( wxEVT_SCROLL_PAGEDOWN, 1)
 EVT_COMMAND_SCROLL_THUMBTRACK = wx.PyEventBinder( wxEVT_SCROLL_THUMBTRACK, 1)
 EVT_COMMAND_SCROLL_THUMBRELEASE = wx.PyEventBinder( wxEVT_SCROLL_THUMBRELEASE, 1)
 EVT_COMMAND_SCROLL_PAGEDOWN = wx.PyEventBinder( wxEVT_SCROLL_PAGEDOWN, 1)
 EVT_COMMAND_SCROLL_THUMBTRACK = wx.PyEventBinder( wxEVT_SCROLL_THUMBTRACK, 1)
 EVT_COMMAND_SCROLL_THUMBRELEASE = wx.PyEventBinder( wxEVT_SCROLL_THUMBRELEASE, 1)

-EVT_COMMAND_SCROLL_ENDSCROLL = wx.PyEventBinder( wxEVT_SCROLL_ENDSCROLL, 1)
+EVT_COMMAND_SCROLL_CHANGED = wx.PyEventBinder( wxEVT_SCROLL_CHANGED, 1)
+EVT_COMMAND_SCROLL_ENDSCROLL = EVT_COMMAND_SCROLL_CHANGED

 
 EVT_BUTTON = wx.PyEventBinder( wxEVT_COMMAND_BUTTON_CLICKED, 1)
 EVT_CHECKBOX = wx.PyEventBinder( wxEVT_COMMAND_CHECKBOX_CLICKED, 1)
 
 EVT_BUTTON = wx.PyEventBinder( wxEVT_COMMAND_BUTTON_CLICKED, 1)
 EVT_CHECKBOX = wx.PyEventBinder( wxEVT_COMMAND_CHECKBOX_CLICKED, 1)


@@ -351,46 +369,105 @@ EVT_UPDATE_UI_RANGE = wx.PyEventBinder( wxEVT_UPDATE_UI, 2)
 
 EVT_CONTEXT_MENU = wx.PyEventBinder( wxEVT_CONTEXT_MENU )
 
 
 EVT_CONTEXT_MENU = wx.PyEventBinder( wxEVT_CONTEXT_MENU )
 

+EVT_TEXT_CUT   =  wx.PyEventBinder( wxEVT_COMMAND_TEXT_CUT )
+EVT_TEXT_COPY  =  wx.PyEventBinder( wxEVT_COMMAND_TEXT_COPY )
+EVT_TEXT_PASTE =  wx.PyEventBinder( wxEVT_COMMAND_TEXT_PASTE )

 
 }
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 
 }
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxEvent,
+"An event is a structure holding information about an event passed to a
+callback or member function. wx.Event is an abstract base class for
+other event classes", "");
+

 class wxEvent : public wxObject {
 public:
     // wxEvent(int winid = 0, wxEventType commandType = wxEVT_NULL);     // *** This class is now an ABC
     ~wxEvent();
 
 class wxEvent : public wxObject {
 public:
     // wxEvent(int winid = 0, wxEventType commandType = wxEVT_NULL);     // *** This class is now an ABC
     ~wxEvent();
 

-    void SetEventType(wxEventType typ);
-    wxEventType GetEventType() const;
-    wxObject *GetEventObject() const;
-    void SetEventObject(wxObject *obj);
+    DocDeclStr(
+        void , SetEventType(wxEventType typ),
+        "Sets the specific type of the event.", "");
+
+    DocDeclStr(
+        wxEventType , GetEventType() const,
+        "Returns the identifier of the given event type, such as
+``wxEVT_COMMAND_BUTTON_CLICKED``.", "");
+
+    DocDeclStr(
+        wxObject *, GetEventObject() const,
+        "Returns the object (usually a window) associated with the event, if
+any.", "");
+
+    DocDeclStr(
+        void , SetEventObject(wxObject *obj),
+        "Sets the originating object, or in other words, obj is normally the
+object that is sending the event.", "");
+

     long GetTimestamp() const;
     void SetTimestamp(long ts = 0);
     long GetTimestamp() const;
     void SetTimestamp(long ts = 0);

-    int GetId() const;
-    void SetId(int Id);

 
 

+    DocDeclStr(
+        int  , GetId() const,
+        "Returns the identifier associated with this event, such as a button
+command id.", "");
+
+    DocDeclStr(
+        void , SetId(int Id),
+        "Set's the ID for the event.  This is usually the ID of the window that
+is sending the event, but it can also be a command id from a menu
+item, etc.", "");
+
+
+
+    DocDeclStr(
+        bool , IsCommandEvent() const,
+        "Returns true if the event is or is derived from `wx.CommandEvent` else
+it returns false. Note: Exists only for optimization purposes.", "");
+
+
+    DocDeclStr(
+        void , Skip(bool skip = true),
+        "Called by an event handler, it controls whether additional event
+handlers bound to this event will be called after the current event
+handler returns.  Skip(false) (the default setting) will prevent
+additional event handlers from being called and control will be
+returned to the sender of the event immediately after the current
+handler has finished.  Skip(True) will cause the event processing
+system to continue searching for a handler function for this event.
+", "");

 
 

-    bool IsCommandEvent() const;
+    DocDeclStr(
+        bool , GetSkipped() const,
+        "Returns true if the event handler should be skipped, false otherwise.
+:see: `Skip`", "");

 
 

-    // 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()
-    // is the analog of calling the base class verstion of a virtual function)
-    void Skip(bool skip = True);
-    bool GetSkipped() const;

 
 

-    // Determine if this event should be propagating to the parent window.
-    bool ShouldPropagate() const;
+    DocDeclStr(
+        bool , ShouldPropagate() const,
+        "Test if this event should be propagated to the parent window or not,
+i.e. if the propagation level is currently greater than 0.", "");
+

 
     // Stop an event from propagating to its parent window, returns the old
     // propagation level value
 
     // Stop an event from propagating to its parent window, returns the old
     // propagation level value

-    int StopPropagation();
+    DocDeclStr(
+        int , StopPropagation(),
+        "Stop the event from propagating to its parent window.  Returns the old
+propagation level value which may be later passed to
+`ResumePropagation` to allow propagating the event again.", "");
+
+
+    DocDeclStr(
+        void , ResumePropagation(int propagationLevel),
+        "Resume the event propagation by restoring the propagation level.  (For
+example, you can use the value returned by an earlier call to
+`StopPropagation`.)
+", "");

 
 

-    // Resume the event propagation by restoring the propagation level
-    // (returned by StopPropagation())
-    void ResumePropagation(int propagationLevel);

 
     // this function is used to create a copy of the event polymorphically and
     // all derived classes must implement it because otherwise wxPostEvent()
 
     // this function is used to create a copy of the event polymorphically and
     // all derived classes must implement it because otherwise wxPostEvent()


@@ -402,7 +479,10 @@ public:
 //---------------------------------------------------------------------------
 %newgroup;
 
 //---------------------------------------------------------------------------
 %newgroup;
 

-// Helper class to temporarily change an event not to propagate.
+DocStr(wxPropagationDisabler,
+"Helper class to temporarily change an event not to propagate.  Simply
+create an instance of this class and then whe it is destroyed the
+propogation of the event will be restored.", "");

 class  wxPropagationDisabler
 {
 public:
 class  wxPropagationDisabler
 {
 public:


@@ -411,7 +491,10 @@ public:
 };
 
 
 };
 
 

-// Another one to temporarily lower propagation level.
+DocStr( wxPropagateOnce,
+"A helper class that will temporarily lower propagation level of an
+event.  Simply create an instance of this class and then whe it is
+destroyed the propogation of the event will be restored.", "");

 class  wxPropagateOnce
 {
 public:
 class  wxPropagateOnce
 {
 public:


@@ -422,6 +505,11 @@ public:
 //---------------------------------------------------------------------------
 %newgroup;
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxCommandEvent,
+"This event class contains information about command events, which
+originate from a variety of simple controls, as well as menus and
+toolbars.", "");
+

 class wxCommandEvent : public wxEvent
 {
 public:
 class wxCommandEvent : public wxEvent
 {
 public:


@@ -436,26 +524,80 @@ public:
 //     void SetClientObject(wxClientData* clientObject) { m_clientObject = clientObject; }
 //     void *GetClientObject() const { return m_clientObject; }
 
 //     void SetClientObject(wxClientData* clientObject) { m_clientObject = clientObject; }
 //     void *GetClientObject() const { return m_clientObject; }
 

-    
-    // Get listbox selection if single-choice
-    int GetSelection() const;

 
 

-    // Set/Get listbox/choice selection string
+    DocDeclStr(
+        int , GetSelection() const,
+        "Returns item index for a listbox or choice selection event (not valid
+for a deselection).", "");
+
+

     void SetString(const wxString& s);
     void SetString(const wxString& s);

-    wxString GetString() const;
+    DocDeclStr(
+        wxString , GetString() const,
+        "Returns item string for a listbox or choice selection event (not valid
+for a deselection).", "");
+
+
+    DocDeclStr(
+        bool , IsChecked() const,
+        "This method can be used with checkbox and menu events: for the
+checkboxes, the method returns true for a selection event and false
+for a deselection one. For the menu events, this method indicates if
+the menu item just has become checked or unchecked (and thus only
+makes sense for checkable menu items).", "");

 
 

-    // Get checkbox value
-    bool IsChecked() const;

     %pythoncode { Checked = IsChecked }
     %pythoncode { Checked = IsChecked }

-    
-    // True if the listbox event was a selection.
-    bool IsSelection() const;
+
+    DocDeclStr(
+        bool , IsSelection() const,
+        "For a listbox or similar event, returns true if it is a selection,
+false if it is a deselection.", "");
+

 
     void SetExtraLong(long extraLong);
 
     void SetExtraLong(long extraLong);

-    long GetExtraLong() const;
+    DocDeclStr(
+        long , GetExtraLong() const,
+        "Returns extra information dependant on the event objects type. If the
+event comes from a listbox selection, it is a boolean determining
+whether the event was a selection (true) or a deselection (false). A
+listbox deselection only occurs for multiple-selection boxes, and in
+this case the index and string values are indeterminate and the
+listbox must be examined by the application.", "");
+

 
     void SetInt(int i);
 
     void SetInt(int i);

-    long GetInt() const;
+    DocDeclStr(
+        int , GetInt() const,
+        "Returns the integer identifier corresponding to a listbox, choice or
+radiobox selection (only if the event was a selection, not a
+deselection), or a boolean value representing the value of a checkbox.", "");
+
+
+     %extend {
+        DocStr(GetClientData,
+               "Returns the client data object for a listbox or choice selection event, (if any.)", "");
+        PyObject* GetClientData() {
+            wxPyClientData* data = (wxPyClientData*)self->GetClientObject();
+            if (data) {
+                Py_INCREF(data->m_obj);
+                return data->m_obj;
+            } else {
+                Py_INCREF(Py_None);
+                return Py_None;
+            }
+        }
+
+        DocStr(SetClientData,
+               "Associate the given client data with the item at position n.", "");
+        void SetClientData(PyObject* clientData) {
+            wxPyClientData* data = new wxPyClientData(clientData);
+            self->SetClientObject(data);
+        }
+    }
+    %pythoncode {
+         GetClientObject = GetClientData
+         SetClientObject = SetClientData
+    }

 
     virtual wxEvent *Clone() const;
 
 
     virtual wxEvent *Clone() const;
 


@@ -464,37 +606,103 @@ public:
 //---------------------------------------------------------------------------
 %newgroup;
 
 //---------------------------------------------------------------------------
 %newgroup;
 

-// this class adds a possibility to react (from the user) code to a control
-// notification: allow or veto the operation being reported.
+DocStr(wxNotifyEvent,
+"An instance of this class (or one of its derived classes) is sent from
+a control when the control's state is being changed and the control
+allows that change to be prevented from happening.  The event handler
+can call `Veto` or `Allow` to tell the control what to do.", "");
+

 class wxNotifyEvent : public wxCommandEvent
 {
 public:
     wxNotifyEvent(wxEventType commandType = wxEVT_NULL, int winid = 0);
 
 class wxNotifyEvent : public wxCommandEvent
 {
 public:
     wxNotifyEvent(wxEventType commandType = wxEVT_NULL, int winid = 0);
 

-    // veto the operation (usually it's allowed by default)
-    void Veto();
+    DocDeclStr(
+        void , Veto(),
+        "Prevents the change announced by this event from happening.

 
 

-    // allow the operation if it was disabled by default
-    void Allow();
+It is in general a good idea to notify the user about the reasons for
+vetoing the change because otherwise the applications behaviour (which
+just refuses to do what the user wants) might be quite surprising.", "");
+
+
+    DocDeclStr(
+        void , Allow(),
+        "This is the opposite of `Veto`: it explicitly allows the event to be
+processed. For most events it is not necessary to call this method as
+the events are allowed anyhow but some are forbidden by default (this
+will be mentioned in the corresponding event description).", "");
+
+
+    DocDeclStr(
+        bool , IsAllowed(),
+        "Returns true if the change is allowed (`Veto` hasn't been called) or
+false otherwise (if it was).", "");

 
 

-    // for implementation code only: is the operation allowed?
-    bool IsAllowed();

 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 

-// Scroll event class, derived form wxCommandEvent. wxScrollEvents are
-// sent by wxSlider and wxScrollBar.
+DocStr(wxScrollEvent,
+"A scroll event holds information about events sent from stand-alone
+scrollbars and sliders. Note that scrolled windows do not send
+instnaces of this event class, but send the `wx.ScrollWinEvent`
+instead.", "
+
+Events
+-------
+    =======================     ==========================================
+    EVT_SCROLL                  Used to bind all scroll events
+    EVT_SCROLL_TOP              scroll-to-top events (minimum position)
+    EVT_SCROLL_BOTTOM           scroll-to-bottom events (maximum position)
+    EVT_SCROLL_LINEUP           line up events
+    EVT_SCROLL_LINEDOWN         line down events
+    EVT_SCROLL_PAGEUP           page up events
+    EVT_SCROLL_PAGEDOWN         page down events
+    EVT_SCROLL_THUMBTRACK       thumbtrack events (frequent events sent
+                                as the user drags the 'thumb')
+    EVT_SCROLL_THUMBRELEASE     thumb release events.
+    EVT_SCROLL_ENDSCROLL        End of scrolling
+    =======================     ==========================================
+
+Note
+------
+    The EVT_SCROLL_THUMBRELEASE event is only emitted when actually
+    dragging the thumb using the mouse and releasing it (This
+    EVT_SCROLL_THUMBRELEASE event is also followed by an
+    EVT_SCROLL_ENDSCROLL event).
+
+    The EVT_SCROLL_ENDSCROLL event also occurs when using the keyboard
+    to change the thumb position, and when clicking next to the thumb
+    (In all these cases the EVT_SCROLL_THUMBRELEASE event does not
+    happen).
+
+    In short, the EVT_SCROLL_ENDSCROLL event is triggered when
+    scrolling/ moving has finished. The only exception (unfortunately)
+    is that changing the thumb position using the mousewheel does give
+    a EVT_SCROLL_THUMBRELEASE event but NOT an EVT_SCROLL_ENDSCROLL
+    event.
+");
+

 class  wxScrollEvent : public wxCommandEvent
 {
 public:
 class  wxScrollEvent : public wxCommandEvent
 {
 public:

-    wxScrollEvent(wxEventType commandType = wxEVT_NULL,
-                  int winid = 0, int pos = 0, int orient = 0);
+    DocCtorStr(
+        wxScrollEvent(wxEventType commandType = wxEVT_NULL,
+                      int winid = 0, int pos = 0, int orient = 0),
+        "", "");
+
+    DocDeclStr(
+        int , GetOrientation() const,
+        "Returns wx.HORIZONTAL or wx.VERTICAL, depending on the orientation of
+the scrollbar.", "");
+
+    DocDeclStr(
+        int , GetPosition() const,
+        "Returns the position of the scrollbar.", "");

 
 

-    int GetOrientation() const;
-    int GetPosition() const;

     void SetOrientation(int orient);
     void SetPosition(int pos);
 };
     void SetOrientation(int orient);
     void SetPosition(int pos);
 };


@@ -503,16 +711,46 @@ public:
 //---------------------------------------------------------------------------
 %newgroup;
 
 //---------------------------------------------------------------------------
 %newgroup;
 

-// ScrollWin event class, derived fom wxEvent. wxScrollWinEvents
-// are sent by wxWindow.
+DocStr(wxScrollWinEvent,
+"A wx.ScrollWinEvent holds information about scrolling and is sent from
+scrolling windows.", "
+
+Events
+-------
+    ==========================     ==========================================
+    EVT_SCROLLWIN                  Used to bind all scrolled window scroll events
+    EVT_SCROLLWIN_TOP              scroll-to-top events (minimum position)
+    EVT_SCROLLWIN_BOTTOM           scroll-to-bottom events (maximum position)
+    EVT_SCROLLWIN_LINEUP           line up events
+    EVT_SCROLLWIN_LINEDOWN         line down events
+    EVT_SCROLLWIN_PAGEUP           page up events
+    EVT_SCROLLWIN_PAGEDOWN         page down events
+    EVT_SCROLLWIN_THUMBTRACK       thumbtrack events (frequent events sent
+                                   as the user drags the 'thumb')
+    EVT_SCROLLWIN_THUMBRELEASE     thumb release events.
+    EVT_SCROLLWIN_ENDSCROLL        End of scrolling
+    ==========================     ==========================================
+
+:see: `wx.ScrollEvent`
+");
+

 class wxScrollWinEvent : public wxEvent
 {
 public:
     wxScrollWinEvent(wxEventType commandType = wxEVT_NULL,
                      int pos = 0, int orient = 0);
 
 class wxScrollWinEvent : public wxEvent
 {
 public:
     wxScrollWinEvent(wxEventType commandType = wxEVT_NULL,
                      int pos = 0, int orient = 0);
 

-    int GetOrientation() const;
-    int GetPosition() const;
+    DocDeclStr(
+        int , GetOrientation() const,
+        "Returns wx.HORIZONTAL or wx.VERTICAL, depending on the orientation of
+the scrollbar.", "");
+
+    DocDeclStr(
+        int , GetPosition() const,
+        "Returns the position of the scrollbar for the thumb track and release
+events. Note that this field can't be used for the other events, you
+need to query the window itself for the current position in that case.", "");
+

     void SetOrientation(int orient);
     void SetPosition(int pos);
 };
     void SetOrientation(int orient);
     void SetPosition(int pos);
 };


@@ -520,6 +758,55 @@ public:
 //---------------------------------------------------------------------------
 %newgroup;
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+
+DocStr(wxMouseEvent,
+"This event class contains information about the events generated by
+the mouse: they include mouse buttons press and release events and
+mouse move events.
+
+All mouse events involving the buttons use ``wx.MOUSE_BTN_LEFT`` for
+the left mouse button, ``wx.MOUSE_BTN_MIDDLE`` for the middle one and
+``wx.MOUSE_BTN_RIGHT`` for the right one. Note that not all mice have
+a middle button so a portable application should avoid relying on the
+events from it.
+
+Note the difference between methods like `LeftDown` and `LeftIsDown`:
+the former returns true when the event corresponds to the left mouse
+button click while the latter returns true if the left mouse button is
+currently being pressed. For example, when the user is dragging the
+mouse you can use `LeftIsDown` to test whether the left mouse button
+is (still) depressed. Also, by convention, if `LeftDown` returns true,
+`LeftIsDown` will also return true in wxWidgets whatever the
+underlying GUI behaviour is (which is platform-dependent). The same
+applies, of course, to other mouse buttons as well.", "
+
+Events
+-------
+    ==================     ==============================================
+    EVT_LEFT_DOWN          Left mouse button down event. The handler
+                           of this event should normally call
+                           event.Skip() to allow the default processing
+                           to take place as otherwise the window under
+                           mouse wouldn't get the focus.
+    EVT_LEFT_UP            Left mouse button up event
+    EVT_LEFT_DCLICK        Left mouse button double click event
+    EVT_MIDDLE_DOWN        Middle mouse button down event
+    EVT_MIDDLE_UP          Middle mouse button up event
+    EVT_MIDDLE_DCLICK      Middle mouse button double click event
+    EVT_RIGHT_DOWN         Right mouse button down event
+    EVT_RIGHT_UP           Right mouse button up event
+    EVT_RIGHT_DCLICK       Right mouse button double click event
+    EVT_MOTION             Event sent when the mouse is moving
+    EVT_ENTER_WINDOW       Event sent when the mouse enters the
+                           boundaries of a window.
+    EVT_LEAVE_WINDOW       Sent when the mouse leaves the window's bounds
+    EVT_MOUSEWHEEL         Mouse scroll wheel event
+    EVT_MOUSE_EVENTS       Binds all mouse events at once.
+    ==================     ==============================================
+
+");
+
+

 // the symbolic names for the mouse buttons
 enum
 {
 // the symbolic names for the mouse buttons
 enum
 {


@@ -535,106 +822,257 @@ enum
 class  wxMouseEvent : public wxEvent
 {
 public:
 class  wxMouseEvent : public wxEvent
 {
 public:

-    wxMouseEvent(wxEventType mouseType = wxEVT_NULL);
+    DocCtorStr(
+        wxMouseEvent(wxEventType mouseType = wxEVT_NULL),
+"Constructs a wx.MouseEvent.  Valid event types are:
+
+    * wxEVT_ENTER_WINDOW
+    * wxEVT_LEAVE_WINDOW
+    * wxEVT_LEFT_DOWN
+    * wxEVT_LEFT_UP
+    * wxEVT_LEFT_DCLICK
+    * wxEVT_MIDDLE_DOWN
+    * wxEVT_MIDDLE_UP
+    * wxEVT_MIDDLE_DCLICK
+    * wxEVT_RIGHT_DOWN
+    * wxEVT_RIGHT_UP
+    * wxEVT_RIGHT_DCLICK
+    * wxEVT_MOTION
+    * wxEVT_MOUSEWHEEL ", "");
+
+
+    DocDeclStr(
+        bool , IsButton() const,
+        "Returns true if the event was a mouse button event (not necessarily a
+button down event - that may be tested using `ButtonDown`).", "");
+
+
+    DocDeclStr(
+        bool , ButtonDown(int but = wxMOUSE_BTN_ANY) const,
+        "If the argument is omitted, this returns true if the event was any
+mouse button down event. Otherwise the argument specifies which
+button-down event shold be checked for (see `Button` for the possible
+values).", "");
+
+
+    DocDeclStr(
+        bool , ButtonDClick(int but = wxMOUSE_BTN_ANY) const,
+        "If the argument is omitted, this returns true if the event was any
+mouse double click event. Otherwise the argument specifies which
+double click event to check for (see `Button` for the possible
+values).", "");
+
+
+    DocDeclStr(
+        bool , ButtonUp(int but = wxMOUSE_BTN_ANY) const,
+        "If the argument is omitted, this returns true if the event was any
+mouse button up event. Otherwise the argument specifies which button
+up event to check for (see `Button` for the possible values).", "");
+
+
+    DocDeclStr(
+        bool , Button(int button) const,
+        "Returns true if the identified mouse button is changing state. Valid
+values of button are:
+
+     ====================      =====================================
+     wx.MOUSE_BTN_LEFT         check if left button was pressed
+     wx.MOUSE_BTN_MIDDLE       check if middle button was pressed
+     wx.MOUSE_BTN_RIGHT        check if right button was pressed
+     wx.MOUSE_BTN_ANY          check if any button was pressed
+     ====================      =====================================
+", "");

 
 

-    // Was it a button event? (*doesn't* mean: is any button *down*?)
-    bool IsButton() const;

 
 

-    // Was it a down event from this (or any) button?
-    bool ButtonDown(int but = wxMOUSE_BTN_ANY) const;
+    // Was the given button in Down state?
+    bool ButtonIsDown(int but) const;

 
 

-    // Was it a dclick event from this (or any) button?
-    bool ButtonDClick(int but = wxMOUSE_BTN_ANY) const;
+    DocDeclStr(
+        int , GetButton() const,
+        "Returns the mouse button which generated this event or
+wx.MOUSE_BTN_NONE if no button is involved (for mouse move, enter or
+leave event, for example). Otherwise wx.MOUSE_BTN_LEFT is returned for
+the left button down, up and double click events, wx.MOUSE_BTN_MIDDLE
+and wx.MOUSE_BTN_RIGHT for the same events for the middle and the
+right buttons respectively.", "");

 
 

-    // Was it a up event from this (or any) button?
-    bool ButtonUp(int but = wxMOUSE_BTN_ANY) const;

 
 

-    // Was the given button changing state?
-    bool Button(int but) const;
+    DocDeclStr(
+        bool , ControlDown() const,
+        "Returns true if the control key was down at the time of the event.", "");

 
 

-    // Was the given button in Down state?
-    bool ButtonIsDown(int but) const;
+    DocDeclStr(
+        bool , MetaDown() const,
+        "Returns true if the Meta key was down at the time of the event.", "");
+
+
+    DocDeclStr(
+        bool , AltDown() const,
+        "Returns true if the Alt key was down at the time of the event.", "");
+
+    DocDeclStr(
+        bool , ShiftDown() const,
+        "Returns true if the Shift key was down at the time of the event.", "");
+
+
+    DocDeclStr(
+        bool , CmdDown() const,
+        "\"Cmd\" is a pseudo key which is the same as Control for PC and Unix
+platforms but the special \"Apple\" (a.k.a as \"Command\") key on
+Macs. It often makes sense to use it instead of, say, `ControlDown`
+because Cmd key is used for the same thing under Mac as Ctrl
+elsewhere. The Ctrl key still exists, it's just not used for this
+purpose. So for non-Mac platforms this is the same as `ControlDown`
+and Macs this is the same as `MetaDown`.", "");
+
+
+    DocDeclStr(
+        bool , LeftDown() const,
+        "Returns true if the left mouse button state changed to down.", "");
+
+    DocDeclStr(
+        bool , MiddleDown() const,
+        "Returns true if the middle mouse button state changed to down.", "");
+
+    DocDeclStr(
+        bool , RightDown() const,
+        "Returns true if the right mouse button state changed to down.", "");
+
+
+
+    DocDeclStr(
+        bool , LeftUp() const,
+        "Returns true if the left mouse button state changed to up.", "");
+
+    DocDeclStr(
+        bool , MiddleUp() const,
+        "Returns true if the middle mouse button state changed to up.", "");
+
+    DocDeclStr(
+        bool , RightUp() const,
+        "Returns true if the right mouse button state changed to up.", "");
+
+
+
+
+    DocDeclStr(
+        bool , LeftDClick() const,
+        "Returns true if the event was a left button double click.", "");

 
 

-    // Get the button which is changing state (wxMOUSE_BTN_NONE if none)
-    int GetButton() const;
+    DocDeclStr(
+        bool , MiddleDClick() const,
+        "Returns true if the event was a middle button double click.", "");

 
 

-    // Find state of shift/control keys
-    bool ControlDown() const;
-    bool MetaDown() const;
-    bool AltDown() const;
-    bool ShiftDown() const;
+    DocDeclStr(
+        bool , RightDClick() const,
+        "Returns true if the event was a right button double click.", "");

 
 

-    // Find which event was just generated
-    bool LeftDown() const;
-    bool MiddleDown() const;
-    bool RightDown() const;

 
 

-    bool LeftUp() const;
-    bool MiddleUp() const;
-    bool RightUp() const;

 
 

-    bool LeftDClick() const;
-    bool MiddleDClick() const;
-    bool RightDClick() const;
+    DocDeclStr(
+        bool , LeftIsDown(),
+        "Returns true if the left mouse button is currently down, independent
+of the current event type.

 
 

-    // Find the current state of the mouse buttons (regardless
-    // of current event type)
-    bool LeftIsDown();
-    bool MiddleIsDown();
-    bool RightIsDown();
+Please notice that it is not the same as LeftDown which returns true
+if the left mouse button was just pressed. Rather, it describes the
+state of the mouse button before the event happened.

 
 

-    // True if a button is down and the mouse is moving
-    bool Dragging() const;
+This event is usually used in the mouse event handlers which process
+\"move mouse\" messages to determine whether the user is (still)
+dragging the mouse.", "");

 
 

-    // True if the mouse is moving, and no button is down
-    bool Moving() const;
+    DocDeclStr(
+        bool , MiddleIsDown(),
+        "Returns true if the middle mouse button is currently down, independent
+of the current event type.", "");

 
 

-    // True if the mouse is just entering the window
-    bool Entering() const;
+    DocDeclStr(
+        bool , RightIsDown(),
+        "Returns true if the right mouse button is currently down, independent
+of the current event type.", "");
+
+
+
+    DocDeclStr(
+        bool , Dragging() const,
+        "Returns true if this was a dragging event (motion while a button is
+depressed).", "");
+
+
+    DocDeclStr(
+        bool , Moving() const,
+        "Returns true if this was a motion event and no mouse buttons were
+pressed. If any mouse button is held pressed, then this method returns
+false and Dragging returns true.", "");
+
+
+    DocDeclStr(
+        bool , Entering() const,
+        "Returns true if the mouse was entering the window.", "");
+
+
+    DocDeclStr(
+        bool , Leaving() const,
+        "Returns true if the mouse was leaving the window.", "");

 
 

-    // True if the mouse is just leaving the window
-    bool Leaving() const;

 
 
     DocStr(GetPosition,   // sets the docstring for both
 
 
     DocStr(GetPosition,   // sets the docstring for both

-           "Returns the position of the mouse in window coordinates when the event
-happened.", "");
+           "Returns the pixel position of the mouse in window coordinates when the
+event happened.", "");

     wxPoint GetPosition();
 
     DocDeclAName(
         void, GetPosition(long *OUTPUT, long *OUTPUT),
         "GetPositionTuple() -> (x,y)",
         GetPositionTuple);
     wxPoint GetPosition();
 
     DocDeclAName(
         void, GetPosition(long *OUTPUT, long *OUTPUT),
         "GetPositionTuple() -> (x,y)",
         GetPositionTuple);

-    
-    // Find the logical position of the event given the DC
-    wxPoint GetLogicalPosition(const wxDC& dc) const;

 
 

-    // Get X position
-    wxCoord GetX() const;
+    DocDeclStr(
+        wxPoint , GetLogicalPosition(const wxDC& dc) const,
+        "Returns the logical mouse position in pixels (i.e. translated
+according to the translation set for the DC, which usually indicates
+that the window has been scrolled).", "");

 
 

-    // Get Y position
-    wxCoord GetY() const;

 
 

-    // Get wheel rotation, positive or negative indicates direction of
-    // rotation.  Current devices all send an event when rotation is equal to
-    // +/-WheelDelta, but this allows for finer resolution devices to be
-    // created in the future.  Because of this you shouldn't assume that one
-    // event is equal to 1 line or whatever, but you should be able to either
-    // do partial line scrolling or wait until +/-WheelDelta rotation values
-    // have been accumulated before scrolling.
-    int GetWheelRotation() const;
+    DocDeclStr(
+        wxCoord , GetX() const,
+        "Returns X coordinate of the physical mouse event position.", "");

 
 

-    // Get wheel delta, normally 120.  This is the threshold for action to be
-    // taken, and one such action (for example, scrolling one increment)
-    // should occur for each delta.
-    int GetWheelDelta() const;
+    DocDeclStr(
+        wxCoord , GetY() const,
+        "Returns Y coordinate of the physical mouse event position.", "");

 
 

-    // Returns the configured number of lines (or whatever) to be scrolled per
-    // wheel action.  Defaults to one.
-    int GetLinesPerAction() const;

 
 

-    // Is the system set to do page scrolling?
-    bool IsPageScroll() const;
+    DocDeclStr(
+        int , GetWheelRotation() const,
+        "Get wheel rotation, positive or negative indicates direction of
+rotation. Current devices all send an event when rotation is equal to
++/-WheelDelta, but this allows for finer resolution devices to be
+created in the future. Because of this you shouldn't assume that one
+event is equal to 1 line or whatever, but you should be able to either
+do partial line scrolling or wait until +/-WheelDelta rotation values
+have been accumulated before scrolling.", "");
+
+
+    DocDeclStr(
+        int , GetWheelDelta() const,
+        "Get wheel delta, normally 120. This is the threshold for action to be
+taken, and one such action (for example, scrolling one increment)
+should occur for each delta.", "");
+
+
+    DocDeclStr(
+        int , GetLinesPerAction() const,
+        "Returns the configured number of lines (or whatever) to be scrolled
+per wheel action. Defaults to three.", "");
+
+
+    DocDeclStr(
+        bool , IsPageScroll() const,
+        "Returns true if the system has been setup to do page scrolling with
+the mouse wheel instead of line scrolling.", "");
+

 
 public:
     wxCoord m_x, m_y;
 
 public:
     wxCoord m_x, m_y;


@@ -657,17 +1095,42 @@ public:
 %newgroup;
 
 // Cursor set event
 %newgroup;
 
 // Cursor set event

+
+DocStr(wxSetCursorEvent,
+"A SetCursorEvent is generated when the mouse cursor is about to be set
+as a result of mouse motion. This event gives the application the
+chance to perform specific mouse cursor processing based on the
+current position of the mouse within the window. Use the `SetCursor`
+method to specify the cursor you want to be displayed.", "");
+

 class wxSetCursorEvent : public wxEvent
 {
 public:
 class wxSetCursorEvent : public wxEvent
 {
 public:

-    wxSetCursorEvent(wxCoord x = 0, wxCoord y = 0);
+    DocCtorStr(
+        wxSetCursorEvent(wxCoord x = 0, wxCoord y = 0),
+        "Construct a new `wx.SetCursorEvent`.", "");

 
 

-    wxCoord GetX() const;
-    wxCoord GetY() const;
+    DocDeclStr(
+        wxCoord , GetX() const,
+        "Returns the X coordinate of the mouse in client coordinates.", "");
+
+    DocDeclStr(
+        wxCoord , GetY() const,
+        "Returns the Y coordinate of the mouse in client coordinates.", "");
+
+
+    DocDeclStr(
+        void , SetCursor(const wxCursor& cursor),
+        "Sets the cursor associated with this event.", "");
+
+    DocDeclStr(
+        const wxCursor& , GetCursor() const,
+        "Returns a reference to the cursor specified by this event.", "");
+
+    DocDeclStr(
+        bool , HasCursor() const,
+        "Returns true if the cursor specified by this event is a valid cursor.", "");

 
 

-    void SetCursor(const wxCursor& cursor);
-    const wxCursor& GetCursor() const;
-    bool HasCursor() const;

 };
 
 //---------------------------------------------------------------------------
 };
 
 //---------------------------------------------------------------------------


@@ -675,45 +1138,228 @@ public:
 
 // Keyboard input event class
 
 
 // Keyboard input event class
 

+DocStr(wxKeyEvent,
+"This event class contains information about keypress and character
+events.  These events are only sent to the widget that currently has
+the keyboard focus.
+
+Notice that there are three different kinds of keyboard events in
+wxWidgets: key down and up events and char events. The difference
+between the first two is clear - the first corresponds to a key press
+and the second to a key release - otherwise they are identical. Just
+note that if the key is maintained in a pressed state you will
+typically get a lot of (automatically generated) down events but only
+one up so it is wrong to assume that there is one up event
+corresponding to each down one.
+
+Both key events provide untranslated key codes while the char event
+carries the translated one. The untranslated code for alphanumeric
+keys is always an upper case value. For the other keys it is one of
+WXK_XXX values from the keycodes table. The translated key is, in
+general, the character the user expects to appear as the result of the
+key combination when typing the text into a text entry zone, for
+example.
+
+A few examples to clarify this (all assume that CAPS LOCK is unpressed
+and the standard US keyboard): when the 'A' key is pressed, the key
+down event key code is equal to ASCII A == 65. But the char event key
+code is ASCII a == 97. On the other hand, if you press both SHIFT and
+'A' keys simultaneously , the key code in key down event will still be
+just 'A' while the char event key code parameter will now be 'A' as
+well.
+
+Although in this simple case it is clear that the correct key code
+could be found in the key down event handler by checking the value
+returned by `ShiftDown`, in general you should use EVT_CHAR for this
+as for non alphanumeric keys or non-US keyboard layouts the
+translation is keyboard-layout dependent and can only be done properly
+by the system itself.
+
+Another kind of translation is done when the control key is pressed:
+for example, for CTRL-A key press the key down event still carries the
+same key code 'A' as usual but the char event will have key code of 1,
+the ASCII value of this key combination.
+
+You may discover how the other keys on your system behave
+interactively by running the KeyEvents sample in the wxPython demo and
+pressing some keys while the blue box at the top has the keyboard
+focus.
+
+**Note**: If a key down event is caught and the event handler does not
+call event.Skip() then the coresponding char event will not
+happen. This is by design and enables the programs that handle both
+types of events to be a bit simpler.
+
+**Note for Windows programmers**: The key and char events in wxWidgets
+are similar to but slightly different from Windows WM_KEYDOWN and
+WM_CHAR events. In particular, Alt-x combination will generate a char
+event in wxWidgets (unless it is used as an accelerator).
+
+**Tip**: be sure to call event.Skip() for events that you don't
+process in key event function, otherwise menu shortcuts may cease to
+work under Windows.
+", "
+
+Events
+------
+    ==================     ==============================================
+    wx.EVT_KEY_DOWN        Sent when a keyboard key has been pressed
+    wx.EVT_KEY_UP          Sent when a keyboard key has been released
+    wx.EVT_CHAR            Sent for translated character events.
+    ==================     ==============================================
+
+
+Keycode Table
+-------------
+    ===========  ==============  ========  ====================  =================
+    WXK_BACK     WXK_EXECUTE     WXK_F1    WXK_NUMPAD_SPACE      WXK_WINDOWS_LEFT
+    WXK_TAB      WXK_SNAPSHOT    WXK_F2    WXK_NUMPAD_TAB        WXK_WINDOWS_RIGHT
+    WXK_RETURN   WXK_INSERT      WXK_F3    WXK_NUMPAD_ENTER      WXK_WINDOWS_MENU
+    WXK_ESCAPE   WXK_HELP        WXK_F4    WXK_NUMPAD_F1         WXK_SPECIAL1
+    WXK_SPACE    WXK_NUMPAD0     WXK_F5    WXK_NUMPAD_F2         WXK_SPECIAL2
+    WXK_DELETE   WXK_NUMPAD1     WXK_F6    WXK_NUMPAD_F3         WXK_SPECIAL3
+    WXK_LBUTTON  WXK_NUMPAD2     WXK_F7    WXK_NUMPAD_F4         WXK_SPECIAL4
+    WXK_RBUTTON  WXK_NUMPAD3     WXK_F8    WXK_NUMPAD_HOME       WXK_SPECIAL5
+    WXK_CANCEL   WXK_NUMPAD4     WXK_F9    WXK_NUMPAD_LEFT       WXK_SPECIAL6
+    WXK_MBUTTON  WXK_NUMPAD5     WXK_F10   WXK_NUMPAD_UP         WXK_SPECIAL7
+    WXK_CLEAR    WXK_NUMPAD6     WXK_F11   WXK_NUMPAD_RIGHT      WXK_SPECIAL8
+    WXK_SHIFT    WXK_NUMPAD7     WXK_F12   WXK_NUMPAD_DOWN       WXK_SPECIAL9
+    WXK_ALT      WXK_NUMPAD8     WXK_F13   WXK_NUMPAD_PRIOR      WXK_SPECIAL10
+    WXK_CONTROL  WXK_NUMPAD9     WXK_F14   WXK_NUMPAD_PAGEUP     WXK_SPECIAL11
+    WXK_MENU     WXK_MULTIPLY    WXK_F15   WXK_NUMPAD_NEXT       WXK_SPECIAL12
+    WXK_PAUSE    WXK_ADD         WXK_F16   WXK_NUMPAD_PAGEDOWN   WXK_SPECIAL13
+    WXK_CAPITAL  WXK_SEPARATOR   WXK_F17   WXK_NUMPAD_END        WXK_SPECIAL14
+    WXK_PRIOR    WXK_SUBTRACT    WXK_F18   WXK_NUMPAD_BEGIN      WXK_SPECIAL15
+    WXK_NEXT     WXK_DECIMAL     WXK_F19   WXK_NUMPAD_INSERT     WXK_SPECIAL16
+    WXK_END      WXK_DIVIDE      WXK_F20   WXK_NUMPAD_DELETE     WXK_SPECIAL17
+    WXK_HOME     WXK_NUMLOCK     WXK_F21   WXK_NUMPAD_EQUAL      WXK_SPECIAL18
+    WXK_LEFT     WXK_SCROLL      WXK_F22   WXK_NUMPAD_MULTIPLY   WXK_SPECIAL19
+    WXK_UP       WXK_PAGEUP      WXK_F23   WXK_NUMPAD_ADD        WXK_SPECIAL20
+    WXK_RIGHT    WXK_PAGEDOWN    WXK_F24   WXK_NUMPAD_SEPARATOR
+    WXK_DOWN                               WXK_NUMPAD_SUBTRACT
+    WXK_SELECT                             WXK_NUMPAD_DECIMAL
+    WXK_PRINT                              WXK_NUMPAD_DIVIDE
+    ===========  ==============  ========  ====================  =================
+");
+

 class wxKeyEvent : public wxEvent
 {
 public:
 class wxKeyEvent : public wxEvent
 {
 public:

-    wxKeyEvent(wxEventType keyType = wxEVT_NULL);
-
-    // Find state of shift/control keys
-    bool ControlDown() const;
-    bool MetaDown() const;
-    bool AltDown() const;
-    bool ShiftDown() const;
-
-    // exclude MetaDown() from HasModifiers() because NumLock under X is often
-    // configured as mod2 modifier, yet the key events even when it is pressed
-    // should be processed normally, not like Ctrl- or Alt-key
-    bool HasModifiers() const;
-
-    // get the key code: an ASCII7 char or an element of wxKeyCode enum
-    int GetKeyCode() const;
+    DocCtorStr(
+        wxKeyEvent(wxEventType eventType = wxEVT_NULL),
+        "Construct a new `wx.KeyEvent`.  Valid event types are:
+    * ", "");
+
+
+    DocDeclStr(
+        int, GetModifiers() const,
+        "Returns a bitmask of the current modifier settings.  Can be used to
+check if the key event has exactly the given modifiers without having
+to explicitly check that the other modifiers are not down.  For
+example::
+
+    if event.GetModifers() == wx.MOD_CONTROL:
+        DoSomething()
+", "");
+
+    DocDeclStr(
+        bool , ControlDown() const,
+        "Returns ``True`` if the Control key was down at the time of the event.", "");
+
+    DocDeclStr(
+        bool , MetaDown() const,
+        "Returns ``True`` if the Meta key was down at the time of the event.", "");
+
+    DocDeclStr(
+        bool , AltDown() const,
+        "Returns ``True`` if the Alt key was down at the time of the event.", "");
+
+    DocDeclStr(
+        bool , ShiftDown() const,
+        "Returns ``True`` if the Shift key was down at the time of the event.", "");
+
+
+    DocDeclStr(
+        bool , CmdDown() const,
+        "\"Cmd\" is a pseudo key which is the same as Control for PC and Unix
+platforms but the special \"Apple\" (a.k.a as \"Command\") key on
+Macs. It makes often sense to use it instead of, say, `ControlDown`
+because Cmd key is used for the same thing under Mac as Ctrl
+elsewhere. The Ctrl still exists, it's just not used for this
+purpose. So for non-Mac platforms this is the same as `ControlDown`
+and Macs this is the same as `MetaDown`.", "");
+
+
+
+    DocDeclStr(
+        bool , HasModifiers() const,
+        "Returns true if either CTRL or ALT keys was down at the time of the
+key event. Note that this function does not take into account neither
+SHIFT nor META key states (the reason for ignoring the latter is that
+it is common for NUMLOCK key to be configured as META under X but the
+key presses even while NUMLOCK is on should be still processed
+normally).", "");
+
+
+    DocDeclStr(
+        int , GetKeyCode() const,
+        "Returns the virtual key code. ASCII events return normal ASCII values,
+while non-ASCII events return values such as WXK_LEFT for the left
+cursor key. See `wx.KeyEvent` for a full list of the virtual key
+codes.
+
+Note that in Unicode build, the returned value is meaningful only if
+the user entered a character that can be represented in current
+locale's default charset. You can obtain the corresponding Unicode
+character using `GetUnicodeKey`.", "");

     %pythoncode { KeyCode = GetKeyCode }
 
     %pythoncode { KeyCode = GetKeyCode }
 

+

     %extend {
     %extend {

-        int GetUniChar() {
+        DocStr(
+            GetUnicodeKey,
+            "Returns the Unicode character corresponding to this key event.  This
+function is only meaningfule in a Unicode build of wxPython.", "");
+        int GetUnicodeKey() {

         %#if wxUSE_UNICODE
         %#if wxUSE_UNICODE

-            return self->m_uniChar;
+            return self->GetUnicodeKey();

         %#else
             return 0;
         %#endif
         }
     }
         %#else
             return 0;
         %#endif
         }
     }

-    
-    // get the raw key code (platform-dependent)
-    wxUint32 GetRawKeyCode() const;
+    %pythoncode { GetUniChar = GetUnicodeKey }
+
+    %extend {
+        DocStr(
+            SetUnicodeKey,
+            "Set the Unicode value of the key event, but only if this is a Unicode
+build of wxPython.", "");
+        void SetUnicodeKey(int uniChar) {
+            %#if wxUSE_UNICODE
+                self->m_uniChar = uniChar;
+            %#endif
+        }
+    }
+
+    DocDeclStr(
+        wxUint32 , GetRawKeyCode() const,
+        "Returns the raw key code for this event. This is a platform-dependent
+scan code which should only be used in advanced
+applications. Currently the raw key codes are not supported by all
+ports.", "");
+
+
+    DocDeclStr(
+        wxUint32 , GetRawKeyFlags() const,
+        "Returns the low level key flags for this event. The flags are
+platform-dependent and should only be used in advanced applications.
+Currently the raw key flags are not supported by all ports.", "");
+

 
 

-    // get the raw key flags (platform-dependent)
-    wxUint32 GetRawKeyFlags() const;

 
 

-    

     DocStr(GetPosition,   // sets the docstring for both
     DocStr(GetPosition,   // sets the docstring for both

-           "Find the position of the event.", "");
+           "Find the position of the event, if applicable.", "");

     wxPoint GetPosition();
 
     DocDeclAName(
     wxPoint GetPosition();
 
     DocDeclAName(


@@ -721,11 +1367,18 @@ public:
         "GetPositionTuple() -> (x,y)",
         GetPositionTuple);
 
         "GetPositionTuple() -> (x,y)",
         GetPositionTuple);
 

-    // Get X position
-    wxCoord GetX() const;

 
 

-    // Get Y position
-    wxCoord GetY() const;
+    DocDeclStr(
+        wxCoord , GetX() const,
+        "Returns the X position (in client coordinates) of the event, if
+applicable.", "");
+
+
+    DocDeclStr(
+        wxCoord , GetY() const,
+        "Returns the Y position (in client coordinates) of the event, if
+applicable.", "");
+

 
 public:
     wxCoord       m_x, m_y;
 
 public:
     wxCoord       m_x, m_y;


@@ -738,8 +1391,6 @@ public:
     bool          m_metaDown;
     bool          m_scanCode;
 
     bool          m_metaDown;
     bool          m_scanCode;
 

-    // these fields contain the platform-specific information about
-    // key that was pressed

     wxUint32      m_rawCode;
     wxUint32      m_rawFlags;
 };
     wxUint32      m_rawCode;
     wxUint32      m_rawFlags;
 };


@@ -748,14 +1399,39 @@ public:
 %newgroup;
 
 // Size event class
 %newgroup;
 
 // Size event class

+
+DocStr(wxSizeEvent,
+"A size event holds information about size change events.  The EVT_SIZE
+handler function will be called when the window it is bound to has
+been resized.
+
+Note that the size passed is of the whole window: call
+`wx.Window.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 and and that area is all that is in the update region for the
+next paint event. However, if your drawing depends on the size of the
+window, you may need to clear the DC explicitly and repaint the whole
+window. In which case, you may need to call `wx.Window.Refresh` to
+invalidate the entire window.
+", "");
+

 class wxSizeEvent : public wxEvent
 {
 public:
 class wxSizeEvent : public wxEvent
 {
 public:

-    wxSizeEvent(const wxSize& sz=wxDefaultSize, int winid = 0);
+    DocCtorStr(
+        wxSizeEvent(const wxSize& sz=wxDefaultSize, int winid = 0),
+        "Construct a new ``wx.SizeEvent``.", "");
+
+    DocDeclStr(
+        wxSize , GetSize() const,
+        "Returns the entire size of the window generating the size change
+event.", "");

 
 

-    wxSize GetSize() const;

     wxRect GetRect() const;
     void SetRect(wxRect rect);
     wxRect GetRect() const;
     void SetRect(wxRect rect);

+

     %extend {
         void SetSize(wxSize size) {
             self->m_size = size;
     %extend {
         void SetSize(wxSize size) {
             self->m_size = size;


@@ -764,40 +1440,62 @@ public:
 
 public:
     wxSize m_size;
 
 public:
     wxSize m_size;

-    wxRect m_rect; // Used for wxEVT_SIZING
+    wxRect m_rect;

 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 

-// Move event class
+DocStr(wxMoveEvent,
+"This event object is sent for EVT_MOVE event bindings when a window is
+moved to a new position.", "");
+

 class wxMoveEvent : public wxEvent
 {
 public:
 class wxMoveEvent : public wxEvent
 {
 public:

-    wxMoveEvent(const wxPoint& pos=wxDefaultPosition, int winid = 0);
+    DocCtorStr(
+        wxMoveEvent(const wxPoint& pos=wxDefaultPosition, int winid = 0),
+        "Constructor.", "");
+
+    DocDeclStr(
+        wxPoint , GetPosition() const,
+        "Returns the position of the window generating the move change event.", "");

 
 

-    wxPoint GetPosition() const;

     wxRect GetRect() const;
     wxRect GetRect() const;

-    void SetRect(wxRect rect);
-    %extend {
-        void SetPosition(wxPoint pos) {
-            self->m_pos = pos;
-        }
-    }
+    void SetRect(const wxRect& rect);
+    void SetPosition(const wxPoint& pos);

 
 

-    wxPoint m_pos;
-    wxRect m_rect;
+    %pythoncode {
+        m_pos =  property(GetPosition, SetPosition)
+        m_rect = property(GetRect, SetRect)
+    }

 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 

-// Paint event class
+DocStr(wxPaintEvent,
+"A paint event is sent when a window's contents needs to be repainted.
+Note that in an EVT_PAINT handler the application must *always* create
+a `wx.PaintDC` object, even if you do not use it.  Otherwise MS
+Windows assumes that the window has not been painted yet and will send
+the event again, causing endless refreshes.
+
+You can optimize painting by retrieving the rectangles that have been
+damaged using `wx.Window.GetUpdateRegion` and/or `wx.RegionIterator`,
+and only repainting these rectangles. The rectangles are in terms of
+the client area, and are unscrolled, so you will need to do some
+calculations using the current view position to obtain logical,
+scrolled units.
+", "");
+

 class wxPaintEvent : public wxEvent
 {
 public:
 class wxPaintEvent : public wxEvent
 {
 public:

-    wxPaintEvent(int Id = 0);
+    DocCtorStr(
+        wxPaintEvent(int Id = 0),
+        "", "");

 };
 
 
 };
 
 


@@ -810,110 +1508,301 @@ public:
 //---------------------------------------------------------------------------
 %newgroup;
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxEraseEvent,
+"An erase event is sent whenever the background of a window needs to be
+repainted.  To intercept this event use the EVT_ERASE_BACKGROUND event
+binder.  On some platforms, such as GTK+, this event is simulated
+(simply generated just before the paint event) and may cause flicker.
+
+To paint a custom background use the `GetDC` method and use the returned
+device context if it is not ``None``, otherwise create a temporary
+`wx.ClientDC` and draw on that.
+", "");
+

 class wxEraseEvent : public wxEvent
 {
 public:
 class wxEraseEvent : public wxEvent
 {
 public:

-    wxEraseEvent(int Id = 0, wxDC *dc = (wxDC *) NULL);
-
-    wxDC *GetDC() const;
+    DocCtorStr(
+        wxEraseEvent(int Id = 0, wxDC *dc = NULL),
+        "Constructor", "");
+
+    DocDeclStr(
+        wxDC *, GetDC() const,
+        "Returns the device context the event handler should draw upon.  If
+``None`` is returned then create a temporary `wx.ClientDC` and use
+that instead.", "");

 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxFocusEvent,
+"A focus event is sent when a window's focus changes. The window losing
+focus receives an EVT_KILL_FOCUS event while the window gaining it
+gets an EVT_SET_FOCUS event.
+
+Notice that the set focus event happens both when the user gives focus
+to the window (whether using the mouse or keyboard) and when it is
+done from the program itself using `wx.Window.SetFocus`.
+", "");
+

 class wxFocusEvent : public wxEvent
 {
 public:
 class wxFocusEvent : public wxEvent
 {
 public:

-    wxFocusEvent(wxEventType type = wxEVT_NULL, int winid = 0);
+    DocCtorStr(
+        wxFocusEvent(wxEventType type = wxEVT_NULL, int winid = 0),
+        "Constructor", "");
+
+    DocDeclStr(
+        wxWindow *, GetWindow() const,
+        "Returns the other window associated with this event, that is the
+window which had the focus before for the EVT_SET_FOCUS event and the
+window which is going to receive focus for the wxEVT_KILL_FOCUS event.
+
+Warning: the window returned may be None!", "");

 
 

-    // The window associated with this event is the window which had focus
-    // before for SET event and the window which will have focus for the KILL
-    // one. NB: it may be NULL in both cases!
-    wxWindow *GetWindow() const;

     void SetWindow(wxWindow *win);
 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 
     void SetWindow(wxWindow *win);
 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 

-// wxChildFocusEvent notifies the parent that a child has got the focus: unlike
-// wxFocusEvent it is propagated upwards the window chain
+DocStr(wxChildFocusEvent,
+"wx.ChildFocusEvent notifies the parent that a child has received the
+focus.  Unlike `wx.FocusEvent` it is propagated up the window
+heirarchy.", "");
+
+

 class wxChildFocusEvent : public wxCommandEvent
 {
 public:
 class wxChildFocusEvent : public wxCommandEvent
 {
 public:

-    wxChildFocusEvent(wxWindow *win = NULL);
+    DocCtorStr(
+        wxChildFocusEvent(wxWindow *win = NULL),
+        "Constructor", "");
+
+    DocDeclStr(
+        wxWindow *, GetWindow() const,
+        "The window which has just received the focus.", "");

 
 

-    wxWindow *GetWindow() const;

 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxActivateEvent,
+"An activate event is sent when a top-level window or the entire
+application is being activated or deactivated.
+
+A top-level window (a dialog or frame) receives an activate event when
+is being activated or deactivated. This is indicated visually by the
+title bar changing colour, and a subwindow gaining the keyboard focus.
+An application is activated or deactivated when one of its frames
+becomes activated, or a frame becomes inactivate resulting in all
+application frames being inactive.
+
+Please note that usually you should call event.Skip() in your handlers
+for these events so the default handlers will still be called, as not
+doing so can result in strange effects.
+", "
+
+Events
+-------
+    =======================     ==========================================
+    wx.EVT_ACTIVATE             Sent to a frame when it has been activated
+                                or deactivated.
+    wx.EVT_ACTIVATE_APP         Sent to the app object when its activation
+                                state changes.
+    =======================     ==========================================
+");
+
+

 class wxActivateEvent : public wxEvent
 {
 public:
 class wxActivateEvent : public wxEvent
 {
 public:

-    wxActivateEvent(wxEventType type = wxEVT_NULL, bool active = True, int Id = 0);
-    bool GetActive() const;
+    DocCtorStr(
+        wxActivateEvent(wxEventType type = wxEVT_NULL, bool active = true, int Id = 0),
+        "Constructor", "");
+
+    DocDeclStr(
+        bool , GetActive() const,
+        "Returns true if the application or window is being activated, false
+otherwise.", "");
+

 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxInitDialogEvent,
+"A wx.InitDialogEvent is sent as a dialog is being initialised, or for
+any window when `wx.Window.InitDialog` is called.  Handlers for this
+event can transfer data to the window, or anything else that should be
+done before the user begins editing the form. The default handler
+calls `wx.Window.TransferDataToWindow`.", "
+
+Events
+-------
+    =======================     ==========================================
+    wx.EVT_INIT_DIALOG          Binder for init dialog events.
+    =======================     ==========================================
+");
+

 class wxInitDialogEvent : public wxEvent
 {
 public:
 class wxInitDialogEvent : public wxEvent
 {
 public:

-    wxInitDialogEvent(int Id = 0);
+    DocCtorStr(
+        wxInitDialogEvent(int Id = 0),
+        "Constructor", "");

 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxMenuEvent,
+"This class is used for a variety of menu-related events.  Note that
+these do not include menu command events, which are handled by sending
+`wx.CommandEvent` objects.
+
+The default handler for wx.EVT_MENU_HIGHLIGHT displays menu item help
+text in the first field of the status bar.", "
+
+Events
+-------
+    =========================   ==========================================
+    wx.EVT_MENU_OPEN            A menu is about to be opened. On Windows,
+                                this is only sent once for each navigation
+                                of the menubar (up until all menus have closed).
+    wx.EVT_MENU_CLOSE           A menu has been just closed.
+    wx.EVT_MENU_HIGHLIGHT       Sent when the menu item with the specified id
+                                has been highlighted: used by default to show
+                                help prompts in the `wx.Frame`'s status bar.
+    wx.EVT_MENU_HIGHLIGHT_ALL   Can be used to catch the menu highlight
+                                event for all menu items.
+    =========================   ==========================================
+");
+

 class wxMenuEvent : public wxEvent
 {
 public:
 class wxMenuEvent : public wxEvent
 {
 public:

-    wxMenuEvent(wxEventType type = wxEVT_NULL, int winid = 0, wxMenu* menu = NULL);
-    
-    // only for wxEVT_MENU_HIGHLIGHT
-    int GetMenuId() const;
+    DocCtorStr(
+        wxMenuEvent(wxEventType type = wxEVT_NULL, int winid = 0, wxMenu* menu = NULL),
+        "Constructor", "");
+
+    DocDeclStr(
+        int , GetMenuId() const,
+        "Returns the menu identifier associated with the event. This method
+should be only used with the HIGHLIGHT events.", "");
+
+
+    DocDeclStr(
+        bool , IsPopup() const,
+        "Returns ``True`` if the menu which is being opened or closed is a
+popup menu, ``False`` if it is a normal one.  This method should only
+be used with the OPEN and CLOSE events.", "");

 
 

-    // only for wxEVT_MENU_OPEN/CLOSE
-    bool IsPopup() const;

 
 

-    // only for wxEVT_MENU_OPEN/CLOSE
-    wxMenu* GetMenu() const;
+    DocDeclStr(
+        wxMenu* , GetMenu() const,
+        "Returns the menu which is being opened or closed. This method should
+only be used with the OPEN and CLOSE events.", "");
+

 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 

-// Window close or session close event class
+DocStr(wxCloseEvent,
+"This event class contains information about window and session close
+events.
+
+The handler function for EVT_CLOSE is called when the user has tried
+to close a a frame or dialog box using the window manager controls or
+the system menu. It can also be invoked by the application itself
+programmatically, for example by calling the `wx.Window.Close`
+function.
+
+You should check whether the application is forcing the deletion of
+the window using `CanVeto`. If it returns ``False``, you must destroy
+the window using `wx.Window.Destroy`. If the return value is ``True``,
+it is up to you whether you respond by destroying the window or not.
+For example you may wish to display a message dialog prompting to save
+files or to cancel the close.
+
+If you don't destroy the window, you should call `Veto` to let the
+calling code know that you did not destroy the window. This allows the
+`wx.Window.Close` function to return ``True`` or ``False`` depending
+on whether the close instruction was honored or not.", "
+
+Events
+-------
+    =========================   ==========================================
+    wx.EVT_CLOSE                This event is sent to a top-level window
+                                when it has been requested to close either
+                                from the user or programatically.
+    wx.EVT_QUERY_END_SESSION    This event is sent to the `wx.App` when the
+                                system is about to be logged off, giving the
+                                app a chance to veto the shutdown.
+    wx.EVT_END_SESSION          This event is sent to the `wx.App` when the
+                                system is being logged off.
+    =========================   ==========================================
+");
+

 class wxCloseEvent : public wxEvent
 {
 public:
 class wxCloseEvent : public wxEvent
 {
 public:

-    wxCloseEvent(wxEventType type = wxEVT_NULL, int winid = 0);
-    
-    void SetLoggingOff(bool logOff);
-    bool GetLoggingOff() const;
-
-    void Veto(bool veto = True);
-    void SetCanVeto(bool canVeto);
-    
-    bool CanVeto() const;
+    DocCtorStr(
+        wxCloseEvent(wxEventType type = wxEVT_NULL, int winid = 0),
+        "Constructor.", "");
+
+    DocDeclStr(
+        void , SetLoggingOff(bool logOff),
+        "Sets the 'logging off' flag.", "");
+
+    DocDeclStr(
+        bool , GetLoggingOff() const,
+        "Returns ``True`` if the user is logging off or ``False`` if the
+system is shutting down. This method can only be called for end
+session and query end session events, it doesn't make sense for close
+window event.", "");
+
+
+    DocDeclStr(
+        void , Veto(bool veto = true),
+        "Call this from your event handler to veto a system shutdown or to
+signal to the calling application that a window close did not happen.
+
+You can only veto a shutdown or close if `CanVeto` returns true.", "");
+

     bool GetVeto() const;
     bool GetVeto() const;

+
+    DocDeclStr(
+        void , SetCanVeto(bool canVeto),
+        "Sets the 'can veto' flag.", "");
+
+    DocDeclStr(
+        bool , CanVeto() const,
+        "Returns true if you can veto a system shutdown or a window close
+event. Vetoing a window close event is not possible if the calling
+code wishes to force the application to exit, and so this function
+must be called to check this.", "");
+

 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxShowEvent,
+"An EVT_SHOW event is sent when a window is shown or hidden.", "");
+

 class wxShowEvent : public wxEvent
 {
 public:
 class wxShowEvent : public wxEvent
 {
 public:

-    wxShowEvent(int winid = 0, bool show = False);
-    
+    wxShowEvent(int winid = 0, bool show = false);
+

     void SetShow(bool show);
     bool GetShow() const;
 
     void SetShow(bool show);
     bool GetShow() const;
 


@@ -923,17 +1812,29 @@ public:
 //---------------------------------------------------------------------------
 %newgroup;
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxIconizeEvent,
+"An EVT_ICONIZE event is sent when a frame is iconized (minimized) or
+restored.", "");
+

 class wxIconizeEvent: public wxEvent
 {
 public:
 class wxIconizeEvent: public wxEvent
 {
 public:

-    wxIconizeEvent(int id = 0, bool iconized = True);
-    bool Iconized();
+    wxIconizeEvent(int id = 0, bool iconized = true);
+
+    DocDeclStr(
+        bool , Iconized(),
+        "Returns ``True`` if the frame has been iconized, ``False`` if it has
+been restored.", "");
+

 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxMaximizeEvent,
+"An EVT_MAXIMIZE event is sent when a frame is maximized or restored.", "");
+

 class wxMaximizeEvent: public wxEvent
 {
 public:
 class wxMaximizeEvent: public wxEvent
 {
 public:


@@ -943,26 +1844,58 @@ public:
 //---------------------------------------------------------------------------
 %newgroup;
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxDropFilesEvent,
+"This class is used for drop files events, that is, when files have
+been dropped onto the window. This functionality is only available
+under Windows. The window must have previously been enabled for
+dropping by calling `wx.Window.DragAcceptFiles`.
+
+Important note: this is a separate implementation to the more general
+drag and drop implementation using `wx.FileDropTarget`, and etc. This
+implementation uses the older, Windows message-based approach of
+dropping files.
+
+Use wx.EVT_DROP_FILES to bind an event handler to receive file drop
+events.
+", "");
+

 class wxDropFilesEvent: public wxEvent
 {
 public:
 class wxDropFilesEvent: public wxEvent
 {
 public:

-    wxPoint GetPosition();
-    int GetNumberOfFiles();
+
+    // TODO:  wrap the ctor!
+
+
+    DocDeclStr(
+        wxPoint , GetPosition(),
+        "Returns the position at which the files were dropped.", "");
+
+    DocDeclStr(
+        int , GetNumberOfFiles(),
+        "Returns the number of files dropped.", "");
+

 
     %extend {
 
     %extend {

+        DocStr(
+            GetFiles,
+            "Returns a list of the filenames that were dropped.", "");
+

         PyObject* GetFiles() {
             int         count = self->GetNumberOfFiles();
             wxString*   files = self->GetFiles();
         PyObject* GetFiles() {
             int         count = self->GetNumberOfFiles();
             wxString*   files = self->GetFiles();

+            wxPyBlock_t blocked = wxPyBeginBlockThreads();

             PyObject*   list  = PyList_New(count);
 
             if (!list) {
                 PyErr_SetString(PyExc_MemoryError, "Can't allocate list of files!");
             PyObject*   list  = PyList_New(count);
 
             if (!list) {
                 PyErr_SetString(PyExc_MemoryError, "Can't allocate list of files!");

+                wxPyEndBlockThreads(blocked);

                 return NULL;
             }
 
             for (int i=0; i<count; i++) {
                 PyList_SetItem(list, i, wx2PyString(files[i]));
             }
                 return NULL;
             }
 
             for (int i=0; i<count; i++) {
                 PyList_SetItem(list, i, wx2PyString(files[i]));
             }

+            wxPyEndBlockThreads(blocked);

             return list;
         }
     }
             return list;
         }
     }


@@ -974,96 +1907,272 @@ public:
 %newgroup;
 
 
 %newgroup;
 
 

-// Whether to always send update events to windows, or
-// to only send update events to those with the
-// wxWS_EX_PROCESS_UI_UPDATES style.
-

 enum wxUpdateUIMode
 {
 enum wxUpdateUIMode
 {

-        // Send UI update events to all windows

     wxUPDATE_UI_PROCESS_ALL,
     wxUPDATE_UI_PROCESS_ALL,

-
-        // Send UI update events to windows that have
-        // the wxWS_EX_PROCESS_UI_UPDATES flag specified

     wxUPDATE_UI_PROCESS_SPECIFIED
 };
 
 
     wxUPDATE_UI_PROCESS_SPECIFIED
 };
 
 

+DocStr(wxUpdateUIEvent,
+"This class is used for EVT_UPDATE_UI pseudo-events which are sent by
+wxWidgets to give an application the chance to update various user
+interface elements.
+
+Without update UI events, an application has to work hard to
+check/uncheck, enable/disable, and set the text for elements such as
+menu items and toolbar buttons. The code for doing this has to be
+mixed up with the code that is invoked when an action is invoked for a
+menu item or button.
+
+With update UI events, you define an event handler to look at the
+state of the application and change UI elements accordingly. wxWidgets
+will call your handler functions in idle time, so you don't have to
+worry where to call this code. In addition to being a clearer and more
+declarative method, it also means you don't have to worry whether
+you're updating a toolbar or menubar identifier. The same handler can
+update a menu item and toolbar button, if the ID values are the same.
+
+Instead of directly manipulating the menu or button, you call
+functions in the event object, such as `Check`. wxWidgets will
+determine whether such a call has been made, and which UI element to
+update.
+
+These events will work for popup menus as well as menubars. Just
+before a menu is popped up, `wx.Menu.UpdateUI` is called to process
+any UI events for the window that owns the menu.
+
+If you find that the overhead of UI update processing is affecting
+your application, you can do one or both of the following:
+
+   1. Call `wx.UpdateUIEvent.SetMode` with a value of
+      wx.UPDATE_UI_PROCESS_SPECIFIED, and set the extra style
+      wx.WS_EX_PROCESS_UPDATE_EVENTS for every window that should
+      receive update events. No other windows will receive update
+      events.
+
+   2. Call `wx.UpdateUIEvent.SetUpdateInterval` with a millisecond
+      value to set the delay between updates. You may need to call
+      `wx.Window.UpdateWindowUI` at critical points, for example when
+      a dialog is about to be shown, in case the user sees a slight
+      delay before windows are updated.
+
+Note that although events are sent in idle time, defining a EVT_IDLE
+handler for a window does not affect this because the events are sent
+from an internal idle handler.
+
+wxWidgets tries to optimize update events on some platforms. On
+Windows and GTK+, events for menubar items are only sent when the menu
+is about to be shown, and not in idle time.
+", "");

 
 class wxUpdateUIEvent : public wxCommandEvent
 {
 public:
 
 class wxUpdateUIEvent : public wxCommandEvent
 {
 public:

-    wxUpdateUIEvent(wxWindowID commandId = 0);
-    
-    bool GetChecked() const;
-    bool GetEnabled() const;
-    wxString GetText() const;
-    bool GetSetText() const;
-    bool GetSetChecked() const;
-    bool GetSetEnabled() const;
-
-    void Check(bool check);
-    void Enable(bool enable);
-    void SetText(const wxString& text);
-
-    // Sets the interval between updates in milliseconds.
-    // Set to -1 to disable updates, or to 0 to update as frequently as possible.
-    static void SetUpdateInterval(long updateInterval);
-
-    // Returns the current interval between updates in milliseconds
-    static long GetUpdateInterval();
-
-    // Can we update this window?
-    static bool CanUpdate(wxWindow *win);
-
-    // Reset the update time to provide a delay until the next
-    // time we should update
-    static void ResetUpdateTime();
-
-    // Specify how wxWindows will send update events: to
-    // all windows, or only to those which specify that they
-    // will process the events.
-    static void SetMode(wxUpdateUIMode mode);
-
-    // Returns the UI update mode
-    static wxUpdateUIMode GetMode();
+    DocCtorStr(
+        wxUpdateUIEvent(wxWindowID commandId = 0),
+        "Constructor", "");
+
+    DocDeclStr(
+        bool , GetChecked() const,
+        "Returns ``True`` if the UI element should be checked.", "");
+
+    DocDeclStr(
+        bool , GetEnabled() const,
+        "Returns ``True`` if the UI element should be enabled.", "");
+
+    DocDeclStr(
+        bool , GetShown() const,
+        "Returns ``True`` if the UI element should be shown.", "");
+
+    DocDeclStr(
+        wxString , GetText() const,
+        "Returns the text that should be set for the UI element.", "");
+
+    DocDeclStr(
+        bool , GetSetText() const,
+        "Returns ``True`` if the application has called `SetText`. For
+wxWidgets internal use only.", "");
+
+    DocDeclStr(
+        bool , GetSetChecked() const,
+        "Returns ``True`` if the application has called `Check`. For wxWidgets
+internal use only.", "");
+
+    DocDeclStr(
+        bool , GetSetEnabled() const,
+        "Returns ``True`` if the application has called `Enable`. For wxWidgets
+internal use only.", "");
+
+    DocDeclStr(
+        bool , GetSetShown() const,
+        "Returns ``True`` if the application has called `Show`. For wxWidgets
+internal use only.", "");
+
+
+    DocDeclStr(
+        void , Check(bool check),
+        "Check or uncheck the UI element.", "");
+
+    DocDeclStr(
+        void , Enable(bool enable),
+        "Enable or disable the UI element.", "");
+
+    DocDeclStr(
+        void , Show(bool show),
+        "Show or hide the UI element.", "");
+
+
+    DocDeclStr(
+        void , SetText(const wxString& text),
+        "Sets the text for this UI element.", "");
+
+
+
+    DocDeclStr(
+        static void , SetUpdateInterval(long updateInterval),
+        "Sets the interval between updates in milliseconds. Set to -1 to
+disable updates, or to 0 to update as frequently as possible. The
+default is 0.
+
+Use this to reduce the overhead of UI update events if your
+application has a lot of windows. If you set the value to -1 or
+greater than 0, you may also need to call `wx.Window.UpdateWindowUI`
+at appropriate points in your application, such as when a dialog is
+about to be shown.", "");
+
+
+    DocDeclStr(
+        static long , GetUpdateInterval(),
+        "Returns the current interval between updates in milliseconds. -1
+disables updates, 0 updates as frequently as possible.", "");
+
+
+    DocDeclStr(
+        static bool , CanUpdate(wxWindow *win),
+        "Returns ``True`` if it is appropriate to update (send UI update events
+to) this window.
+
+This function looks at the mode used (see `wx.UpdateUIEvent.SetMode`),
+the wx.WS_EX_PROCESS_UPDATE_EVENTS flag in window, the time update
+events were last sent in idle time, and the update interval, to
+determine whether events should be sent to this window now. By default
+this will always return true because the update mode is initially
+wx.UPDATE_UI_PROCESS_ALL and the interval is set to 0; so update
+events will be sent as often as possible. You can reduce the frequency
+that events are sent by changing the mode and/or setting an update
+interval.
+", "");
+
+
+    DocDeclStr(
+        static void , ResetUpdateTime(),
+        "Used internally to reset the last-updated time to the current time. It
+is assumed that update events are normally sent in idle time, so this
+is called at the end of idle processing.", "");
+
+
+    DocDeclStr(
+        static void , SetMode(wxUpdateUIMode mode),
+        "Specify how wxWidgets will send update events: to all windows, or only
+to those which specify that they will process the events.
+
+The mode may be one of the following values:
+
+    =============================   ==========================================
+    wxUPDATE_UI_PROCESS_ALL         Send UI update events to all windows.  This
+                                    is the default setting.
+    wxUPDATE_UI_PROCESS_SPECIFIED   Send UI update events only to windows that
+                                    have the wx.WS_EX_PROCESS_UI_UPDATES extra
+                                    style set.
+    =============================   ==========================================
+", "");
+
+
+    DocDeclStr(
+        static wxUpdateUIMode , GetMode(),
+        "Returns a value specifying how wxWidgets will send update events: to
+all windows, or only to those which specify that they will process the
+events.", "");
+

 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxSysColourChangedEvent,
+"This class is used for EVT_SYS_COLOUR_CHANGED, which are generated
+when the user changes the colour settings using the control
+panel. This is only applicable under Windows.
+
+The default event handler for this event propagates the event to child
+windows, since Windows only sends the events to top-level windows. If
+intercepting this event for a top-level window, remember to call
+`Skip` so the the base class handler will still be executed, or to
+pass the event on to the window's children explicitly.
+", "");
+

 class wxSysColourChangedEvent: public wxEvent {
 public:
 class wxSysColourChangedEvent: public wxEvent {
 public:

-    wxSysColourChangedEvent();
+    DocCtorStr(
+        wxSysColourChangedEvent(),
+        "Constructor", "");

 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 
 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 

-//  wxEVT_MOUSE_CAPTURE_CHANGED
-//  The window losing the capture receives this message
-//  (even if it released the capture itself).
+DocStr(wxMouseCaptureChangedEvent,
+"An mouse capture changed event (EVT_MOUSE_CAPTURE_CHANGED) is sent to
+a window that loses its mouse capture. This is called even if
+`wx.Window.ReleaseMouse` was called by the application code. Handling
+this event allows an application to cater for unexpected capture
+releases which might otherwise confuse mouse handling code.
+
+This event is implemented under Windows only.", "");
+

 class wxMouseCaptureChangedEvent : public wxEvent
 {
 public:
 class wxMouseCaptureChangedEvent : public wxEvent
 {
 public:

-    wxMouseCaptureChangedEvent(wxWindowID winid = 0, wxWindow* gainedCapture = NULL);
+    DocCtorStr(
+        wxMouseCaptureChangedEvent(wxWindowID winid = 0, wxWindow* gainedCapture = NULL),
+        "Constructor", "");
+
+    DocDeclStr(
+        wxWindow* , GetCapturedWindow() const,
+        "Returns the window that gained the capture, or ``None`` if it was a
+non-wxWidgets window.", "");

 
 

-    wxWindow* GetCapturedWindow() const;

 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxDisplayChangedEvent,
+"An EVT_DISPLAY_CHANGED event is sent to all windows when the display
+resolution has changed.
+
+This event is implemented under Windows only.", "");
+

 class wxDisplayChangedEvent : public wxEvent
 {
 public:
 class wxDisplayChangedEvent : public wxEvent
 {
 public:

-    wxDisplayChangedEvent();
+    DocCtorStr(
+        wxDisplayChangedEvent(),
+        "", "");

 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxPaletteChangedEvent,
+"An EVT_PALETTE_CHANGED event is sent when the system palette has
+changed, thereby giving each window a chance to redo their own to
+match.
+
+This event is implemented under Windows only.", "");
+

 class  wxPaletteChangedEvent : public wxEvent
 {
 public:
 class  wxPaletteChangedEvent : public wxEvent
 {
 public:


@@ -1077,16 +2186,23 @@ public:
 //---------------------------------------------------------------------------
 %newgroup;
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxQueryNewPaletteEvent,
+       "An EVT_QUERY_NEW_PALETE event indicates the window is getting keyboard
+focus and should re-do its palette.
+
+This event is implemented under Windows only.", "");

 
 

-//  wxEVT_QUERY_NEW_PALETTE
-//  Indicates the window is getting keyboard focus and should re-do its palette.

 class wxQueryNewPaletteEvent : public wxEvent
 {
 public:
 class wxQueryNewPaletteEvent : public wxEvent
 {
 public:

-    wxQueryNewPaletteEvent(wxWindowID winid = 0);
+    DocCtorStr(
+        wxQueryNewPaletteEvent(wxWindowID winid = 0),
+        "Constructor.", "");
+
+    DocDeclStr(
+        void , SetPaletteRealized(bool realized),
+        "App should set this if it changes the palette.", "");

 
 

-    // App sets this if it changes the palette.
-    void SetPaletteRealized(bool realized);

     bool GetPaletteRealized() const;
 };
 
     bool GetPaletteRealized() const;
 };
 


@@ -1094,115 +2210,261 @@ public:
 %newgroup;
 
 
 %newgroup;
 
 

-//  Event generated by dialog navigation keys
-//  wxEVT_NAVIGATION_KEY
+
+DocStr(wxNavigationKeyEvent,
+"EVT_NAVIGATION_KEY events are used to control moving the focus between
+widgets, otherwise known as tab-traversal.  You woudl normally not
+catch navigation events in applications as there are already
+appropriate handlers in `wx.Dialog` and `wx.Panel`, but you may find
+it useful to send navigation events in certain situations to change
+the focus in certain ways, although it's probably easier to just call
+`wx.Window.Navigate`.", "");

 
 class wxNavigationKeyEvent : public wxEvent
 {
 public:
 
 class wxNavigationKeyEvent : public wxEvent
 {
 public:

-    wxNavigationKeyEvent();
-    
-    // direction: forward (True) or backward (False)
-    bool GetDirection() const;
-    void SetDirection(bool bForward);
-
-    // it may be a window change event (MDI, notebook pages...) or a control
-    // change event
-    bool IsWindowChange() const;
-    void SetWindowChange(bool bIs);
-
-    // the child which has the focus currently (may be NULL - use
-    // wxWindow::FindFocus then)
-    wxWindow* GetCurrentFocus() const;
-    void SetCurrentFocus(wxWindow *win);
-};
+    DocCtorStr(
+        wxNavigationKeyEvent(),
+        "", "");
+
+    DocDeclStr(
+        bool , GetDirection() const,
+        "Returns ``True`` if the direction is forward, ``False`` otherwise.", "");
+
+    DocDeclStr(
+        void , SetDirection(bool forward),
+        "Specify the direction that the navigation should take.  Usually the
+difference between using Tab and Shift-Tab.", "");
+
+
+    DocDeclStr(
+        bool , IsWindowChange() const,
+        "Returns ``True`` if window change is allowed.", "");
+
+    DocDeclStr(
+        void , SetWindowChange(bool ischange),
+        "Specify if the navigation should be able to change parent windows.
+For example, changing notebook pages, etc. This is usually implemented
+by using Control-Tab.", "");
+
+
+    DocDeclStr(
+        bool , IsFromTab() const,
+        "Returns ``True`` if the navigation event is originated from the Tab
+key.", "");
+
+    DocDeclStr(
+        void , SetFromTab(bool bIs),
+        "Set to true under MSW if the event was generated using the tab key.
+This is required for proper navogation over radio buttons.", "");
+
+
+    DocDeclStr(
+        void , SetFlags(long flags),
+        "Set the navigation flags to a combination of the following:

 
 

+    * wx.NavigationKeyEvent.IsBackward
+    * wx.NavigationKeyEvent.IsForward
+    * wx.NavigationKeyEvent.WinChange
+    * wx.NavigationKeyEvent.FromTab
+", "");
+
+
+    DocDeclStr(
+        wxWindow* , GetCurrentFocus() const,
+        "Returns the child window which currenty has the focus.  May be
+``None``.", "");
+
+    DocDeclStr(
+        void , SetCurrentFocus(wxWindow *win),
+        "Set the window that has the focus.", "");
+
+
+    enum {
+        IsBackward,
+        IsForward,
+        WinChange,
+        FromTab
+    };
+};

 
 //---------------------------------------------------------------------------
 %newgroup;
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 

-// Window creation/destruction events: the first is sent as soon as window is
-// created (i.e. the underlying GUI object exists), but when the C++ object is
-// fully initialized (so virtual functions may be called). The second,
-// wxEVT_DESTROY, is sent right before the window is destroyed - again, it's
-// still safe to call virtual functions at this moment
+
+DocStr(wxWindowCreateEvent,
+       "The EVT_WINDOW_CREATE event is sent as soon as the window object (the
+underlying GUI object) exists.", "");

 
 class wxWindowCreateEvent : public wxCommandEvent
 {
 public:
     wxWindowCreateEvent(wxWindow *win = NULL);
 
 class wxWindowCreateEvent : public wxCommandEvent
 {
 public:
     wxWindowCreateEvent(wxWindow *win = NULL);

-    wxWindow *GetWindow() const;
+
+    DocDeclStr(
+        wxWindow *, GetWindow() const,
+        "Returns the window that this event refers to.", "");
+

 };
 
 };
 

+
+DocStr(wxWindowDestroyEvent,
+       "The EVT_WINDOW_DESTROY event is sent from the `wx.Window` destructor
+when the GUI window is destroyed.
+
+When a class derived from `wx.Window` is destroyed its destructor will
+have already run by the time this event is sent. Therefore this event
+will not usually be received at all by the window itself.  Since it is
+received after the destructor has run, an object should not try to
+handle its own wx.WindowDestroyEvent, but it can be used to get
+notification of the destruction of another window.", "");

 class wxWindowDestroyEvent : public wxCommandEvent
 {
 public:
     wxWindowDestroyEvent(wxWindow *win = NULL);
 class wxWindowDestroyEvent : public wxCommandEvent
 {
 public:
     wxWindowDestroyEvent(wxWindow *win = NULL);

-    wxWindow *GetWindow() const;
+
+    DocDeclStr(
+        wxWindow *, GetWindow() const,
+        "Returns the window that this event refers to.", "");

 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 };
 
 
 //---------------------------------------------------------------------------
 %newgroup;
 

-// A Context event is sent when the user right clicks on a window or
-// presses Shift-F10
-// NOTE : Under windows this is a repackaged WM_CONTETXMENU message
-//        Under other systems it may have to be generated from a right click event
-/*
- wxEVT_CONTEXT_MENU
-*/
+
+DocStr(wxContextMenuEvent,
+"This class is used for context menu events (EVT_CONTECT_MENU,) sent to
+give the application a chance to show a context (popup) menu.", "");

 
 class wxContextMenuEvent : public wxCommandEvent
 {
 public:
 
 class wxContextMenuEvent : public wxCommandEvent
 {
 public:

-    wxContextMenuEvent(wxEventType type = wxEVT_NULL,
-                       wxWindowID winid = 0,
-                       const wxPoint& pt = wxDefaultPosition);
+    DocCtorStr(
+        wxContextMenuEvent(wxEventType type = wxEVT_NULL,
+                           wxWindowID winid = 0,
+                           const wxPoint& pt = wxDefaultPosition),
+        "Constructor.", "");

 
     // Position of event (in screen coordinates)
 
     // Position of event (in screen coordinates)

-    const wxPoint& GetPosition() const;
-    void SetPosition(const wxPoint& pos);
+    DocDeclStr(
+        const wxPoint& , GetPosition() const,
+        "Returns the position (in screen coordinants) at which the menu should
+be shown.", "");
+
+
+    DocDeclStr(
+        void , SetPosition(const wxPoint& pos),
+        "Sets the position at which the menu should be shown.", "");
+

 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 

-// Whether to always send idle events to windows, or
-// to only send update events to those with the
-// wxWS_EX_PROCESS_IDLE style.
-

 enum wxIdleMode
 {
 enum wxIdleMode
 {

-        // Send idle events to all windows

     wxIDLE_PROCESS_ALL,
     wxIDLE_PROCESS_ALL,

-
-        // Send idle events to windows that have
-        // the wxWS_EX_PROCESS_IDLE flag specified

     wxIDLE_PROCESS_SPECIFIED
 };
 
 
     wxIDLE_PROCESS_SPECIFIED
 };
 
 

+DocStr(wxIdleEvent,
+"This class is used for EVT_IDLE events, which are generated and sent
+when the application *becomes* idle.  In other words, the when the
+event queue becomes empty then idle events are sent to all windows (by
+default) and as long as none of them call `RequestMore` then there are
+no more idle events until after the system event queue has some normal
+events and then becomes empty again.
+
+By default, idle events are sent to all windows. If this is causing a
+significant overhead in your application, you can call
+`wx.IdleEvent.SetMode` with the value wx.IDLE_PROCESS_SPECIFIED, and
+set the wx.WS_EX_PROCESS_IDLE extra window style for every window
+which should receive idle events.  Then idle events will only be sent
+to those windows and not to any others.", "");
+

 class wxIdleEvent : public wxEvent
 {
 public:
 class wxIdleEvent : public wxEvent
 {
 public:

-    wxIdleEvent();
-    
-    void RequestMore(bool needMore = True);
-    bool MoreRequested() const;
+    DocCtorStr(
+        wxIdleEvent(),
+        "Constructor", "");
+
+
+    DocDeclStr(
+        void , RequestMore(bool needMore = true),
+        "Tells wxWidgets that more processing is required. This function can be
+called by an EVT_IDLE handler for a window to indicate that the
+application should forward the EVT_IDLE event once more to the
+application windows. If no window calls this function during its
+EVT_IDLE handler, then the application will remain in a passive event
+loop until a new event is posted to the application by the windowing
+system.", "");
+
+    DocDeclStr(
+        bool , MoreRequested() const,
+        "Returns ``True`` if the OnIdle function processing this event
+requested more processing time.", "");
+
+
+    DocDeclStr(
+        static void , SetMode(wxIdleMode mode),
+        "Static method for specifying how wxWidgets will send idle events: to
+all windows, or only to those which specify that they will process the
+events.
+
+The mode can be one of the following values:
+
+    =========================   ========================================
+    wx.IDLE_PROCESS_ALL         Send idle events to all windows
+    wx.IDLE_PROCESS_SPECIFIED   Send idle events only to windows that have
+                                the wx.WS_EX_PROCESS_IDLE extra style
+                                flag set.
+    =========================   ========================================
+", "");
+
+
+    DocDeclStr(
+        static wxIdleMode , GetMode(),
+        "Static method returning a value specifying how wxWidgets will send
+idle events: to all windows, or only to those which specify that they
+will process the events.", "");
+
+
+    DocDeclStr(
+        static bool , CanSend(wxWindow* win),
+        "Returns ``True`` if it is appropriate to send idle events to this
+window.
+
+This function looks at the mode used (see `wx.IdleEvent.SetMode`), and
+the wx.WS_EX_PROCESS_IDLE style in window to determine whether idle
+events should be sent to this window now. By default this will always
+return ``True`` because the update mode is initially
+wx.IDLE_PROCESS_ALL. You can change the mode to only send idle events
+to windows with the wx.WS_EX_PROCESS_IDLE extra window style set.", "");

 
 

-    // Specify how wxWindows will send idle events: to
-    // all windows, or only to those which specify that they
-    // will process the events.
-    static void SetMode(wxIdleMode mode);
+};
+
+//---------------------------------------------------------------------------
+%newgroup;

 
 

-    // Returns the idle event mode
-    static wxIdleMode GetMode();

 
 

-    // Can we send an idle event?
-    static bool CanSend(wxWindow* win);
+DocStr(wxClipboardTextEvent,
+"A Clipboard Text event is sent when a window intercepts a text
+copy/cut/paste message, i.e. the user has cut/copied/pasted data
+from/into a text control via ctrl-C/X/V, ctrl/shift-del/insert, a
+popup menu command, etc.  NOTE : under windows these events are *NOT*
+generated automatically for a Rich Edit text control.", "");
+
+class wxClipboardTextEvent : public wxCommandEvent
+{
+public:
+    wxClipboardTextEvent(wxEventType type = wxEVT_NULL,
+                         wxWindowID winid = 0);

 };
 
 };
 

+

 //---------------------------------------------------------------------------
 %newgroup;
 
 //---------------------------------------------------------------------------
 %newgroup;
 


@@ -1210,26 +2472,55 @@ public:
 // system without loosing anything.  They do this by keeping a reference to
 // themselves and some special case handling in wxPyCallback::EventThunker.
 
 // system without loosing anything.  They do this by keeping a reference to
 // themselves and some special case handling in wxPyCallback::EventThunker.
 

+DocStr(wxPyEvent,
+"wx.PyEvent can be used as a base class for implementing custom event
+types in Python.  You should derived from this class instead of
+`wx.Event` because this class is Python-aware and is able to transport
+its Python bits safely through the wxWidgets event system and have
+them still be there when the event handler is invoked.
+
+:see: `wx.PyCommandEvent`
+", "");
+

 class wxPyEvent : public wxEvent {
 public:
 class wxPyEvent : public wxEvent {
 public:

-    %pythonAppend wxPyEvent     "self.SetSelf(self)"
-    wxPyEvent(int winid=0, wxEventType commandType = wxEVT_NULL );
+    %pythonAppend wxPyEvent     "self._SetSelf(self)"
+    DocCtorStr(
+        wxPyEvent(int winid=0, wxEventType eventType = wxEVT_NULL ),
+        "", "");
+

     ~wxPyEvent();
 
 
     ~wxPyEvent();
 
 

-    void SetSelf(PyObject* self);
-    PyObject* GetSelf();
+    %Rename(_SetSelf, void , SetSelf(PyObject* self));
+    %Rename(_GetSelf, PyObject* , GetSelf());

 };
 
 
 };
 
 

+
+DocStr(wxPyCommandEvent,
+"wx.PyCommandEvent can be used as a base class for implementing custom
+event types in Python, where the event shoudl travel up to parent
+windows looking for a handler.  You should derived from this class
+instead of `wx.CommandEvent` because this class is Python-aware and is
+able to transport its Python bits safely through the wxWidgets event
+system and have them still be there when the event handler is invoked.
+
+:see: `wx.PyEvent`
+", "");
+

 class wxPyCommandEvent : public wxCommandEvent {
 public:
 class wxPyCommandEvent : public wxCommandEvent {
 public:

-    %pythonAppend wxPyCommandEvent     "self.SetSelf(self)"
-    wxPyCommandEvent(wxEventType commandType = wxEVT_NULL, int id=0);
+    %pythonAppend wxPyCommandEvent     "self._SetSelf(self)"
+
+    DocCtorStr(
+        wxPyCommandEvent(wxEventType eventType = wxEVT_NULL, int id=0),
+        "", "");
+

     ~wxPyCommandEvent();
 
     ~wxPyCommandEvent();
 

-    void SetSelf(PyObject* self);
-    PyObject* GetSelf();
+    %Rename(_SetSelf, void , SetSelf(PyObject* self));
+    %Rename(_GetSelf, PyObject* , GetSelf());

 };
 
 
 };
 
 


@@ -1237,4 +2528,38 @@ public:
 //---------------------------------------------------------------------------
 
 
 //---------------------------------------------------------------------------
 
 

+DocStr(wxDateEvent,
+"This event class holds information about a date change event and is
+used together with `wx.DatePickerCtrl`. It also serves as a base class
+for `wx.calendar.CalendarEvent`.  Bind these event types with
+EVT_DATE_CHANGED.", "");
+
+class wxDateEvent : public wxCommandEvent
+{
+public:
+    DocCtorStr(
+        wxDateEvent(wxWindow *win, const wxDateTime& dt, wxEventType type),
+        "", "");
+
+    DocDeclStr(
+        const wxDateTime& , GetDate() const,
+        "Returns the date.", "");
+
+    DocDeclStr(
+        void , SetDate(const wxDateTime &date),
+        "Sets the date carried by the event, normally only used by the library
+internally.", "");
+
+
+};

 
 

+
+%constant wxEventType wxEVT_DATE_CHANGED;
+
+%pythoncode {
+    EVT_DATE_CHANGED = wx.PyEventBinder( wxEVT_DATE_CHANGED, 1 )
+}
+
+
+//---------------------------------------------------------------------------
+//---------------------------------------------------------------------------