Added wxMouseCaptureLostEvent

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

diff --git a/wxPython/src/_event.i b/wxPython/src/_event.i
index 979fbf16049de7adcd1e937fedcf9b28a258f1fd..614030cf299412379d09bde9f80260692118b241 100644 (file)
--- a/wxPython/src/_event.i
+++ b/wxPython/src/_event.i
@@ -149,6 +149,7 @@ wxEventType wxNewEventType();
 %constant wxEventType wxEVT_ICONIZE;
 %constant wxEventType wxEVT_MAXIMIZE;
 %constant wxEventType wxEVT_MOUSE_CAPTURE_CHANGED;
+%constant wxEventType wxEVT_MOUSE_CAPTURE_LOST;
 %constant wxEventType wxEVT_PAINT;
 %constant wxEventType wxEVT_ERASE_BACKGROUND;
 %constant wxEventType wxEVT_NC_PAINT;
@@ -235,6 +236,7 @@ EVT_WINDOW_CREATE = wx.PyEventBinder( wxEVT_CREATE )
 EVT_WINDOW_DESTROY = wx.PyEventBinder( wxEVT_DESTROY )
 EVT_SET_CURSOR = wx.PyEventBinder( wxEVT_SET_CURSOR )
 EVT_MOUSE_CAPTURE_CHANGED = wx.PyEventBinder( wxEVT_MOUSE_CAPTURE_CHANGED )
+EVT_MOUSE_CAPTURE_LOST = wx.PyEventBinder( wxEVT_MOUSE_CAPTURE_LOST )         
 
 EVT_LEFT_DOWN = wx.PyEventBinder( wxEVT_LEFT_DOWN )
 EVT_LEFT_UP = wx.PyEventBinder( wxEVT_LEFT_UP )
@@ -2149,6 +2151,30 @@ non-wxWidgets window.", "");
 //---------------------------------------------------------------------------
 %newgroup;
 
+DocStr(wxMouseCaptureLostEvent,
+"A mouse capture lost event is sent to a window that obtained mouse
+capture, which was subsequently loss due to \"external\" event, for
+example when a dialog box is shown or if another application captures
+the mouse.
+
+If this happens, this event is sent to all windows that are on the
+capture stack (i.e. a window that called `wx.Window.CaptureMouse`, but
+didn't call `wx.Window.ReleaseMouse` yet). The event is *not* sent
+if the capture changes because of a call to CaptureMouse or
+ReleaseMouse.
+
+This event is currently emitted under Windows only.
+", "");
+
+class wxMouseCaptureLostEvent : public wxEvent
+{
+public:
+    wxMouseCaptureLostEvent(wxWindowID winid = 0);
+};
+
+//---------------------------------------------------------------------------
+%newgroup;
+
 DocStr(wxDisplayChangedEvent,
 "An EVT_DISPLAY_CHANGED event is sent to all windows when the display
 resolution has changed.

diff --git a/wxPython/src/_window.i b/wxPython/src/_window.i
index 2e014bcd137229de7392d1a2259888e631892cb3..2f0ebf8636735cfe63e4328e1661571d8e9bac93 100644 (file)
--- a/wxPython/src/_window.i
+++ b/wxPython/src/_window.i
@@ -1193,7 +1193,13 @@ Note that wxWindows maintains the stack of windows having captured the
 mouse and when the mouse is released the capture returns to the window
 which had had captured it previously and it is only really released if
 there were no previous window. In particular, this means that you must
-release the mouse as many times as you capture it.", "");
+release the mouse as many times as you capture it, unless the window
+receives the `wx.MouseCaptureLostEvent` event.
+ 
+Any application which captures the mouse in the beginning of some
+operation *must* handle `wx.MouseCaptureLostEvent` and cancel this
+operation when it receives the event. The event handler must not
+recapture mouse.", "");
     
     DocDeclStr(
         void , ReleaseMouse(),