Section 13.12. Keyboard-Event Handling

13.12. 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 has the 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 the 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: FrmKeyDemo.vb  2  ' Displaying information about the key the user pressed.  3  Public Class FrmKeyDemo  4  5     ' display the character pressed using KeyChar  6     Private Sub FrmKeyDemo_KeyPress(ByVal sender As System.Object, _  7        ByVal e As System.Windows.Forms.KeyPressEventArgs) _  8        Handles MyBase.KeyPress  9 10        lblChar.Text = "Key pressed: " & e.KeyChar 11     End Sub ' FrmKeyDemo_KeyPress 12 13     ' display modifier keys, key code, key data and key value 14     Private Sub FrmKeyDemo_KeyDown(ByVal sender As System.Object, _ 15        ByVal e As System.Windows.Forms.KeyEventArgs) _ 16        Handles MyBase.KeyDown 17 18        If e.Alt Then ' key is Alt 19           lblKeyInfo.Text = "Alt: Yes" & vbCrLf 20        Else ' key is not Alt 21           lblKeyInfo.Text = "Alt: No" & vbCrLf 22        End If 23 24        If e.Shift Then ' key is Shift 25           lblKeyInfo.Text &= "Shift: Yes" & vbCrLf 26        Else ' key is not Shift 27           lblKeyInfo.Text &= "Shift: No" & vbCrLf 28        End If 29 30        If e.Control Then ' key is Control 31           lblKeyInfo.Text &= "Control: Yes" & vbCrLf 32        Else ' key is not Control 33           lblKeyInfo.Text &= "Control: No" & vbCrLf 34        End If 35 36        ' diplay key code, key data and key value 37        lblKeyInfo.Text &= "KeyCode: " & e.KeyCode.ToString() & vbCrLf & _ 38           "KeyData: " & e.KeyData.ToString() & vbCrLf & _ 39           "KeyValue: " & e.KeyValue.ToString() 40     End Sub ' FrmKeyDemo_KeyDown 41 42     ' clear Labels when keys are released 43     Private Sub FrmKeyDemo_KeyUp(ByVal sender As System.Object, _ 44        ByVal e As System.Windows.Forms.KeyEventArgs) Handles MyBase .KeyUp 45 46        lblChar.Text = "" 47        lblKeyInfo.Text = "" 48     End Sub ' FrmKeyDemo_KeyUp 49  End Class ' FrmKeyDemo 

Initially, the two Labels (lblChar and lblKeyInfo) contain "Just Press" and "A Key...". Control lblChar displays the character value of the key pressed, whereas lblKeyInfo displays information relating to the pressed key. Because the KeyDown and KeyPress events convey different information, the Form (FrmKeyDemo) handles both.

The KeyPress event handler (lines 611) accesses the KeyChar property of the Key-PressEventArgs object. This returns the pressed key as a Char, which we then display in lblChar (line 10). If the pressed key is not an ASCII character, then the KeyPress event will not occur, and lblChar 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 1440) 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 Boolean 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 37). The KeyCode property returns the pressed key, but does not provide any information about modifier keys. Thus, both a capital "A" and a lowercase "a" are represented as the A key.

The KeyData property (line 38) 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 39) returns the key code of the pressed key as an Integer. This Integer is the key code, which provides an Integer value for a wide range of keys and for mouse buttons. The key code is useful when one is testing for non-ASCII keys (such as F12).

The KeyUp event handler (lines 4348) clears both Labels when the key is released. As we can see from the output, non-ASCII keys are not displayed in lblChar, because the KeyPress event is not generated. However, the KeyDown event is still generated, and lblKeyInfo 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 make a control react when a particular key is pressed (such as Enter), handle a key event for that control and test for the pressed key. To allow a Button to be clicked when the user presses the Enter key on a Form, set the Form's AcceptButton property.