Building an Event Example Project

You're now going to learn how to use the MouseMove event by modifying the Picture Viewer project of Hour 3. You're going to make it so that, as a user moves the mouse over a picture, the X and Y coordinates of the cursor are displayed on the form. You'll be using the e parameter to get the coordinate of the mouse pointer.

Creating the User Interface

Start with a copy of the Picture Viewer project that you completed in Hour 3. If you don't have this project, you can download it from my website.

You'll need two label controls on the form; one for the X value and one for the Y value. Label controls are used to display static text; users can't type text into a label. Follow these steps:

1.

Double-click frmViewer.cs in the Solution Explorer to display the form in the designer.

2.

Add a label control to the form by double-clicking the Label tool in the tool-box. Set its properties as follows:

Property	Value
Name	lblX
Location	300, 110
Text	X:

3.

Use the toolbox to add one more Label control to the form. Set its properties as follows:

Property	Value
Name	lblY
Location	300, 125
Text	Y:

Your form should now look like the one in Figure 4.6. It's a good idea to save frequently, so save your project now by clicking the Save All button on the toolbar.

Figure 4.6. Label controls display static text to the user.

Creating Event Handlers

The interface for this example is completenow on to the fun part. You're now going to create the event procedures that empower the program to do something. The first event that we're interested in is the MouseMove event. Follow these steps to create the code:

1.	Click the picture box on the form to select it, and then click the Event button in the Properties Window (the button with the lightning bolt) to view a list of the events supported by the picture box.
2.	Scroll down and locate MouseMove, and then double-click it to create the new MouseMove event (see Figure 4.7). Figure 4.7. Each time you select a new event, Visual C# creates an empty event procedureif one hasn't been created previously for the control.
3.	Enter the following code into the MouseMove event procedure: lblX.Text = "X: " + e.X.ToString(); lblY.Text = "Y: " + e.Y.ToString();

This code is fairly simple, and may already make sense to you. If it's still not clear, it will be soon. Consider the first line (called a statement). lblX.Text is on the left of the = sign, so Text is a property of the label, and we're going to be setting it to some value. The text "X: " is a literal value that we're placing in the Text property of the label control. The reason you include this literal is that when you set the Text property, you completely overwrite the current value of the property. So, even though you entered X: as the property in the properties window, you need to include it when setting the property as well. To make this useful, we also have to include the actual value for X, which is stored in the X property of the e object. Again, we're concatenating the literal value of "X: " with the value stored in e.X; the + sign concatenates two strings. Notice that we use the ToString() method of the X property. This is necessary because Visual C# will only concatenate text (strings), but the X and Y properties hold numbers. The ToString() method converts the number to a string.

The second statement does the same thing, only with the Y value.

The nice thing about objects is that you don't have to commit every detail about them to memory. For example, you don't need to memorize the return values for each type of button (who wants to remember e.X, e.Y, or e.Button anyway?). Just remember that the e parameter contains information about the event. When you type e and press the period, the IntelliSense drop-down list appears and shows you the members of e. Don't feel overwhelmed by all the object references you'll encounter throughout this book. Simply accept that you can't memorize them all, nor do you need to; you'll learn the ones that are important, and you'll use Help when you're stuck. Also, after you know the parent object in a situation (such as the e object in this example), it's easy for you to determine the objects and members that belong to it by using the IntelliSense drop-down lists.

Click Save All in the toolbar now to save your work (you wouldn't want to lose it!). Next, press F5 to run the project now and move the mouse over the picture box. You'll see the coordinates of the pointer (as it relates to the picture box) displayed in the two label controls you created (see Figure 4.8).

Figure 4.8. The MouseMove event makes it easy to track the pointer over a control.

Now, move the mouse pointer off the picture box. Notice that the labels display the last coordinate that the pointer moved over on the picture box. The MouseMove event fires only when the mouse is moved over the control the event is attached to: the picture box in this example. Well, we can't leave those numbers just dangling there can we?

The PictureBox just so happens to have another event we can use to fix this: the MouseLeave event. Oddly enough, the MouseLeave event fires when the mouse leaves the space of the control (yeah, something that's actually intuitive!). Follow these steps to clear the coordinates when the cursor leaves the picture box:

1.	Stop the project if it's still running by closing the Picture Viewer form.
2.	Click the frmViewer.cs [Design] tab to return to the form designer.
3.	Click the picture box (if it's not already selected) to view its events. Locate MouseLeave in the list of events and double-click it to create a new event procedure.
4.	Enter the following code into the MouseLeave event: lblX.Text = ""; lblY.Text = "";

Press F5 to run the project again and move the mouse over the picture box and then off it. Notice that the coordinates go away. Move the pointer over the picture box again, and they reappearperfect! Go ahead and stop the running project now.

There's only one thing left to do. Did you notice that when you first start the project, the labels have "X:" and "Y:" in them? Wouldn't it be better to not display this text until the user mouses over the picture box? You could set the Text properties of these labels to empty using the Properties window. However, if you do this, you won't see the labels on the form in the designer and may place other controls over the top of them. A better solution is to initialize their values when the form first loads. You're going to do just that by following these steps:

1.	Click the frmViewer.cs [Design] once more to return to the form designer.
2.	Click the form to select it and view its events.
3.	In the event list for the picture box, locate the Load event and double-click it to create a new event handler. The Load event executes automatically when the form first loadsthe perfect place to initialize the label controls.
4.	Enter the following two code statements: lblX.Text = ""; lblY.Text = "";

That's ityou're finished! Go ahead and Press F5 to run the project and give it a test drive. When the form first loads, the coordinate labels should be empty (this makes them appear invisible). When you mouse over the picture box, the coordinates are displayed, and when you leave the confines of the picture box, the coordinates are hidden once again. A little bit of code and the right event selection can go a long way.