From: Robin Dunn <robin@alldunn.com>
Date: Mon, 31 Jul 2006 19:12:07 +0000 (+0000)
Subject: Added wxMouseCaptureLostEvent
X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/e249d3c0dcbef5d7cdd31168456d407dd62c1300?ds=inline

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 979fbf1604..614030cf29 100644
--- 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 2e014bcd13..2f0ebf8636 100644
--- 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(),