added wxEVT_MOUSE_CAPTURE_LOST event and code for correctly handling capture loss (bug #1153662)

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

docs/latex/wx/category.tex

@@ -257,6 +257,7 @@ An event object contains information about a specific event. Event handlers
 \twocolitem{\helpref{wxMaximizeEvent}{wxmaximizeevent}}{A maximize event}
 \twocolitem{\helpref{wxMenuEvent}{wxmenuevent}}{A menu event}
 \twocolitem{\helpref{wxMouseCaptureChangedEvent}{wxmousecapturechangedevent}}{A mouse capture changed event}
+\twocolitem{\helpref{wxMouseCaptureLostEvent}{wxmousecapturelostevent}}{A mouse capture lost event}
 \twocolitem{\helpref{wxMouseEvent}{wxmouseevent}}{A mouse event}
 \twocolitem{\helpref{wxMoveEvent}{wxmoveevent}}{A move event}
 \twocolitem{\helpref{wxNotebookEvent}{wxnotebookevent}}{A notebook control event}

docs/latex/wx/mcaptevt.tex

@@ -29,6 +29,7 @@ function that takes a wxMouseCaptureChangedEvent argument.
 
 \wxheading{See also}
 
+\helpref{wxMouseCaptureLostEvent}{wxmousecapturelostevent}
 \helpref{Event handling overview}{eventhandlingoverview}, 
 \helpref{wxWindow::CaptureMouse}{wxwindowcapturemouse}, 
 \helpref{wxWindow::ReleaseMouse}{wxwindowreleasemouse}, 
@@ -48,3 +49,51 @@ Constructor.
 
 Returns the window that gained the capture, or NULL if it was a non-wxWidgets window.
 
+
+\section{\class{wxMouseCaptureLostEvent}}\label{wxmousecapturelostevent}
+
+An 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 capture stack
+(i.e. called CaptureMouse, but didn't call ReleaseMouse yet). The event is
+{\em not} sent if the capture changes because of a call to CaptureMouse or
+ReleaseMouse.
+
+This event is currently emitted under Windows only.
+
+\wxheading{Derived from}
+
+\helpref{wxEvent}{wxevent}\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/event.h>
+
+\wxheading{Event table macros}
+
+To process this event, use the following event handler macro to direct input to
+a member function that takes a wxMouseCaptureLostEvent argument.
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf EVT\_MOUSE\_CAPTURE\_LOST(func)}}{Process a wxEVT\_MOUSE\_CAPTURE\_LOST event.}
+\end{twocollist}
+
+\wxheading{See also}
+
+\helpref{wxMouseCaptureChangedEvent}{wxmousecapturechangedevent}
+\helpref{Event handling overview}{eventhandlingoverview}, 
+\helpref{wxWindow::CaptureMouse}{wxwindowcapturemouse}, 
+\helpref{wxWindow::ReleaseMouse}{wxwindowreleasemouse}, 
+\helpref{wxWindow::GetCapture}{wxwindowgetcapture}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxMouseCaptureLostEvent::wxMouseCaptureLostEvent}\label{wxmousecapturelosteventctor}
+
+\func{}{wxMouseCaptureLostEvent}{\param{wxWindowID }{windowId = 0}}
+
+Constructor.

docs/latex/wx/window.tex

@@ -203,11 +203,18 @@ Note that wxWidgets 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.
+as you capture it, unless the window receives
+the \helpref{wxMouseCaptureLostEvent}{wxmousecapturelostevent} event.
+
+Any application which captures the mouse in the beginning of some operation
+{\em must} handle \helpref{wxMouseCaptureLostEvent}{wxmousecapturelostevent}
+and cancel this operation when it receives the event. The event handler must
+not recapture mouse.
 
 \wxheading{See also}
 
 \helpref{wxWindow::ReleaseMouse}{wxwindowreleasemouse}
+\helpref{wxMouseCaptureLostEvent}{wxmousecapturelostevent}
 
 
 \membersection{wxWindow::Center}\label{wxwindowcenter}
@@ -787,6 +794,7 @@ Returns the currently captured window.
 \helpref{wxWindow::HasCapture}{wxwindowhascapture},
 \helpref{wxWindow::CaptureMouse}{wxwindowcapturemouse},
 \helpref{wxWindow::ReleaseMouse}{wxwindowreleasemouse},
+\helpref{wxMouseCaptureLostEvent}{wxmousecapturelostevent}
 \helpref{wxMouseCaptureChangedEvent}{wxmousecapturechangedevent}
 
 
@@ -1390,6 +1398,7 @@ Returns {\tt true} if this window has the current mouse capture.
 
 \helpref{wxWindow::CaptureMouse}{wxwindowcapturemouse},
 \helpref{wxWindow::ReleaseMouse}{wxwindowreleasemouse},
+\helpref{wxMouseCaptureLostEvent}{wxmousecapturelostevent}
 \helpref{wxMouseCaptureChangedEvent}{wxmousecapturechangedevent}
 
 
@@ -2361,6 +2370,7 @@ Releases mouse input captured with \helpref{wxWindow::CaptureMouse}{wxwindowcapt
 \helpref{wxWindow::CaptureMouse}{wxwindowcapturemouse},
 \helpref{wxWindow::HasCapture}{wxwindowhascapture},
 \helpref{wxWindow::ReleaseMouse}{wxwindowreleasemouse},
+\helpref{wxMouseCaptureLostEvent}{wxmousecapturelostevent}
 \helpref{wxMouseCaptureChangedEvent}{wxmousecapturechangedevent}