Section 13.11. Mouse-Event Handling

13.11. 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 mouse-event 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 eventthat is point (0,0) represents the upper-left corner of the control where the mouse event occurred. Several common mouse events are described in Figure 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 within the control's boundaries.
Class MouseEventArgs Properties
Button	Specifies which mouse button was pressed (Left, Right, Middle or none).
Clicks	The number of times 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: FrmPainter.vb  2  ' Using the mouse to draw on a Form.  3  Public Class FrmPainter  4     Private shouldPaint As Boolean = False ' determines whether to paint  5  6     ' should paint when mouse button is pressed down  7     Private Sub FrmPainter_MouseDown(ByVal sender As System.Object, _  8        ByVal e As System.Windows.Forms.MouseEventArgs) _  9        Handles MyBase.MouseDown 10        shouldPaint = True 11     End Sub ' FrmPainter_MouseDown 12 13     ' stop painting when mouse button is released 14     Private Sub FrmPainter_MouseUp(ByVal sender As System.Object, _ 15        ByVal e As System.Windows.Forms.MouseEventArgs) _ 16        Handles MyBase.MouseUp 17        shouldPaint = False 18     End Sub ' FrmPainter_MouseUp 19 20     ' draw circle whenever mouse moves with its button held down      21     Private Sub FrmPainter_MouseMove(ByVal sender As System.Object, _ 22        ByVal e As System.Windows.Forms.MouseEventArgs) _              23        Handles MyBase.MouseMove                                       24        ' check if mouse button is being pressed                       25        If (shouldPaint) Then                                          26           ' draw a circle where the mouse pointer is present           27           Dim g As Graphics = CreateGraphics()                        28           g.FillEllipse( _                                            29              New SolidBrush(Color.BlueViolet), e.X, e.Y, 4, 4)        30           g.Dispose()                                                 31        End If                                                         32     End Sub ' FrmPainter_MouseMove                                    33  End Class ' FrmPainter 

Line 4 declares variable shouldPaint, which determines whether to draw on the Form. We want 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 FrmPainter_MouseDown (lines 711) sets shouldPaint to true. When the user releases the mouse button, the system generates a MouseUp event, shouldPaint is set to False in the FrmPainter_MouseUp event handler (lines 1418) 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 FrmPainter_MouseMove event handler (lines 2132), the program draws only if shouldPaint is TRue (i.e., a mouse button is pressed). Line 27 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 2829 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 many 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. Line 30 invokes the Graphics object's Dispose method to return the Graphics object's resources back to the system. Graphics, SolidBrush and Color are all part of the System.Drawing namespace. We discuss class Graphics and its methods in depth in Chapter 17, Graphics and Multimedia.