HOUR 4 Understanding Events

HOUR 4 Understanding Events It s fairly easy to produce an attractive interface for an application using Visual Basic.NET s integrated design tools. You can create beautiful forms that have buttons to click, text boxes in which to type information, picture boxes that display pictures, and many other creative and attractive elements with which users can interact. However, that s just the start of producing a Visual Basic program. In addition to designing an interface, you have to empower your program to perform actions in response both to how a user interacts with the program and how Windows interacts with the program. This is accomplished by using events. In the previous hour, you learned about objects and their members notably, properties and methods. In this hour, you ll learn about object events and event-driven programming, and you ll learn how to use events to make your applications responsive. The highlights of this hour include Understanding event-driven programming Triggering events Avoiding recursive events Accessing an object s events

82 Hour 4 Working with event parameters Creating event handlers Keeping event names current Understanding Event-Driven Programming With traditional programming languages (often referred to as procedural languages), the program itself fully dictates what code is executed as well as when it s executed. When you start such a program, the first line of code in the program executes, and the code continues to execute in a completely predetermined path. The execution of code might branch and loop on occasion, but the execution path is completely determined by the program. This often meant that a program was quite restricted in how it could respond to the user. For example, the program might expect text to be entered into controls on the screen in a predetermined order. This is quite unlike a Windows application in which a user can interact with different parts of the interface often in any order the user chooses. Visual Basic.NET incorporates an event-driven programming model. Eventdriven applications aren t bound by the constraints of procedural programs. Instead of the top-down approach of procedural languages, event-driven programs have logical sections of code placed within events. There s no predetermined order in which events occur; the user often has complete control over what code is executed in an eventdriven program by interactively triggering specific events, such as by clicking a button. An event, along with the code it contains, is called an event procedure. NEW TERM Triggering Events In the previous hour, you learned that a method is simply a function of an object. Events, in a sense, are really a special kind of method used by an object to signal state changes that might be useful to clients (code using the object). In fact, the Visual Basic.NET documentation refers to events as methods quite frequently (something that will no doubt cause a lot of confusion). Events are methods that can be called in special ways usually by the user interacting with something on a form or by Windows itself rather than being called from a statement in your code. There are many types of events and many ways to trigger those events. You ve already seen how a user can trigger the event of a button by clicking it. User interaction isn t the only thing that can trigger an event; an event can be triggered in one of the following four ways: Users can trigger events by interacting with your program. Objects can trigger their own events, as needed.

Understanding Events 83 The operating system (whichever version of Windows the user is running) can trigger events. You can trigger events by calling them using Visual Basic code. Events Triggered Through User Interaction The most common way an event is triggered is by a user interacting with a program. Every form, and almost every control you can place on a form, has a set of events specific to its object type. For example, the Button control has a number of events, including the Click event that you ve already used in previous hours. The Click event is triggered, and then the code within the Click event executes when the user clicks the button. The Textbox control enables users to enter information using the keyboard, and it also has a set of events. The Textbox control has some of the same types of events as the Button control, such as a Click event, but the Textbox control also has events not supported by the Button control, such as the TextChanged event. The TextChanged event occurs each time the contents of the text box changes, such as when the user types information into the text box. Because you can t enter text into a Button control, it makes sense that the Button control doesn t have a TextChanged event. Every object that supports events supports a unique set of events. Each type of event has its own behavior, and it s important to understand the events you work with. The TextChanged event, for example, exhibits a behavior that might not be intuitive to a new developer because the event fires each time the contents of the text box change. If you were to type the following sentence into an empty text box: 4 Visual Basic.Net is very cool! the TextChanged event would be triggered 30 times once for each character typed because each time you enter a new character, the contents of the text box are changed. Although it s easy to think that the Change event fires only when you commit your entry, such as by leaving the text box or pressing Enter, this isn t how it works. Again, it s important to learn the nuances and the exact behavior of the events you re using. If you use events without fully understanding how they work, your program might exhibit unusual, and often undesirable, results. Triggering events (which are just a type of procedure) using Visual Basic code is discussed in detail in Hour 10, Creating and Calling Code Procedures.

84 Hour 4 Events Triggered by an Object Sometimes an object triggers its own events. The most common example of this is the Timer control s Timer event. The Timer control doesn t appear on a form when the program is running; it appears only when you re designing a form. The Timer control s sole purpose is to trigger its Timer event at an interval that s specified in its Interval property. By setting the Timer control s Interval property, you control the interval (in milliseconds) at which the Timer event executes. After firing its Timer event, a Timer control resets itself and fires its Timer event again when the interval has passed. This occurs until the interval is changed, the Timer control is disabled, or the Timer control s form is unloaded. A common use of timers is to create a clock on a form. You can display the time in a label and update the time at regular intervals by placing the code to display the current time in the Timer event. You ll create a project with a Timer control in Hour 8, Using Advanced Controls. Events Triggered by the Operating System The third way an event can be triggered is by Windows itself. Often, you might not even realize these events exist. For example, when a form is fully or partially obstructed by another window, the program needs to know when the offending window is resized or moved so that it can repaint the area of the window that s hidden. Windows and Visual Basic.NET work together in this respect. When the obstructing window is moved or resized, Windows tells Visual Basic.NET to repaint the form, which Visual Basic.NET does. This also causes Visual Basic.NET to raise the form s Paint event. You can place code into the Paint event to create a custom display for the form, such as drawing shapes on the form using a Graphics object. By doing so, every time the form repaints itself, your custom drawing code executes. Avoiding Recursive Events You must make sure never to cause an event to endlessly trigger itself. An event that continuously triggers itself is called a recursive event. To illustrate a situation that causes a recursive event, think of the Textbox control s TextChanged event discussed earlier. The TextChanged event fires every time the text within the text box changes. Placing code into the TextChanged event that alters the text within the text box causes the Change event to be fired again, which could result in an endless loop. Recursive events terminate when Windows returns a StackOverflow exception (see Figure 4.1), indicating that Windows no longer has the resources to follow the recursion. NEW TERM

Understanding Events 85 FIGURE 4.1 When you receive a StackOverflow exception, you should look for a recursive event as the culprit. Recursive behavior can occur with more than one event in the loop. For example, if Event A triggers Event B, which in turn triggers Event A, you can have infinite looping of the two events. Recursive behavior can take place among a sequence of many events, not just one or two. Uses for recursive procedures actually exist, such as when writing complex math functions. For instance, recursive events are often used to compute factorials. However, when you purposely create a recursive event, you must ensure that the recursion isn t infinite. Accessing an Object s Events Accessing an object s events is simple, and if you ve been following the examples in this book, you ve already accessed a number of objects default events. To access an object s events, you double-click the object in Form Design view. 4 You re now going to create a project to get the feel for working with events. Start Visual Basic.NET, create a new Windows Application project titled View Events, and then follow these steps: 1. Change the name of the default form to fclsviewevents and change the Text property to View Events Example. 2. Make this form the Startup object by right-clicking View Events in the Solution Explorer window, choosing Properties, and then selecting fclsviewevents from the Startup object drop-down list. Click OK to close the dialog box. 3. Use the toolbox to add a picture box to the form. 4. Change the name of the picture box to pictext, and then double-click the picture box to access its event procedures. Your screen should look like the one in Figure 4.2. Notice the two drop-down lists at the top of the code window: One contains the word pictext and the other reads Click. The drop-down list on the left contains a list of all the objects of the current form (including

86 Hour 4 the form and its controls), whereas the list on the right contains all the events for the object selected in the first drop-down list. FIGURE 4.2 Event procedures are created using the events drop-down list in the code editor. Currently, you re viewing the Click event for the pictext object. The cursor is placed within the Click event procedure, ready for you to enter code. The code statement above the cursor is the event declaration. An event declaration is a statement that defines the structure of an event. Notice that this event declaration contains the name of the object, an underscore character (_), and then the event name. Following the event name is a set of parentheses. The items within the parentheses are called parameters, which are the topic of the next section. This is the standard declaration structure for an event procedure. NEW TERM Click the events drop-down list (the list on the right), and take a look at all the events that the picture box supports. Select MouseDown from the list and notice how your Code window changes to look like the one shown in Figure 4.3. When you select an event from the list, Visual Basic.NET creates a new event procedure for that event. The full event declaration is shown here: Protected Sub pictext_mousedown(byval sender As System.Object, _ ByVal e As System.WinForms.MouseEventArgs)

Understanding Events 87 FIGURE 4.3 Visual Basic.NET creates an empty event procedure the first time you select an object s event. Notice that the new event declaration is similar to the first one in the window in that it s titled with the object s name followed by an underscore. However, the remainder of the event procedure declaration is different. It s the name of the event in this case, MouseDown. 4 The words Protected and Sub are Visual Basic.NET reserved words that indicate the scope and type of the procedure. Scope and type are discussed in Hour 10. Working with Event Parameters As mentioned previously, the items within the parentheses of an event declaration NEW TERM are called parameters. An event parameter is a variable that s created and assigned a value by Visual Basic.NET. These parameter variables are used to get, and sometimes set, relevant information within the event. This data may be text, a number, an object almost anything. Multiple parameters within an event procedure are always separated by commas. As you can see, the MouseDown event has two parameters. When the event procedure is triggered, Visual Basic automatically creates the parameter variables and assigns them values for use in this single execution of the event procedure; the next time the event procedure occurs, the values in the parameters are reset. You use the values in the parameters to make decisions or perform operations in your code.

88 Hour 4 The MouseDown event of a form has the following parameters: ByVal sender As System.Object and ByVal e As System.WinForms.MouseEventArgs For now, ignore the ByVal keywords. These are discussed in Hour 11, Using Constants, Data Types, Variables, and Arrays. The text following ByVal is the name of the parameter, and the string after the word As indicates the type of data the parameter contains. The first parameter, sender, holds a generic object. Object parameters can be any type of object supported by Visual Basic.NET. It s not critical that you understand data types right now, just be aware that different parameter variables contain different types of information. Some contain text, others contain numbers, and still others (many others) contain objects. In the case of the sender parameter, it will always hold a reference to the control causing the event. NEW TERM The e parameter of the MouseDown event, on the other hand, is where the real action is. The e parameter also holds an object, and in this case the object is System.WinForms.MouseEventArgs. This object has properties that relate to the MouseDown event. To see them, type in the following code, but don t press anything after entering the dot (period): e. When you press the period, you ll get a drop-down list showing you the members (properties and methods) of the e object (see Figure 4.4). Using the e object, you can determine a number of things about the occurrence of the MouseDown event. I ve listed some of the more interesting items in Table 4.1. TABLE 4.1 Property Clicks Button X Y Commonly Used Members of System.WinForms.MouseEventArgs Description Returns the number of times the user clicked the mouse button Returns the button that was clicked (left, middle, right) Returns the horizontal coordinate at which the pointer was located when the user clicked Returns the vertical coordinate at which the pointer was located when the user clicked

Understanding Events 89 FIGURE 4.4 IntelliSense drop-down lists alleviate the need for memorizing the make up of hundreds of objects. Each time the event occurs, the parameters are initialized by Visual Basic.NET so that they always reflect the current occurrence of the event. 4 Each event has parameters specific to it. For instance, the TextChanged event returns parameters that are different from the MouseDown event. As you work with events and you ll work with a lot of events you ll quickly become familiar with the parameters of each event type. You ll learn how to create parameters for your own functions and procedures in Hour 10. Building an Event Example Project You re now going to create a very simple project in which you ll use the event procedures of a text box. Specifically, you re going to write code to display a message when a user presses a mouse button on the text box, and code to clear the text box when the user releases the button. You ll be using the e parameter to determine which button the user has pressed. Creating the User Interface Create a new Windows application titled Events Example. Change the name of the default form to fclseventsexample and set the form s Text property to Events example.

90 Hour 4 Next, make this form the Startup object by right-clicking Events Example in the Solution Explorer window, choosing Properties, and then selecting fclseventsexample from the Startup object drop-down list. Add a text box to the form by double-clicking the TextBox tool in the toolbox. Set its properties as follows: Property Name Value txtevents Location 48,120 Size 193,20 Text Click Me! The only other control you need on your form is a Label. Label controls are used to display static text; users can t type text into a label. Add a new label to your form now by double-clicking the Label tool in the toolbox and then set the Label control s properties as follows: Property Name Value lblmessage Location 48,152 Size 192,16 Text (make blank) Your form should now look like the one in Figure 4.5. It s a good idea to save frequently, so save your project now by clicking the Save All button on the toolbar. Creating Event Handlers The interface for the Events Example project is complete on to the fun part. You re now going to create the event procedures that empower the program to do something. The event that we re interested in first is the MouseDown event. Double-click the text box on the form to access its event procedures. When you double-click a control, the event procedure that s created is always for the default event for the type of control. For text boxes, this is the TextChanged event. You re not interested in the TextChanged event at this time, however. Open the event list (the drop-down list in the upper-right), and then locate and select MouseDown. Visual Basic creates a new MouseDown procedure for the text box (see Figure 4.6).

Understanding Events 91 FIGURE 4.5 A Label control that has an empty Text property can be hard to see unless it s selected. FIGURE 4.6 Each time you select a new event, Visual Basic creates an empty event procedure if one hasn t been created previously for the control. 4 Notice that Visual Basic.NET left the default event procedure it created for you. It s best not to leave dead code (code that isn t used), so delete the TextChanged event procedure now. To fully delete the event procedure, you must delete all the following code:

92 Hour 4 Protected Sub txtevents_textchanged(byval sender As Object, _ ByVal e As System.EventArgs) End Sub After you ve deleted the dead procedure, place the cursor on the line between the Private Sub and End Sub statements of the txtevents_mousedown procedure. Enter the following code into the MouseDown event procedure: Select Case e.button Case MouseButtons.Left lblmessage.text = You are pressing the left button! Case MouseButtons.right lblmessage.text = You are pressing the right button! Case MouseButtons.Middle lblmessage.text = You are pressing the middle button! End Select The Select Case construct, which is discussed in detail in Hour 13, Making Decisions in Visual Basic Code, compares the value of an expression to a list of possible values. In this instance, the expression is the value of e.button (the Button property of the object e). When this code executes, the expression is compared to each Case statement in the order in which the statements appear. If and when a match is found, the code immediately following the Case statement that was matched gets executed. In a nutshell, the code you wrote looks at the value of e.button and compares it to three values one at a time. When the Select Case construct concludes which button has been pressed, it displays a message about it in the Label control. In a more robust application, you would probably execute more useful and more complicated code. For example, you might want to display a custom pop-up menu when the user clicks with the right button, and perhaps execute a specific function when the user clicks with the middle button. All of this and more this is possible. 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 MouseButtons.Left 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, one of which is Button. If you select Button and press a space followed by an equal sign, you ll see another drop-down list showing you the possible values of Buttons (you saw this when you entered the code for this procedure). This behavior manifests itself in many ways. For example, each time that you typed the word Case and pressed the spacebar when

Understanding Events 93 entering this code, you received a drop-down list showing you possible values. Visual Basic can do this because it knows that the Case statement must evaluate to a value of e.buttons. 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. You re now going to add code to the MouseUp event to clear the label s Text property when the user releases the button. First, you ll need to create the MouseUp event procedure. To do this, choose MouseUp from the events drop-down list. All you re going to do in the MouseUp event is clear the Label control. Enter the following code: lblmessage.text = Testing Your Events Project Run your project now by pressing F5. If you entered all the code correctly and you don t receive any errors, your form will be displayed as shown in Figure 4.7). 4 FIGURE 4.7 A simple but functional example. Click the text box with the left mouse button and watch the label. It will display a sentence telling you that the left button was clicked. When you release the button, the text is cleared. Try this with the middle and right buttons as well. When you click the text box with the right button, Windows displays the standard shortcut menu for text boxes. When this menu appears, you have to select something from it or click somewhere off the menu to trigger the MouseUp event. In Hour 9, Adding Menus and Toolbars to Forms, you ll

94 Hour 4 learn how to add your own shortcut menus to forms and controls. When you re satisfied that your project is behaving as it should, choose Stop Debugging from the Debug menu or toolbar to stop the project (or click the Close button on your form). Be sure to save your work by clicking Save All on the toolbar. Keeping Event Names Current If you ve used any version of Visual Basic prior to.net, you ve undoubtedly experienced orphaned events. As you now know, the name of an event procedure is defined by the control s name followed by an underscore and then the event name (such as txtaddress_textchanged). When you change the name of a control, Visual Basic doesn t change the control s event declarations to reflect the new name, but it does keep the event attached to the control. The way this works is that at the end of each event declaration is the keyword Handles, followed by an object name. The Handles keyword effectively hooks up an event handler to the event of a control. When you change the name of a control, Visual Basic.NET changes the Handles reference, but it doesn t change the event name. Although your code will work, you should manually change the name of the corresponding procedures so that they match the new name of the control; this will help a lot when debugging complicated code. Summary In this hour, you learned about event-driven programming, including what events are, how to trigger events, and how to avoid recursive events. In addition, you learned how to access an object s events and how to work with parameters. Much of the code you ll write will execute in response to an event of some kind. By understanding how events work, including being aware of the available events and their parameters, you ll be able to create complex Visual Basic.NET programs that react to a multitude of user and system input. Q&A Q Is it possible to create custom events for an object? A Yes, you can create custom events for your own objects (which you ll learn about in Hour 16, Designing Objects Using Classes ), and you can also create them for existing objects. Creating custom events, however, is beyond the scope of this book.

Understanding Events 95 Q Is it possible for objects that don t have an interface to support events? A Yes. However, to use the events of such an object, the object variable must be dimensioned a special way or the events aren t available. This gets a little tricky and is beyond the scope of this book. If you have an object in code that supports events, look in Help for the keyword WithEvents for information on how to use such events. Workshop The Workshop is designed to help you anticipate possible questions, review what you ve learned, and get you thinking about how to put your knowledge into practice. The answers to the quiz are in Appendix B, Answers to the Quizzes. Quiz 1. Name three things that can cause events to occur. 2. True or False: All objects support the same set of events. 3. What is the default event type for a button? 4. Writing code in an event that causes that same event to be triggered, setting off a chain reaction with the event triggered again and again is called what? 5. What is the easiest way to access a control s default event handler? 6. All control events pass a reference to the control causing the event. What is the name of the parameter that holds this reference? 7. What should you do when you change the name of a control? 4 Exercises 1. Create a project with a single picture box and a text box. In the MouseDown event of the picture box, show the coordinate of the mouse in the text box. (Hint: Use the E parameter in the MouseDown event to get the coordinates.) 2. Create a project with a form and a text box. Add code to the TextChange event to cause a recursion when the user types in text. Hint: Concatenate a character to the end of the user s text using a statement such as txtmytextbox.text = txtmytextbox.text & a ; The ampersand tells Visual Basic.NET to add the letter a to the end of the existing text box contents.