JavaScript MouseEvent.buttons Property: Detecting Mouse Buttons Pressed

The MouseEvent.buttons property in JavaScript provides a way to detect which mouse buttons are pressed during mouse events, like mousedown, mouseup, or mousemove. Unlike the MouseEvent.button property, which indicates the single button that triggered the event, buttons provides a bitmask representing all currently pressed buttons. This is particularly useful for handling multi-button interactions. This article will delve into the specifics of this property, show its syntax, provide examples, and offer practical applications.

What is the MouseEvent.buttons Property?

The MouseEvent.buttons property returns a numerical value representing a bitmask of mouse buttons currently pressed. This is useful for detecting scenarios where multiple mouse buttons are held down, allowing for the implementation of complex mouse interactions such as multi-button gestures, advanced drawing tools, and more.

Purpose of the MouseEvent.buttons Property

The primary purpose of the buttons property is to:

• Detect which mouse buttons are pressed during a mouse event.
• Handle multi-button interactions, such as drawing tools that use multiple buttons.
• Implement more advanced mouse gestures and control schemes.

Syntax of MouseEvent.buttons

The syntax is quite simple:

event.buttons

Where event is a MouseEvent object. The returned value is an integer bitmask, where each bit represents a specific button. The values for each button are represented as follows:

Value	Button	Description
0	None	No button is pressed.
1	Left Button	The primary mouse button (usually the left button) is pressed.
2	Right Button	The secondary mouse button (usually the right button) is pressed.
4	Middle Button	The auxiliary button (usually the middle or wheel button) is pressed.
8	Button 4	Typically a browser back button or similar additional button.
16	Button 5	Typically a browser forward button or similar additional button.
Other Values	Combination	A combination of the above buttons may be pressed. The value is the sum of the individual values, e.g., left and right button will be 3 (1+2).

To check if a particular button is pressed, you can use bitwise operations with these values.

Examples

Let’s delve into a few examples to understand how the MouseEvent.buttons property works.

Example 1: Displaying Pressed Buttons

This example demonstrates how to detect and display the buttons currently pressed during a mousemove event on a canvas.

<canvas id="mouseCanvas1" width="300" height="150" style="border: 1px solid black;"></canvas>
<div id="mouseButtonsInfo1"></div>

<script>
    const canvas_mouse1 = document.getElementById('mouseCanvas1');
    const infoDiv1 = document.getElementById('mouseButtonsInfo1');

    canvas_mouse1.addEventListener('mousemove', function(event) {
      const buttonsPressed = event.buttons;
      let buttonNames = [];
      if (buttonsPressed === 0) {
        buttonNames.push("None");
      }
      if (buttonsPressed & 1) {
          buttonNames.push("Left Button");
      }
      if (buttonsPressed & 2) {
        buttonNames.push("Right Button");
      }
      if (buttonsPressed & 4) {
        buttonNames.push("Middle Button");
      }
        if (buttonsPressed & 8) {
            buttonNames.push("Button 4");
        }
         if (buttonsPressed & 16) {
            buttonNames.push("Button 5");
         }
      infoDiv1.textContent = "Pressed buttons: " + buttonNames.join(', ');
    });
</script>

Explanation:

• The script listens for mousemove events on the canvas element.
• It retrieves the event.buttons value and checks for each button using bitwise AND (&).
• The corresponding button names are added to an array and displayed in the info div.

Example 2: Implementing Multi-Button Drawing

Here is an example that shows a basic drawing application that uses the left button for drawing and the right button to change color.

<canvas id="mouseCanvas2" width="300" height="150" style="border: 1px solid black;"></canvas>
<script>
  const canvas_mouse2 = document.getElementById('mouseCanvas2');
  const ctx_mouse2 = canvas_mouse2.getContext('2d');
  let isDrawing2 = false;
  let drawColor2 = 'black';

  canvas_mouse2.addEventListener('mousedown', function(event) {
    if (event.buttons === 1) { // Left button
      isDrawing2 = true;
      ctx_mouse2.beginPath();
      ctx_mouse2.moveTo(event.offsetX, event.offsetY);
    } else if (event.buttons === 2) { // Right button
        drawColor2 = 'red';
    }
  });

  canvas_mouse2.addEventListener('mousemove', function(event) {
    if (isDrawing2) {
      ctx_mouse2.lineTo(event.offsetX, event.offsetY);
      ctx_mouse2.strokeStyle = drawColor2;
      ctx_mouse2.stroke();
    }
  });

  canvas_mouse2.addEventListener('mouseup', function(event) {
     isDrawing2 = false;
  });

  canvas_mouse2.addEventListener('contextmenu', function(event){
        event.preventDefault(); // prevent the default right click menu
  });
</script>

Explanation:

• The code listens for mousedown events to start drawing when the left button is pressed or change drawing color to red when the right button is pressed.
• On mousemove, if drawing is enabled (isDrawing is true), it draws lines with current drawColor.
• Drawing stops when the mouse button is released via the mouseup event listener.
• The default context menu is disabled to prevent the browser’s default right click actions.

Example 3: Combining Buttons for Actions

This example uses the left button for drawing, the middle button for erasing, and both left and right buttons together to change to a different color:

<canvas id="mouseCanvas3" width="300" height="150" style="border: 1px solid black;"></canvas>
<script>
    const canvas_mouse3 = document.getElementById('mouseCanvas3');
    const ctx_mouse3 = canvas_mouse3.getContext('2d');
    let isDrawing3 = false;
    let drawMode3 = 'draw';
    let color3 = 'black';

    canvas_mouse3.addEventListener('mousedown', function(event) {
      if (event.buttons === 1) { // Left button
        isDrawing3 = true;
        drawMode3 = 'draw';
        ctx_mouse3.beginPath();
        ctx_mouse3.moveTo(event.offsetX, event.offsetY);
      } else if (event.buttons === 4) { // Middle button
            isDrawing3 = true;
            drawMode3 = 'erase';
            ctx_mouse3.beginPath();
            ctx_mouse3.moveTo(event.offsetX, event.offsetY);
      } else if (event.buttons === 3) { // Left & Right buttons
            color3 = 'blue';
      }
    });

    canvas_mouse3.addEventListener('mousemove', function(event) {
        if(isDrawing3){
            ctx_mouse3.lineTo(event.offsetX, event.offsetY);
            ctx_mouse3.strokeStyle = color3;
            if(drawMode3 === 'erase'){
                ctx_mouse3.globalCompositeOperation = 'destination-out';
                ctx_mouse3.lineWidth = 20;
            } else {
                ctx_mouse3.globalCompositeOperation = 'source-over';
                ctx_mouse3.lineWidth = 1;
            }
            ctx_mouse3.stroke();
        }
    });

    canvas_mouse3.addEventListener('mouseup', function(event) {
      isDrawing3 = false;
    });

    canvas_mouse3.addEventListener('contextmenu', function(event){
        event.preventDefault(); // prevent the default right click menu
    });
</script>

Explanation:

• It starts drawing with a black line on left click, with a normal source-over global composite operation.
• It uses middle button to erase with destination-out composite operation making it looks like erasing.
• Holding both left and right button will change the drawing color to blue.
• It prevent the default browser’s right click menu.

Real-World Applications

The MouseEvent.buttons property has several real-world applications:

• Advanced Drawing Tools: Implementing drawing or painting applications that use multiple buttons for different tools or actions.
• Gaming Controls: Developing in-browser games where multiple buttons are pressed to perform complex actions or movements.
• CAD/CAM Software: Building web-based CAD or CAM software where different mouse button combinations trigger different commands or transformations.
• Interactive Data Visualization: Creating interactive data visualization tools that allow users to manipulate data points or elements using multiple buttons.

Important Notes

• The buttons property provides a bitmask, so bitwise operations are necessary to check if specific buttons are pressed.
• The values for the buttons may differ slightly on different browsers, but the basic left (1), right (2), and middle (4) buttons are generally consistent.
• Always handle contextmenu events with event.preventDefault() to prevent default browser actions when using the right mouse button.
• The buttons property is available on all MouseEvent types including mousedown, mouseup, mousemove and mouseover.

Browser Support

The MouseEvent.buttons property is widely supported across modern browsers, including:

• Chrome
• Firefox
• Safari
• Edge
• Opera

Note: It is always advisable to test your code in different browsers to ensure full compatibility. 🧪

Conclusion

The MouseEvent.buttons property offers a powerful way to handle mouse interactions and implement sophisticated features in your web applications. Understanding how this property works, and using it with bitwise operations, you can create a rich user experience with complex mouse gestures and controls. This article has detailed the usage and provided examples to help you incorporate this property into your projects. Happy coding!