Mouse-Event Handling

This section explains how to handle mouse events, such as clicks, presses and moves, which are generated when the user interacts with a control via the mouse. Mouse events can be handled for any control that derives from class System.Windows.Forms.Control. For most mouse events, information about the event is passed to the event-handling method through an object of class MouseEventArgs, and the delegate used to create the mouseevent handlers is MouseEventHandler. Each mouse-event-handling method for these events requires an object and a MouseEventArgs object as arguments.

Class MouseEventArgs contains information related to the mouse event, such as the mouse pointer's x- and y-coordinates, the mouse button pressed (Right, Left or Middle) and the number of times the mouse was clicked. Note that the x- and y-coordinates of the MouseEventArgs object are relative to the control that generated the eventi.e., point (0,0) represents the upper-left corner of the control where the mouse event occurred. Several common mouse events are described in Fig. 13.37.

Figure 13.37. Mouse events and event arguments.

Mouse events and event arguments
Mouse Events with Event Argument of Type EventArgs
MouseEnter	Occurs when the mouse cursor enters the control's boundaries.
MouseLeave	Occurs when the mouse cursor leaves the control's boundaries.
Mouse Events with Event Argument of Type MouseEventArgs
MouseDown	Occurs when a mouse button is pressed while the mouse cursor is within a control's boundaries.
MouseHover	Occurs when the mouse cursor hovers within the control's boundaries.
MouseMove	Occurs when the mouse cursor is moved while in the control's boundaries.
MouseUp	Occurs when a mouse button is released when the cursor is over the control's boundaries.
Class MouseEventArgs Properties
Button	Specifies which mouse button was pressed (Left, Right, Middle or none).
Clicks	The number of times that the mouse button was clicked.
X	The x-coordinate within the control where the event occurred.
Y	The y-coordinate within the control where the event occurred.

Figure 13.38 uses mouse events to draw on a Form. Whenever the user drags the mouse (i.e., moves the mouse while a mouse button is pressed), small circles appear on the Form at the position where each mouse event occurs during the drag operation.

Figure 13.38. Using the mouse to draw on a Form.

 1 // Fig 13.38: PainterForm.cs
 2 // Using the mouse to draw on a Form.
 3 using System;
 4 using System.Drawing;
 5 using System.Windows.Forms;
 6
 7 // creates a Form that is a drawing surface
 8 public partial class PainterForm : Form
 9 {
10 bool shouldPaint = false; // determines whether to paint
11
12 // default constructor
13 public PainterForm()
14 {
15 InitializeComponent();
16 } // end constructor
17
18 // should paint when mouse button is pressed down
19 private void PainterForm_MouseDown( object sender, MouseEventArgs e )
20 {
21 // indicate that user is dragging the mouse
22 shouldPaint = true; 
23 } // end method PainterForm_MouseDown
24
25 // stop painting when mouse button is released
26 private void PainterForm_MouseUp( object sender, MouseEventArgs e )
27 {
28 // indicate that user released the mouse button
29 shouldPaint = false; 
30 } // end method PainterForm_MouseUp

31 32 // draw circle whenever mouse moves with its button held down 33 private void PainterForm_MouseMove( object sender, MouseEventArgs e ) 34 { 35 if ( shouldPaint ) // check if mouse button is being pressed 36 { 37 // draw a circle where the mouse pointer is present 38 Graphics graphics = CreateGraphics(); 39 graphics.FillEllipse( 40 new SolidBrush( Color.BlueViolet ), e.X, e.Y, 4, 4 ); 41 graphics.Dispose(); 42 } // end if 43 } // end method PainterForm_MouseMove 44 } // end class PainterForm

In line 10, the program declares variable shouldPaint, which determines whether to draw on the Form. We want the program to draw only while the mouse button is pressed (i.e., held down). Thus, when the user clicks or holds down a mouse button, the system generates a MouseDown event, and the event handler (lines 1923) sets shouldPaint to true. When the user releases the mouse button, the system generates a MouseUp event, shouldPaint is set to false in the PainterForm_MouseUp event handler (lines 2630) and the program stops drawing. Unlike MouseMove events, which occur continuously as the user moves the mouse, the system generates a MouseDown event only when a mouse button is first pressed and generates a MouseUp event only when a mouse button is released.

Whenever the mouse moves over a control, the MouseMove event for that control occurs. Inside the PainterForm_MouseMove event handler (lines 3343), the program draws only if shouldPaint is true (i.e., a mouse button is pressed). Line 38 calls inherited Form method CreateGraphics to create a Graphics object that allows the program to draw on the Form. Class Graphics provides methods that draw various shapes. For example, lines 3940 use method FillEllipse to draw a circle. The first parameter to method FillEllipse in this case is an object of class SolidBrush, which specifies the solid color that will fill the shape. The color is provided as an argument to class SolidBrush's constructor. Type Color contains numerous predefined color constantswe selected Color.BlueViolet. FillEllipse draws an oval in a bounding rectangle that is specified by the x- and y-coordinates of its upper-left corner, its width and its heightthe final four arguments to the method. The x- and y-coordinates represent the location of the mouse event and can be taken from the mouse-event arguments (e.X and e.Y). To draw a circle, we set the width and height of the bounding rectangle so that they are equalin this example, both are 4 pixels. Graphics, SolidBrush and Color are all part of the namespace System.Drawing. We discuss class Graphics and its methods in depth in Chapter 17.