In order to access this site you need to enable JavaScript!

You are here: Reference > JavaScript > client-side > event handling > methods > setCapture

setCapture method

Browser support:

Sets the current object to capture mouse events that occur within the entire browser window.

At most one object can capture mouse events at a time in Internet Explorer.

If an object has capture, then the capturable events will be dispatched to the object first, then, if the event propagates up, it will be dispatched to the ancestor elements of the object. If an event is captured, then it won't be dispatched to the original target element.

The capturable events are: onclick, ondblclick, onmousedown, onmouseup, onmousemove, onmouseout, and onmouseover.

To remove the mouse capture, use the releaseCapture method. If an object has capture and the browser window becomes inactive (another application window becomes the foreground window or a modal or modeless window becomes active in the current application window), then the object automatically loses the capture. If an object has capture and the setCapture method is called on another object, the previous object loses the capture.

When an object loses capture, it triggers the onlosecapture event.

The setCapture method only works in Internet Explorer, use the addEventListener method for event capturing in Firefox, Opera, Google Chrome and Safari (and optionally in Internet Explorer from version 9).

Event propagation and capturing work differently in browsers. You can find a detailed description about them on the page for the event object.

Syntax:

object.setCapture ([containerCapture]);

You can find the related objects in the Supported by objects section below.

Parameters:

containerCapture

Optional. Boolean that specifies whether the mouse events need to be captured for the descendant element of the current object or not.

One of the following values:">

false

Events that occur within the descendant element of the current object are not captured by the current object.

true

Default. All events are captured that occur within the entire browser window.

Return value:

This method has no return value.

Example HTML code 1:

This example illustrates the use of the setCapture and releaseCapture methods to move a square with the mouse:

<head>
    <style>
        #square {
            position:absolute;
            left:200px;
            top:200px;
            width:20px;
            height:20px;
            background:red;
        }
    </style>
    <script type="text/javascript">
        var capturing = false;

        function ToggleCapture () {
            var square = document.getElementById ("square");
            if (square.setCapture) {
                if (capturing) {
                    square.releaseCapture ();
                }
                else {
                    capturing = true;
                    square.setCapture ();
                }
            }
        }

        function OnLoseCapture () {
            capturing = false;
        }
        
        function MoveSquare () {
            if (capturing) {
                var square = document.getElementById ("square");
                square.style.left = event.clientX + "px";
                square.style.top = event.clientY + "px";
            }
        }
    </script>
</head>
<body onkeydown="ToggleCapture ();"> <br />
    <h3 style="text-align:center">Press any key to toggle capture!</h3>
    While mouse events are captured, the square follows the mouse.
    <div id="square" onmousemove="MoveSquare ();" onlosecapture="OnLoseCapture ()"></div>
</body>

Copy Code

Preview

Syntax Highlighter

Did you find this example helpful? yes no

Example HTML code 2:

This example illustrates a cross-browser solution for the previous example:

<head>
    <style>
        #square {
            position:absolute;
            left:200px;
            top:200px;
            width:20px;
            height:20px;
            background:red;
        }
    </style>
    <script type="text/javascript">
        var capturing = false;

        function ToggleCapture () {
            var square = document.getElementById ("square");
            if (capturing) {
                if (window.removeEventListener) {   // all browsers except IE before version 9
                    capturing = false;
                    window.removeEventListener ("mousemove", MoveSquare, true);
                }
                else {
                    if (square.releaseCapture) {    // IE before version 9
                        square.releaseCapture ();
                    }
                }
            }
            else {
                if (window.addEventListener) {  // all browsers except IE before version 9
                    capturing = true;
                    window.addEventListener ("mousemove", MoveSquare, true);
                }
                else {
                    if (square.setCapture) {    // IE before version 9
                        capturing = true;
                        square.setCapture ();
                    }
                }
            }
        }

        function OnLoseCapture () {
            capturing = false;
        }
        
        function MoveSquare (event) {
            if (capturing) {
                var square = document.getElementById ("square");
                square.style.left = event.clientX + "px";
                square.style.top = event.clientY + "px";
            }
        }
    </script>
</head>
<body onkeydown="ToggleCapture ();"> <br />
    <h3 style="text-align:center">Press any key to toggle capture!</h3>
    While mouse events are captured, the square follows the mouse.
    <div id="square" onmousemove="MoveSquare (event);" onlosecapture="OnLoseCapture ()"></div>
</body>

Copy Code

Preview

Syntax Highlighter

Did you find this example helpful? yes no

Example HTML code 3:

This example shows how to detect when the user presses a mouse button over an element but releases the button outside the element:

<head>
    <script type="text/javascript">
        var capturedButton = null;
        function OnButtonDown (button) {
            capturedButton = button;
            if (window.addEventListener) {  // all browsers except IE before version 9
                window.addEventListener ("mouseup", OnButtonUp, true);
            }
            else {
                if (button.setCapture) {    // IE before version 9
                    button.attachEvent ("onlosecapture", OnButtonLoseCapture);
                    button.setCapture ();
                }
            }
        }
        function OnButtonUp () {
            if (capturedButton) {
                if (window.removeEventListener) {   // all browsers except IE before version 9
                    window.removeEventListener ("mouseup", OnButtonUp, true);
                }
                else {
                    if (capturedButton.releaseCapture) {    // IE before version 9
                        capturedButton.detachEvent ("onlosecapture", OnButtonLoseCapture);
                        capturedButton.releaseCapture ();
                    }
                }
                capturedButton = null;
            }
            alert ("The button has been released!");

        }

        function OnButtonLoseCapture () {
            alert ("The button loses the mouse capture!");
            OnButtonUp ();
        }

        function Init () {
            var button = document.getElementById ("testButton");
            if (button.addEventListener) {  // all browsers except IE before version 9
                button.addEventListener ("mousedown", function () {OnButtonDown (button)}, false);
            }
            else {
                if (button.attachEvent) {   // IE before version 9
                    button.attachEvent ("onmousedown", function () {OnButtonDown (button)});
                    button.attachEvent ("onmouseup", OnButtonUp);
                }
            }
        }
    </script>
</head>
<body onload="Init ()">
    Press the following button and release the mouse button somewhere inside or outside the browser.
    <br />
    <button id="testButton">Capture Test</button>
</body>

Copy Code

Preview

Syntax Highlighter

Did you find this example helpful? yes no

Example HTML code 4:

This example implements a simple spin control:

<head>
    <script type="text/javascript">
        var capturedButton = null;
        var changeTimer = 0;

        function ChangeInput (increase, delay) {
            var myInput = document.getElementById ("myInput");
                // parse the current value
            var value = Number (myInput.value);
            if (isNaN (value)) {
                value = 0;
            }
                // direction
            var dir = increase ? 1 : -1;
                // the new value
            var step = 1;
            value += dir * step;
            if (value < 0) {
                value = 0;
            }
            if (value > 100) {
                value = 100;
            }
            myInput.value = value;

            changeTimer = setTimeout (function () {ChangeInput (increase, 100)}, delay);
        }

        function OnButtonDown (button, increase) {
                // capture mouse up
            capturedButton = button;
            if (window.addEventListener) {  // all browsers except IE before version 9
                window.addEventListener ("mouseup", OnButtonUp, true);
            }
            else {
                if (button.setCapture) {    // IE before version 9
                    button.attachEvent ("onlosecapture", OnButtonLoseCapture);
                    button.setCapture ();
                }
            }

                // initialy a longer delay
            ChangeInput (increase, 500);
        }
        
        function OnButtonUp () {
            if (changeTimer) {
                clearTimeout (changeTimer);
                changeTimer = 0;
            }

            if (capturedButton) {
                if (window.removeEventListener) {   // all browsers except IE before version 9
                    window.removeEventListener ("mouseup", OnButtonUp, true);
                }
                else {
                    if (capturedButton.releaseCapture) {    // IE before version 9
                        capturedButton.detachEvent ("onlosecapture", OnButtonLoseCapture);
                        capturedButton.releaseCapture ();
                    }
                }
                capturedButton = null;
            }
        }

        function OnButtonLoseCapture () {
            OnButtonUp ();
        }

        function Init () {
            var incButton = document.getElementById ("incButton");
            var decButton = document.getElementById ("decButton");
            if (incButton.addEventListener) {   // all browsers except IE before version 9
                incButton.addEventListener ("mousedown", function () {OnButtonDown (incButton, true)}, false);
                decButton.addEventListener ("mousedown", function () {OnButtonDown (decButton, false)}, false);
            }
            else {
                if (incButton.attachEvent) {    // IE before version 9
                    incButton.attachEvent ("onmousedown", function () {OnButtonDown (incButton, true)});
                    decButton.attachEvent ("onmousedown", function () {OnButtonDown (decButton, false)});
                    incButton.attachEvent ("onmouseup", OnButtonUp);
                    decButton.attachEvent ("onmouseup", OnButtonUp);
                }
            }
        }
    </script>
</head>
<body onload="Init ()">
    <input id="myInput" size="3" value="50" />
    <button id="incButton">Increase</button>
    <button id="decButton">Decrease</button>
</body>