This documentation is archived and is not being maintained.

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.

Namespace: System.Windows.Forms
Assembly: System.Windows.Forms (in system.windows.forms.dll)

public bool KeyPreview { get; set; }
/** @property */
public boolean get_KeyPreview ()

/** @property */
public void set_KeyPreview (boolean value)

public function get KeyPreview () : boolean

public function set KeyPreview (value : 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.

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 handlers 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 handler to true.

You can use this property to process most 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.

NoteNote

If a form has no visible or enabled controls, it automatically receives all keyboard events.

NoteNote

A control on a form may be programmed to cancel any keystrokes it receives. Since the control never sends these keystrokes to the form, the form will never see them regardless of the setting of KeyPreview.

The following code example demonstrates setting a form's KeyPreview property to true and handling the key events at the form level. To run the example, paste the following code in a blank form.

using namespace System::Windows::Forms;

// 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.  
// This method makes sure the control is selectable and the 
// mnemonic is correct before displaying the message box
// and triggering the click event.
public ref class MyMnemonicButton: public Button
{
protected:
   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;
   }

};


// Declare the controls contained on the form.
public ref class Form1: public System::Windows::Forms::Form
{
private:
   MyMnemonicButton^ button1;

public private:
   System::Windows::Forms::ListBox^ ListBox1;

public:
   Form1()
      : Form()
   {
      
      // 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 = gcnew MyMnemonicButton;
      button1->Text = "&Click";
      button1->Location = System::Drawing::Point( 100, 120 );
      this->Controls->Add( button1 );
      
      // Initialize a ListBox control and the form itself.
      this->ListBox1 = gcnew System::Windows::Forms::ListBox;
      this->SuspendLayout();
      this->ListBox1->Location = System::Drawing::Point( 8, 8 );
      this->ListBox1->Name = "ListBox1";
      this->ListBox1->Size = System::Drawing::Size( 120, 95 );
      this->ListBox1->TabIndex = 0;
      this->ListBox1->Text = "Press a key";
      this->ClientSize = 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 += gcnew KeyEventHandler( this, &Form1::Form1_KeyDown );
   }


private:

   // 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.
   void Form1_KeyDown( Object^ /*sender*/, KeyEventArgs^ e )
   {
      ListBox1->Items->Add( e->KeyCode );
      e->Handled = false;
   }

};


[System::STAThreadAttribute]
int main()
{
   Application::Run( gcnew Form1 );
}


Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

Supported in: 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0
Show: