Keyboard-Event Handling

Key events occur when keyboard keys are pressed and released. Such events can be handled for any control that inherits from System.Windows.Forms.Control. There are three key eventsKeyPress, KeyUp and KeyDown. The KeyPress event occurs when the user presses a key that represents an ASCII character. The specific key can be determined with property KeyChar of the event handler's KeyPressEventArgs argument. ASCII is a 128-character set of alphanumeric symbols, a full listing of which can be found in Appendix D.

The KeyPress event does not indicate whether modifier keys (e.g., Shift, Alt and Ctrl) were pressed when a key event occurred. If this information is important, the KeyUp or KeyDown events can be used. The KeyEventArgs argument for each of these events contains information about modifier keys. Often, modifier keys are used in conjunction with the mouse to select or highlight information. Figure 13.39 lists important key event information. Several properties return values from the Keys enumeration, which provides constants that specify the various keys on a keyboard. Like the FontStyle enumeration (Section 13.7), the Keys enumeration is a System.FlagAttribute, so the enumeration's constants can be combined to indicate multiple keys pressed at the same time.

Figure 13.39. Keyboard events and event arguments.

Keyboard events and event arguments
Key Events with Event Arguments of Type KeyEventArgs
KeyDown	Generated when a key is initially pressed.
KeyUp	Generated when a key is released.
Key Event with Event Argument of Type KeyPressEventArgs
KeyPress	Generated when a key is pressed.
Class KeyPressEventArgs Properties
KeyChar	Returns the ASCII character for the key pressed.
Handled	Indicates whether the KeyPress event was handled.
Class KeyEventArgs Properties
Alt	Indicates whether the Alt key was pressed.
Control	Indicates whether the Ctrl key was pressed.
Shift	Indicates whether the Shift key was pressed.
Handled	Indicates whether the event was handled.
KeyCode	Returns the key code for the key as a value from the Keys enumeration. This does not include modifier-key information. It is used to test for a specific key.
KeyData	Returns the key code for a key combined with modifier information as a Keys value. This property contains all information about the pressed key.
KeyValue	Returns the key code as an int, rather than as a value from the Keys enumeration. This property is used to obtain a numeric representation of the pressed key. The int value is known as a Windows virtual key code.
Modifiers	Returns a Keys value indicating any pressed modifier keys (Alt, Ctrl and Shift). This property is used to determine modifier-key information only.

Figure 13.40 demonstrates the use of the key-event handlers to display a key pressed by a user. The program is a Form with two Labels that displays the pressed key on one Label and modifier key information on the other.

Figure 13.40. Demonstrating keyboard events.

 1 // Fig. 13.40: KeyDemoForm.cs
 2 // Displaying information about the key the user pressed.
 3 System;
 4 System.Windows.Forms;
 5
 6 // Form to display key information when key is pressed
 7 KeyDemoForm : Form
 8 {
 9 // default constructor
10 KeyDemoForm()
11 {
12 InitializeComponent();
13 } // end constructor
14
15 // display the character pressed using KeyChar
16 KeyDemoForm_KeyPress( sender, KeyPressEventArgs e )
17 {
18 charLabel.Text = "Key pressed: " + e.KeyChar;
19 } // end method KeyDemoForm_KeyPress
20
21 // display modifier keys, key code, key data and key value
22 KeyDemoForm_KeyDown( sender, KeyEventArgs e )
23 {
24 keyInfoLabel.Text =
25 "Alt: " + ( e.Alt ? "Yes" : "No" ) + '
' +
26 "Shift: " + ( e.Shift ? "Yes" : "No" ) + '
' +
27 "Ctrl: " + ( e.Control ? "Yes" : "No" ) + '
' +
28 "KeyCode: " + e.KeyCode + '
' +
29 "KeyData: " + e.KeyData + '
' +
30 "KeyValue: " + e.KeyValue;
31 } // end method KeyDemoForm_KeyDown
32

33 // clear Labels when key released 34 KeyDemoForm_KeyUp( sender, KeyEventArgs e ) 35 { 36 charLabel.Text = ""; 37 keyInfoLabel.Text = ""; 38 } // end method KeyDemoForm_KeyUp 39 } // end class KeyDemoForm

Initially, the two Labels (charLabel and keyInfoLabel) are empty. Control charLabel displays the character value of the key pressed, whereas keyInfoLabel displays information relating to the pressed key. Because the KeyDown and KeyPress events convey different information, the Form (KeyDemoForm) handles both.

The KeyPress event handler (lines 1619) accesses the KeyChar property of the KeyPressEventArgs object. This returns the pressed key as a char and which we then display in charLabel (line 18). If the pressed key is not an ASCII character, then the KeyPress event will not occur, and charLabel will not display any text. ASCII is a common encoding format for letters, numbers, punctuation marks and other characters. It does not support keys such as the function keys (like F1) or the modifier keys (Alt, Ctrl and Shift).

The KeyDown event handler (lines 2231) displays information from its KeyEventArgs object. The event handler tests for the Alt, Shift and Ctrl keys by using the Alt, Shift and Control properties, each of which returns a bool valuetrue if the corresponding key is pressed and false otherwise. The event handler then displays the KeyCode, KeyData and KeyValue properties.

The KeyCode property returns a Keys enumeration value (line 28). The KeyCode property returns the pressed key, but does not provide any information about modifier keys. Thus, both a capital and a lowercase "a" are represented as the A key.

The KeyData property (line 29) also returns a Keys enumeration value, but this property includes data about modifier keys. Thus, if "A" is input, the KeyData shows that both the A key and the Shift key were pressed. Lastly, KeyValue (line 30) returns the key code of the pressed key as an int. This int is the key code, which provides an int value for a wide range of keys and for mouse buttons. The Windows virtual key code is useful when one is testing for non-ASCII keys (such as F12).

The KeyUp event handler (lines 3438) clears both Labels when the key is released. As we can see from the output, non-ASCII keys are not displayed in charLabel, because the KeyPress event is not generated. However, the KeyDown event still is generated, and keyInfoLabel displays information about the key that is pressed. The Keys enumeration can be used to test for specific keys by comparing the key pressed to a specific KeyCode.

Software Engineering Observation 13 3

To cause a control to react when a particular key is pressed (such as Enter), handle a key event and test for the pressed key. To cause a Button to be clicked when the Enter key is pressed on a Form, set the Form's AcceptButton property.