setCapture Method

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

Syntax

object.setCapture([bContainerCapture])

Parameters

bContainerCapture Optional. Boolean that specifies one of the following values:

true Default. Events originating within a container with mouse capture are fired.
false Events originating within a container with mouse capture are not fired.

Return Value

No return value.

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. 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 DIV, has mouse capture, events originating on objects within that container are fired by the DIV, 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.

The following key events are unaffected by mouse capture and fire as usual: onkeydown, onkeyup, and onkeypress.

Example

The following examples use the setCapture method to show different aspects of mouse capture.

Sample Code

This example shows the difference between detecting events using event bubbling and mouse capture.

<BODY onload="oOwnCapture.setCapture()" 
    onclick="document.releaseCapture()">
<DIV ID=oOwnCapture
    onmousemove="oWriteLocation.value = event.x + event.y";
    onlosecapture="alert(event.srcElement.id + 
        ' lost mouse capture.')">
<P>Mouse capture has been set to this gray division (DIV) 
    at load time using the setCapture method. The text area will 
    track the mousemove event through the <B>x</B> 
    and <B>y</B> properties of the event object.<BR>
<P>Event bubbling works as usual on objects within a 
    container that has mouse capture. Demonstrate this concept by 
    clicking the button below or changing the active window from 
    this one then back. After oOwnCapture has lost mouse capture, 
    the text area continues tracking the mousemove events only 
    while the cursor is over objects it contains.</P>
    <BR><BR>
<TEXTAREA ID=oWriteLocation COLS=2>
    mouse location</TEXTAREA>
</DIV>
<HR>
<DIV ID=oNoCapture>
<P>This white division is here to illustrate that mousemove 
    events over objects it contains are captured on the gray 
    division, oOwnCapture.
<P>Click this text and check mouse coordinates captured in 
    the text area within the division above.</P>
<INPUT VALUE="Move mouse over this object.">
<INPUT TYPE=button VALUE="Click to End Mouse Capture">
</DIV>
</BODY>

This feature requires Microsoft® Internet Explorer 5 or later. Click the icon below to install the latest version. Then reload this page to view the sample.

This example shows how to use mouse capture to animate graphics.

<HEAD>
<SCRIPT>
var iRad = 25;
var iX01 = 165;
var iY01 = 170;
var iX02 = 285;
var iY02 = 170;

/* The doImgMouseMove function contains calculations to 
    reposition black.bmp in response to mouse movement  */
   
function doImgMouseMove()
{
  var iX1 = event.x - iX01;
  var iY1 = event.y - iY01;
  var iX2 = event.x - iX02;
  var iY2 = event.y - iY02;
  var change1 = Math.sqrt(iX1 * iX1 + iY1 * iY1);
  var change2 = Math.sqrt(iX2 * iX2 + iY2 * iY2);

  oPupilLeft.style.left = iX01 + iRad * iX1 / change1;
  oPupilLeft.style.top = iY01 + iRad * iY1 / change1;
  oPupilRight.style.left = iX02 + iRad * iX2 / change2;
  oPupilRight.style.top = iY02 + iRad * iY2 / change2;
}
</SCRIPT>
</HEAD>
<BODY onload="oEye.setCapture(false)" 
    onclick="oEye.releaseCapture()"
    ondragstart="event.returnValue = false;">
<INPUT TYPE=button ID=oToggle VALUE="Switch Mouse Capture On" 
    onclick="doClick()">
<IMG ID=oEye SRC="/workshop/graphics/eye.gif" 
    onmousemove="doImgMouseMove()">
<IMG ID=oPupilLeft SRC="/workshop/graphics/black.gif">
<IMG ID=oPupilRight SRC="/workshop/graphics/black.gif">
<P>The eyeballs track mouse pointer movement. When mouse 
    capture is on, they follow the mouse pointer no matter where it 
    is positioned in the document. When mouse capture is off, they 
    detect and follow mouse position only while the pointer is 
    positioned over the eyeball graphic.</P>
<P>In this example, mouse capture is set when the document is 
    loaded. Click anywhere on the document to remove mouse 
    capture.</P>
</BODY>

This feature requires Internet Explorer 5 or later. Click the icon below to install the latest version. Then reload this page to view the sample.

Applies To

[ Object Name ]

Platform Version

Win16:

Win32:

Mac:

Unix:

WinCE:

Version data is listed when the mouse hovers over a link, or the link has focus.

A, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, custom, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, Hn, HR, I, IMG, INPUT type=button, INPUT type=checkbox, INPUT type=file, INPUT type=hidden, INPUT type=image, INPUT type=password, INPUT type=radio, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, NOBR, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP