Form.KeyPreview Property
Gets or sets a value indicating whether the form will receive key events before the event is passed to the control that has focus.
[Visual Basic] Public Property KeyPreview As Boolean [C#] public bool KeyPreview {get; set;} [C++] public: __property bool get_KeyPreview(); public: __property void set_KeyPreview(bool); [JScript] public function get KeyPreview() : Boolean; public function set KeyPreview(Boolean);
Property Value
true if the form will receive all key events; false if the currently selected control on the form receives key events. The default is false.
Remarks
When this property is set to true, the form will receive all KeyPress, KeyDown, and KeyUp events. After the form's event handlers have completed processing the keystroke, the keystroke is then assigned to the control with focus. For example, if the KeyPreview property is set to true and the currently selected control is a TextBox, after the keystroke is handled by the event-handling methods of the form the TextBox control will receive the key that was pressed. To handle keyboard events only at the form level and not allow controls to receive keyboard events, set the KeyPressEventArgs.Handled property in your form's KeyPress event-handling method to true.
You can use this property to process all keystrokes in your application and either handle the keystroke or call the appropriate control to handle the keystroke. For example, when an application uses function keys, you might want to process the keystrokes at the form level rather than writing code for each control that might receive keystroke events.
Note If a form has no visible or enabled controls, it automatically receives all keyboard events.
Example
[Visual Basic, C#] The following code example demonstrates setting a form's KeyPreview property to true and handlingthe key events at the form level. To run the example, paste the following code in a blank form.
[Visual Basic] Imports System.Windows.Forms Public Class Form1 Inherits System.Windows.Forms.Form ' Declare the controls contained on the form. Private WithEvents button1 As MyMnemonicButton Friend WithEvents ListBox1 As System.Windows.Forms.ListBox Public Sub New() MyBase.New() ' Set KeyPreview object to true to allow the form to process ' the key before the control with focus processes it. Me.KeyPreview = True ' Add a MyMnemonicButton. button1 = New MyMnemonicButton button1.Text = "&Click" button1.Location = New System.Drawing.Point(100, 120) Me.Controls.Add(button1) ' Initialize a ListBox control and the form itself. Me.ListBox1 = New System.Windows.Forms.ListBox Me.SuspendLayout() Me.ListBox1.Location = New System.Drawing.Point(8, 8) Me.ListBox1.Name = "ListBox1" Me.ListBox1.Size = New System.Drawing.Size(120, 95) Me.ListBox1.TabIndex = 0 Me.ListBox1.Text = "Press a key" Me.AutoScaleBaseSize = New System.Drawing.Size(5, 13) Me.ClientSize = New System.Drawing.Size(292, 266) Me.Controls.Add(Me.ListBox1) Me.Name = "Form1" Me.Text = "Form1" Me.ResumeLayout(False) End Sub ' The form will handle all key events before the control with ' focus handles them. Show the keys pressed by adding the ' KeyCode object to ListBox1. Ensure the processing is passed ' to the control with focus by setting the KeyEventArg.Handled ' property to false. Private Sub Form1_KeyDown(ByVal sender As Object, _ ByVal e As KeyEventArgs) Handles MyBase.KeyDown ListBox1.Items.Add(e.KeyCode) e.Handled = False End Sub <System.STAThreadAttribute()> Public Shared Sub Main() Application.Run(New Form1) End Sub End Class ' This button is a simple extension of the button class that overrides ' the ProcessMnemonic method. If the mnemonic is correctly entered, ' the message box will appear and the click event will be raised. Public Class MyMnemonicButton Inherits Button ' This method makes sure the control is selectable and the ' mneumonic is correct before displaying the message box ' and triggering the click event. Protected Overrides Function ProcessMnemonic( _ ByVal inputChar As Char) As Boolean If (CanSelect And IsMnemonic(inputChar, Me.Text)) Then MessageBox.Show("You've raised the click event " _ & "using the mnemonic.") Me.PerformClick() Return True End If Return False End Function End Class [C#] using System.Windows.Forms; public class Form1: System.Windows.Forms.Form // Declare the controls contained on the form. { private MyMnemonicButton button1; internal System.Windows.Forms.ListBox ListBox1; public Form1() : base() { // Set KeyPreview object to true to allow the form to process // the key before the control with focus processes it. this.KeyPreview = true; // Add a MyMnemonicButton. button1 = new MyMnemonicButton(); button1.Text = "&Click"; button1.Location = new System.Drawing.Point(100, 120); this.Controls.Add(button1); // Initialize a ListBox control and the form itself. this.ListBox1 = new System.Windows.Forms.ListBox(); this.SuspendLayout(); this.ListBox1.Location = new System.Drawing.Point(8, 8); this.ListBox1.Name = "ListBox1"; this.ListBox1.Size = new System.Drawing.Size(120, 95); this.ListBox1.TabIndex = 0; this.ListBox1.Text = "Press a key"; this.AutoScaleBaseSize = new System.Drawing.Size(5, 13); this.ClientSize = new System.Drawing.Size(292, 266); this.Controls.Add(this.ListBox1); this.Name = "Form1"; this.Text = "Form1"; this.ResumeLayout(false); // Associate the event-handling method with the // KeyDown event. this.KeyDown += new KeyEventHandler(Form1_KeyDown); } // The form will handle all key events before the control with // focus handles them. Show the keys pressed by adding the // KeyCode object to ListBox1. Ensure the processing is passed // to the control with focus by setting the KeyEventArg.Handled // property to false. private void Form1_KeyDown(object sender, KeyEventArgs e) { ListBox1.Items.Add(e.KeyCode); e.Handled = false; } [System.STAThreadAttribute] public static void Main() { Application.Run(new Form1()); } } // This button is a simple extension of the button class that overrides // the ProcessMnemonic method. If the mnemonic is correctly entered, // the message box will appear and the click event will be raised. public class MyMnemonicButton: Button // This method makes sure the control is selectable and the // mneumonic is correct before displaying the message box // and triggering the click event. { protected override bool ProcessMnemonic(char inputChar) { if (CanSelect&&IsMnemonic(inputChar, this.Text)) { MessageBox.Show("You've raised the click event " + "using the mnemonic."); this.PerformClick(); return true; } return false; } }
[C++, JScript] No example is available for C++ or JScript. To view a Visual Basic or C# example, click the Language Filter button
in the upper-left corner of the page.
Requirements
Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family
See Also
Form Class | Form Members | System.Windows.Forms Namespace | KeyPress | KeyDown | KeyUp