Edit

Using keyboard events (Windows Forms .NET)

  • Article

Most Windows Forms programs process keyboard input by handling the keyboard events. This article provides an overview of the keyboard events, including details on when to use each event and the data that is supplied for each event. For more information about events in general, see Events overview (Windows Forms .NET).

Important

The Desktop Guide documentation for .NET 7 and .NET 6 is under construction.

Keyboard events

Windows Forms provides two events that occur when a user presses a keyboard key and one event when a user releases a keyboard key:

  • The KeyDown event occurs once.
  • The KeyPress event, which can occur multiple times when a user holds down the same key.
  • The KeyUp event occurs once when a user releases a key.

When a user presses a key, Windows Forms determines which event to raise based on whether the keyboard message specifies a character key or a physical key. For more information about character and physical keys, see Keyboard overview, keyboard events.

The following table describes the three keyboard events.

Keyboard event Description Results
KeyDown This event is raised when a user presses a physical key. The handler for KeyDown receives:

  • A KeyEventArgs parameter, which provides the KeyCode property (which specifies a physical keyboard button).
  • The Modifiers property (SHIFT, CTRL, or ALT).
  • The KeyData property (which combines the key code and modifier). The KeyEventArgs parameter also provides:

    • The Handled property, which can be set to prevent the underlying control from receiving the key.
    • The SuppressKeyPress property, which can be used to suppress the KeyPress and KeyUp events for that keystroke.
KeyPress This event is raised when the key or keys pressed result in a character. For example, a user presses SHIFT and the lowercase "a" keys, which result in a capital letter "A" character. KeyPress is raised after KeyDown.

  • The handler for KeyPress receives:
  • A KeyPressEventArgs parameter, which contains the character code of the key that was pressed. This character code is unique for every combination of a character key and a modifier key.

    For example, the "A" key will generate:

    • The character code 65, if it is pressed with the SHIFT key
    • Or the CAPS LOCK key, 97 if it is pressed by itself,
    • And 1, if it is pressed with the CTRL key.
KeyUp This event is raised when a user releases a physical key. The handler for KeyUp receives:

  • A KeyEventArgs parameter:

    • Which provides the KeyCode property (which specifies a physical keyboard button).
    • The Modifiers property (SHIFT, CTRL, or ALT).
    • The KeyData property (which combines the key code and modifier).

See also