Working with the Mouse

The mouse communicates with your application through events that are raised as the user interacts with the mouse. As the mouse pointer moves over a control or a form, events are raised to enable you to track the current mouse position. Events are passed only to a single form or control; normally, this is the object that’s located under the mouse pointer. Table 13-1 lists the events related to mouse movement.

Although most of the events listed in Table 13-1 accept EventHandler delegates, the event handler for the MouseMove and MouseWheel events must be an instance of the MouseEventHandler class rather than EventHandler. Instances of the MouseEventHandler delegate are created as shown here:

MouseMove += new MouseEventHandler(form_MouseMove);
private void form_MouseMove(object sender, MouseEventArgs e)
{
   
    

} 

As shown in the preceding example, a method associated with a Mouse­EventHandler delegate accepts a MouseEventArgs reference as its second parameter, instead of a reference to an EventArgs object. The MouseEventArgs class provides additional information about the location and state of the mouse. The MouseEventArgs class exposes the following properties:

• Button  A value from the MouseButtons enumeration that indicates which mouse button was clicked by the user

• Clicks  The number of times the mouse button has been clicked recently

• Delta  The number of positions, or detents, that the mouse wheel has been rotated

• X  The x-coordinate of the mouse, in client coordinates

• Y  The y-coordinate of the mouse, in client coordinates

So what happens if you’re handling an event that provides a simple Event­Args parameter and you need the mouse coordinates? You’re in luck, because the Form class includes the MousePosition property, which returns the current mouse position, as shown here:

private void main_Click(object sender, System.EventArgs e)
{
    Point mousePoint = PointToClient(MousePosition);
    string msg = string.Format("Mouse click at X:{0}, Y:{1}",
                                mousePoint.X,
                                mousePoint.Y);
    MessageBox.Show(msg);
}

The location returned from MousePosition is a Point structure, which consists of the xy-coordinates for a specific location on the desktop. The Point structure returned by MousePosition is relative to the entire screen rather than to the current form or control. The preceding code uses the PointToClient method to transform the location into client coordinates.

The MouseButtons enumeration, shown in Table 13-2, is used to determine the current state of the mouse buttons. Values in the MouseButtons enumeration can be combined as necessary to provide an accurate picture of the mouse state.

The last two entries in Table 13-2 refer to extra buttons that are present on the IntelliMouse Explorer mouse. These mice have five mouse buttons; the two additional XButtons are typically used for navigation.

All of the mouse movement events can be accessed through the Forms Designer’s Properties window, except for the MouseWheel event. In most cases, controls that can be manipulated with the MouseWheel event will already provide default handling for this event. To explicitly handle MouseWheel events, you must manually add an event handler delegate to your form or control, as shown here:

nameListBox.MouseWheel += new MouseEventHandler(list_MouseWheel);
private void list_MouseWheel(object sender, MouseEventArgs e)
{
   
    

}

The most common use of the mouse is for item selection. In most cases, you don’t need to detect mouse clicks directly. Most controls and other objects that accept user input generate Click events, as discussed in Chapter 12. Table 13-3 lists the mouse selection events.

The MouseDown and MouseUp events are associated with Mouse­Event­Handler delegates, which enable them to pass a reference to a MouseEventArgs object as a parameter. The Click and DoubleClick events are associated with Event­Handler delegates, however, and don’t provide any additional information about the mouse position or state.

Although mouse events are raised asynchronously and can come at any time, there’s a guarantee with regard to the relative order of mouse events: The MouseEnter and MouseLeave mouse events bracket other mouse events, such as MouseHover, MouseMove, and any mouse selection events. A Click event occurs only after MouseDown and MouseUp events, and a DoubleClick event occurs only after a Click event.

The companion CD includes MouseEvents, an example project that demonstrates how mouse events are raised and handled. The main form from MouseEvents is shown in Figure 13-1.

Figure 13-1.

The MouseEvents main form.

As you can see, the main form includes a list box control and a label control that are used to display mouse-related events that are handled by the application. The constructor for the main form is shown here:

public MainForm()
{
    InitializeComponent();
    MouseEventHandler wheelHandler = null;
    wheelHandler = new MouseEventHandler(listBox_MouseWheel);
    eventListBox.MouseWheel += wheelHandler;
} 

The call to InitializeComponent was inserted by the Forms Designer to initialize the form and the user interface controls. After the call to InitializeComponent, an event handling delegate is created for the list box’s MouseWheel event. The implementation of the listBox_MouseWheel method that handles the wheel events from the mouse is shown below.

private void listBox_MouseWheel(object sender,
                                MouseEventArgs e)
{
    UpdateEventLabels("(ListBox)MouseWheel", e.X, e.Y, e);
}

When mouse-related events are received by the MouseEvents application, the event handler calls the UpdateEventLabels method, shown here:

private void UpdateEventLabels(string msg,
                               int x,
                               int y,
                               MouseEventArgs e)
{
    string message = string.Format("{0} X:{1}, Y:{2}",
                                    msg,
                                    x,
                                    y);
    positionLabel.Text = message;
    string eventMsg = DateTime.Now.ToShortTimeString();
    eventMsg += " " + message;
    eventListBox.Items.Insert(0, eventMsg);
    eventListBox.TopIndex = 0;

    string mouseInfo;
    if(e != null)
    {
        mouseInfo = string.Format("Clicks: {0}, Delta: {1}, " + 
                                    "Buttons: {2}",
                                    e.Clicks,
                                    e.Delta,
                                    e.Button.ToString());
    }
    else
    {
        mouseInfo = "";
    }
    mouseEventArgsLabel.Text = mouseInfo;
}

The UpdateEventLabels method accepts the following parameters:

• msg  A string that describes the event

• x  The mouse pointer’s x-coordinate

• y  The mouse pointer’s y-coordinate

• e  An optional reference to a MouseEventArgs object

The UpdateEventLabels method uses these parameters to format messages that are displayed in the dialog box. After every mouse-related event, a summary of the event is added to the list box, which is then reset so that the most recent messages are always displayed. The current position of the mouse pointer is displayed in the positionLabel label control. When a reference to a MouseEvent­Args object is passed as a parameter, additional information is displayed in the mouseEventArgsLabel label control.

For events that pass a reference to EventArgs instead of a reference to MouseEventArgs, the MousePosition property is used to specify the current mouse coordinates, as shown here:

private void listBox_MouseEnter(object sender, System.EventArgs e)
{
    Point mousePoint = PointToClient(MousePosition);
    UpdateEventLabels("(ListBox)MouseEnter",
                        mousePoint.X,
                        mousePoint.Y,
                        null);
}

Table 13-4 lists the events that are handled by the MouseEvents application and the controls that handle them.

To use the MouseEvents application, move the mouse pointer over the dialog box and child controls. Messages are generated as the mouse pointer passes over the form and the list box control. When the mouse pointer passes over child controls other than the list box, no messages appear; to see event messages for other child controls, you must add additional event handlers.

There are situations in which you need to know exactly where the mouse pointer is located, even if the mouse events would normally be sent to another form or control. In these cases, such as when you’re performing a drag-and-drop operation, you can capture the mouse pointer, which will result in all mouse events being sent to your form or control. The Capture property is used to capture the mouse pointer as well as to determine whether the mouse is currently captured, as shown here:

if(Capture == false)
{
    Capture = true;
    if(Capture == true)
    {
        // Mouse captured.
        
    

    }
} 

A common way to provide feedback to the user is through the mouse pointer. Because the mouse is often the primary method of user input in a Windows Forms application, altering the shape of the mouse pointer is an effective way to provide immediate feedback to the user. In most cases, the operating system and the .NET Framework will provide a mouse pointer that’s appropriate. For example, the default mouse pointer is normally set to the arrow shape over most controls and forms. The following subsections describe how you can enhance the built-in support within Windows and the .NET Framework to provide additional feedback to users.

Cursor = Cursors.WaitCursor;

Cursor oldCursor = Cursor;

    

Cursor = oldCursor;

smileyCursor = new Cursor("..\\..\\smiley.cur");
Cursor = smileyCursor;

smileyCursor.Dispose();

private void SetSmileyCursor();
{
    Cursor _smileyCursor = new Cursor("..\\..\\smiley.cur");
    Cursor = _smileyCursor;
}

Cursor oldCustomCursor = Cursor;
oldCustomCursor.Dispose();
Cursor = Cursors.Wait;

public class MainForm: System.Windows.Forms.Form
{
    Cursor _handCursor;
    Cursor _embeddedCursor;
    Cursor _smileyCursor;
    
    

    public MainForm()
    {
        
    

        _handCursor = new Cursor(externalHand);
        _embeddedCursor = new Cursor(this.GetType(), "Smiley2.cur");
        _smileyCursor = new Cursor("..\\..\\smiley.cur");
    }
    protected override void Dispose( bool disposing )
    {
        if( disposing )
        {
            if (components != null) 
            {
                components.Dispose();
            }
            _handCursor.Dispose();
            _embeddedCursor.Dispose();
            _smileyCursor.Dispose();
        }
        base.Dispose( disposing );
    }
    
    

} 

private void SetExternalCursor(IntPtr handle)
{
    Cursor externalCursor = new Cursor(handle);
    Cursor = externalCursor;
}

// Platform Invoke method to load 
// a standard mouse pointer using Win32
[DllImport("user32.dll", EntryPoint="LoadCursor")]
private static extern IntPtr InteropLoadCursor(int instance,
                                               int resource);

// From the Platform SDK winuser.h header file
const int IDC_HAND = 32649;

private void externalRadioButton_CheckedChanged(object sender, 
                                                System.EventArgs e)
{
    IntPtr externalHand = InteropLoadCursor(0, IDC_HAND);
    Cursor handCursor = new Cursor(externalHand);
    Cursor = handCursor;
}

public class MainForm: System.Windows.Forms.Form
{
    Cursor _handCursor;
    
    

    public MainForm()
    {
        _handCursor = new Cursor(externalHand);
        
    

    }
    
    

    protected override void Dispose( bool disposing )
    {
        if( disposing )
        {
            if (components != null) 
            {
                components.Dispose();
            }
            _handCursor.Dispose();
        }
        base.Dispose( disposing );
    }
    
    

    private void externalRadioButton_CheckedChanged(object sender, 
                                                    System.EventArgs e)
    {
        Cursor = _handCursor;
    }
    
    

}

Cursor embeddedCursor = new Cursor(this.GetType(), "Smiley2.cur");