setCapture method
[This documentation is preliminary and is subject to change.]
Sets the mouse capture to the object that belongs to the current document.
Syntax
HRESULT retVal = object.setCapture(containerCapture);
Standards information
There are no standards that apply here.
Parameters
containerCapture [in, optional]
Type: VARIANT_BOOL
Specifies one of the following values.
VARIANT_TRUE (true)
Default. Events originating in a container are captured by the container.
VARIANT_FALSE (false)
Events originating in a container are not captured by the container.
Return value
Type: HRESULT
If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
Remarks
After mouse capture is set to an object, all mouse events for the document are routed to that object. Supported mouse events include HTMLFrameSiteEvents::onmousedown, HTMLFrameSiteEvents::onmouseup, HTMLFrameSiteEvents::onmousemove, HTMLFrameSiteEvents::onclick, HTMLFrameSiteEvents::ondblclick, HTMLFrameSiteEvents::onmouseover, and HTMLFrameSiteEvents::onmouseout. The srcElement property of the window event object always returns the object that is positioned under the mouse, instead of the object that has mouse capture.
Mouse clicks automatically trigger the HTMLFrameSiteEvents::onlosecapture event. To retain mouse capture, call setCapture inside the HTMLFrameSiteEvents::onclick event handler.
When the containerCapture parameter is set to true
, a container object, such as a div, captures mouse events for all objects in it. By passing the value false
, objects in that container can fire events, and cancel event bubbling.
Drag-and-drop operations, such as the ondragstart event, and text selection through the user interface are disabled when mouse capture is set programmatically. The following key events are unaffected by mouse capture and fire as usual: HTMLFrameSiteEvents::onkeydown, HTMLFrameSiteEvents::onkeyup, and HTMLFrameSiteEvents::onkeypress.
Mouse clicks automatically trigger the HTMLFrameSiteEvents::onlosecapture event. To retain mouse capture, call setCapture inside the HTMLFrameSiteEvents::onclick event handler. Mouse capture is also lost if the browser window loses focus for any reason (including alerts or pop-up windows).
Note The containerCapture parameter is available only in Microsoft Internet Explorer 5.5 or later. For earlier versions, do not specify a parameter.
See also
Reference
HTMLFrameSiteEvents::onlosecapture
Conceptual
Send comments about this topic to Microsoft
Build date: 6/12/2012