IHTMLElement2::setCapture Method

Sets the mouse capture to the object belonging to the current document.

Syntax

HRESULT setCapture(
    VARIANT_BOOL bcontainerCapture
);

Parameters

bContainerCapture

VARIANT Boolean structure that returns the default value of TRUE. By default, the element having mouse capture will fire all events, regardless of where they originate in the document.

Return Value

Returns S_OK if the function was bound successfully, or an error code otherwise.

Remarks

Once mouse capture is set to an object, that object fires all mouse events for the document. Supported mouse events include onmousedown, onmouseup, onmousemove, onclick, ondblclick, onmouseover, and onmouseout. However, the srcElement property of the window event object always returns the object that is positioned under the mouse rather than the object that has mouse capture.

When a container object, such as a division, has mouse capture, events originating on objects within that container are fired by the division, unless the bContainerCapture parameter of the setCapture method is set to FALSE. Passing the value FALSE causes the container to no longer capture all document events. Instead, objects within that container still fire events, and those events also bubble as expected.

Drag-and-drop, as well as text selection through the user interface, are disabled when mouse capture is set programmatically.