information about the event.

I wanted to copy the value the user typed to lblPress. The code is simplistic:

private void KeyReader_KeyPress(object sender, System.Windows.Forms.KeyPressEventArgs e) {

lblPress.Text = "Press: " + Convert.ToString(e.KeyChar);

}// End KeyPress

e.KeyChar refers to one of the properties of the KeyPressEventArgs object. The KeyChar property returns the key the user just tried to type. KeyPress events are good at retrieving the same kinds of values you might see in a text box (although one at a time). You cannot use the KeyPress event to look for control keys, arrow keys, or function keys. These keys simply do not trigger the KeyPress event, so you can’t use a KeyPress() method to look for them.

In the Real World

After all the advice about long, descriptive variable names, you might wonder why a variable as important as the KeyPressEventArgs has a name like e. I can’t be sure what was happening in Redmond, Washington, when the C# developers were planning their language, but this is one of several areas where C# looks suspiciously like another language, called Java. Most event handlers in Java pass an event object named e (for event). In C#, it isn’t called an event object, but the variable is used in exactly the same way and is still named e. Certainly, the key people involved in the development of C# were aware of Java, and most were probably fluent in the language. It’s not surprising that many of Java’s best ideas found their way into C#—but maybe I’m being cynical. Maybe e is shorthand for KeyPressEventArgs.

Trick The KeyPress event is great when you want to watch what the user is typing. For example, you might have a text box where you want the user to enter only numbers. You can use the KeyPress() method to check each key as it is pressed and ensure that it is a number. The Backspace key, arrow keys, Alt key, Ctrl key, and Shift key should operate normally in these situations, without triggering the KeyPress event.

The e.KeyChar property returns a variable of the char type, described briefly in Chapter 2, "Branching and Operators: The Math Game." A char contains only one letter. chars aren’t very useful on their own, so usually you convert them to strings before you do anything else with them. I did so in this case, with your old friend the convert object. I then added the value from the key press to the appropriate label’s text property.

Coding the KeyDown Event

Having three events for handling keyboard input might seem redundant. However, KeyDown and KeyUp act differently than KeyPressed and are used in different circumstances. KeyDown is activated whenever a key is held down. If the key is held down for a long time, the event is called continuously. The KeyUp event is triggered whenever the user releases the key. The KeyDown event is very useful for game programming because it can be triggered continuously and can trap for any key on the keyboard, including the function keys and arrow keys. In addition to the differences in timing, the KeyDown and KeyUp keys are different from KeyPress because they are more closely mapped to the hardware than the KeyPress event. The KeyPress event is used to determine what the user intended to type. KeyUp and KeyDown can determine exactly what key is being held down at any one time. This is a subtle but powerful difference. Look at the template code provided for the KeyDown event:

173

private void KeyReader_KeyDown(object sender, System.Windows.Forms.KeyEventArgs e) {

} // end KeyDown

You might miss something important (I did, on the first attempt). KeyDown looks much like KeyPressed, and both have a parameter named e. The es are not exactly the same. The e in KeyDown is an instance of the KeyEventArgs object, which is a different beast than the KeyPressedEventArgs object. As you can see from Figure 7.6, the KeyEventArgs object is the more powerful of the two objects and sports interesting properties.

Figure 7.6: The KeyEventArgs object has a longer list of features than KeyPressedEvents.

The code in KeyDown is much like that in KeyPressed, but I took advantage of the more powerful event argument object in KeyDown. KeyEventArgs does not have a KeyChar property. Instead, it returns an integer code named KeyValue. This code describes which key on the keyboard was pressed and also stores, in a special binary structure, information about which modifier keys (the keys that are meant to be pressed with another key, such as Shift, Ctrl, and Alt) are also pressed down. Getting meaningful information out of the KeyValue property can be very ugly, but KeyEventArgs comes with some other, more friendly properties that make it much easier. KeyCode describes which key was pressed, and the Control, Alt, and Shift properties return true or false values describing whether the indicated modifier is currently pressed. Generally, you check the KeyCode property to determine which key was pressed.

In the Real World

The KeyPressed event handler is most useful in game situations, where it is usually used to trap for arrow keys and function keys. The KeyUp and KeyDown event handlers are useful when you want to check for control or alt sequences in your programs. I once wrote a paint program that allowed the user to change colors with a control key (control−B turned the pen blue, for example) My KeyUp event first checked whether the control key was currently being held down. If so, it checked whether KeyCode corresponded to the B key. If so, it turned the pen blue.

174