How to: Modify Keyboard Input to a Standard Control
Windows Forms provides the ability to consume and modify keyboard input. Consuming a key refers to handling a key within a method or event handler so that other methods and events further down the message queue do not receive the key value. Modifying a key refers to modifying the value of a key so that methods and event handlers further down the message queue receive a different key value. This topic shows how to accomplish these tasks.
To consume a key
In a KeyPress event handler, set the Handled property of the KeyPressEventArgs class to true.
-or-
In a KeyDown event handler, set the Handled property of the KeyEventArgs class to true.
Note
Setting the Handled property in the KeyDown event handler does not prevent the KeyPress and KeyUp events from being raised for the current keystroke. Use the SuppressKeyPress property for this purpose.
The following example is an excerpt from a switch statement that examines the KeyChar property of the KeyPressEventArgs received by a KeyPress event handler. This code consumes the 'A' and 'a' character keys.
' Consume 'A' and 'a'. Case ChrW(65), ChrW(97) MessageBox.Show(("Control.KeyPress: '" + _ e.KeyChar.ToString() + "' consumed.")) e.Handled = True// Consume 'A' and 'a'. case (char)65: case (char)97: MessageBox.Show("Control.KeyPress: '" + e.KeyChar.ToString() + "' consumed."); e.Handled = true; break;
To modify a standard character key
In a KeyPress event handler, set the KeyChar property of the KeyPressEventArgs class to the value of the new character key.
The following example is an excerpt from a switch statement that modifies 'B' to 'A' and 'b' to 'a'. Note that the Handled property of the KeyPressEventArgs parameter is set to false, so that the new key value is propagated to other methods and events in the message queue.
' Modify 'B' to 'A' and forward the key. Case ChrW(66) MessageBox.Show(("Control.KeyPress: '" + _ e.KeyChar.ToString() + "' replaced by 'A'.")) e.KeyChar = ChrW(65) e.Handled = False ' Modify 'b' to 'a' and forward the key. Case ChrW(98) MessageBox.Show(("Control.KeyPress: '" + _ e.KeyChar.ToString() + "' replaced by 'a'.")) e.KeyChar = ChrW(97) e.Handled = False// Detect 'B', modify it to 'A', and forward the key. case (char)66: MessageBox.Show("Control.KeyPress: '" + e.KeyChar.ToString() + "' replaced by 'A'."); e.KeyChar = (char)65; e.Handled = false; break; // Detect 'b', modify it to 'a', and forward the key. case (char)98: MessageBox.Show("Control.KeyPress: '" + e.KeyChar.ToString() + "' replaced by 'a'."); e.KeyChar = (char)97; e.Handled = false; break;
To modify a noncharacter key
Override a Control method that processes Windows messages, detect the WM_KEYDOWN or WM_SYSKEYDOWN message, and set the WParam property of the Message parameter to the Keys value that represents the new noncharacter key.
The following code example demonstrates how to override the PreProcessMessage method of a control to detect keys F1 through F9 and modify any F3 key press to F1. For more information on Control methods that you can override to intercept keyboard messages, see User Input in a Windows Forms Application and How Keyboard Input Works.
' Detect F1 through F9 during preprocessing and modify F3. Public Overrides Function PreProcessMessage(ByRef m As Message) _ As Boolean If m.Msg = WM_KEYDOWN Then Dim keyCode As Keys = CType(m.WParam, Keys) And Keys.KeyCode ' Detect F1 through F9. Select Case keyCode Case Keys.F1, Keys.F2, Keys.F3, Keys.F4, Keys.F5, _ Keys.F6, Keys.F7, Keys.F8, Keys.F9 MessageBox.Show(("Control.PreProcessMessage: '" + _ keyCode.ToString() + "' pressed.")) ' Replace F3 with F1, so that ProcessKeyMessage will ' receive F1 instead of F3. If keyCode = Keys.F3 Then m.WParam = CType(Keys.F1, IntPtr) MessageBox.Show(("Control.PreProcessMessage: '" + _ keyCode.ToString() + "' replaced by F1.")) End If End Select End If ' Send all other messages to the base method. Return MyBase.PreProcessMessage(m) End Function// Detect F1 through F9 during preprocessing and modify F3. public override bool PreProcessMessage(ref Message m) { if (m.Msg == WM_KEYDOWN) { Keys keyCode = (Keys)m.WParam & Keys.KeyCode; // Detect F1 through F9. switch (keyCode) { case Keys.F1: case Keys.F2: case Keys.F3: case Keys.F4: case Keys.F5: case Keys.F6: case Keys.F7: case Keys.F8: case Keys.F9: MessageBox.Show("Control.PreProcessMessage: '" + keyCode.ToString() + "' pressed."); // Replace F3 with F1, so that ProcessKeyMessage will // receive F1 instead of F3. if (keyCode == Keys.F3) { m.WParam = (IntPtr)Keys.F1; MessageBox.Show("Control.PreProcessMessage: '" + keyCode.ToString() + "' replaced by F1."); } break; } } // Send all other messages to the base method. return base.PreProcessMessage(ref m); }
Example
The following code example is the complete application for the code examples in the previous sections. The application uses a custom control derived from the TextBox class to consume and modify keyboard input.
Imports System
Imports System.Drawing
Imports System.Security
Imports System.Security.Permissions
Imports System.Windows.Forms
Namespace KeyboardInput
<System.Security.Permissions.PermissionSetAttribute(System.Security.Permissions.SecurityAction.Demand, Name:="FullTrust")> _
Class Form1
Inherits Form
' The following Windows message value is defined in Winuser.h.
Private WM_KEYDOWN As Integer = &H100
Private WithEvents CustomTextBox1 As New CustomTextBox()
<STAThread()> _
Public Shared Sub Main()
Application.EnableVisualStyles()
Application.Run(New Form1())
End Sub
Public Sub New()
Me.AutoSize = True
Me.Controls.Add(CustomTextBox1)
End Sub
' Consume and modify several character keys.
Sub CustomTextBox1_KeyPress(ByVal sender As Object, _
ByVal e As KeyPressEventArgs) Handles CustomTextBox1.KeyPress
Select Case e.KeyChar
' Consume 'A' and 'a'.
Case ChrW(65), ChrW(97)
MessageBox.Show(("Control.KeyPress: '" + _
e.KeyChar.ToString() + "' consumed."))
e.Handled = True
' Modify 'B' to 'A' and forward the key.
Case ChrW(66)
MessageBox.Show(("Control.KeyPress: '" + _
e.KeyChar.ToString() + "' replaced by 'A'."))
e.KeyChar = ChrW(65)
e.Handled = False
' Modify 'b' to 'a' and forward the key.
Case ChrW(98)
MessageBox.Show(("Control.KeyPress: '" + _
e.KeyChar.ToString() + "' replaced by 'a'."))
e.KeyChar = ChrW(97)
e.Handled = False
End Select
End Sub
End Class
<System.Security.Permissions.PermissionSetAttribute(System.Security.Permissions.SecurityAction.Demand, Name:="FullTrust")> _
Public Class CustomTextBox
Inherits TextBox
' The following Windows message value is defined in Winuser.h.
Private WM_KEYDOWN As Integer = &H100
Public Sub New()
Me.Size = New Size(100, 100)
Me.AutoSize = False
End Sub
' Detect F1 through F9 during preprocessing and modify F3.
Public Overrides Function PreProcessMessage(ByRef m As Message) _
As Boolean
If m.Msg = WM_KEYDOWN Then
Dim keyCode As Keys = CType(m.WParam, Keys) And Keys.KeyCode
' Detect F1 through F9.
Select Case keyCode
Case Keys.F1, Keys.F2, Keys.F3, Keys.F4, Keys.F5, _
Keys.F6, Keys.F7, Keys.F8, Keys.F9
MessageBox.Show(("Control.PreProcessMessage: '" + _
keyCode.ToString() + "' pressed."))
' Replace F3 with F1, so that ProcessKeyMessage will
' receive F1 instead of F3.
If keyCode = Keys.F3 Then
m.WParam = CType(Keys.F1, IntPtr)
MessageBox.Show(("Control.PreProcessMessage: '" + _
keyCode.ToString() + "' replaced by F1."))
End If
End Select
End If
' Send all other messages to the base method.
Return MyBase.PreProcessMessage(m)
End Function
' Detect F1 through F9 during processing.
Protected Overrides Function ProcessKeyMessage(ByRef m As Message) _
As Boolean
If m.Msg = WM_KEYDOWN Then
Dim keyCode As Keys = CType(m.WParam, Keys) And Keys.KeyCode
' Detect F1 through F9.
Select Case keyCode
Case Keys.F1, Keys.F2, Keys.F3, Keys.F4, Keys.F5, _
Keys.F6, Keys.F7, Keys.F8, Keys.F9
MessageBox.Show(("Control.ProcessKeyMessage: '" + _
keyCode.ToString() + "' pressed."))
End Select
End If
' Send all messages to the base method.
Return MyBase.ProcessKeyMessage(m)
End Function
End Class
End Namespace
using System;
using System.Drawing;
using System.Windows.Forms;
namespace KeyboardInput
{
[System.Security.Permissions.PermissionSet(System.Security.Permissions.SecurityAction.Demand, Name="FullTrust")]
class Form1 : Form
{
// The following Windows message value is defined in Winuser.h.
private int WM_KEYDOWN = 0x100;
CustomTextBox CustomTextBox1 = new CustomTextBox();
[STAThread]
public static void Main()
{
Application.EnableVisualStyles();
Application.Run(new Form1());
}
public Form1()
{
this.AutoSize = true;
this.Controls.Add(CustomTextBox1);
CustomTextBox1.KeyPress +=
new KeyPressEventHandler(CustomTextBox1_KeyPress);
}
// Consume and modify several character keys.
void CustomTextBox1_KeyPress(object sender, KeyPressEventArgs e)
{
switch (e.KeyChar)
{
// Consume 'A' and 'a'.
case (char)65:
case (char)97:
MessageBox.Show("Control.KeyPress: '" +
e.KeyChar.ToString() + "' consumed.");
e.Handled = true;
break;
// Detect 'B', modify it to 'A', and forward the key.
case (char)66:
MessageBox.Show("Control.KeyPress: '" +
e.KeyChar.ToString() + "' replaced by 'A'.");
e.KeyChar = (char)65;
e.Handled = false;
break;
// Detect 'b', modify it to 'a', and forward the key.
case (char)98:
MessageBox.Show("Control.KeyPress: '" +
e.KeyChar.ToString() + "' replaced by 'a'.");
e.KeyChar = (char)97;
e.Handled = false;
break;
}
}
}
[System.Security.Permissions.PermissionSet(System.Security.Permissions.SecurityAction.Demand, Name="FullTrust")]
public class CustomTextBox : TextBox
{
// The following Windows message value is defined in Winuser.h.
private int WM_KEYDOWN = 0x100;
public CustomTextBox()
{
this.Size = new Size(100, 100);
this.AutoSize = false;
}
// Detect F1 through F9 during preprocessing and modify F3.
public override bool PreProcessMessage(ref Message m)
{
if (m.Msg == WM_KEYDOWN)
{
Keys keyCode = (Keys)m.WParam & Keys.KeyCode;
// Detect F1 through F9.
switch (keyCode)
{
case Keys.F1:
case Keys.F2:
case Keys.F3:
case Keys.F4:
case Keys.F5:
case Keys.F6:
case Keys.F7:
case Keys.F8:
case Keys.F9:
MessageBox.Show("Control.PreProcessMessage: '" +
keyCode.ToString() + "' pressed.");
// Replace F3 with F1, so that ProcessKeyMessage will
// receive F1 instead of F3.
if (keyCode == Keys.F3)
{
m.WParam = (IntPtr)Keys.F1;
MessageBox.Show("Control.PreProcessMessage: '" +
keyCode.ToString() + "' replaced by F1.");
}
break;
}
}
// Send all other messages to the base method.
return base.PreProcessMessage(ref m);
}
// Detect F1 through F9 during processing.
protected override bool ProcessKeyMessage(ref Message m)
{
if (m.Msg == WM_KEYDOWN)
{
Keys keyCode = (Keys)m.WParam & Keys.KeyCode;
// Detect F1 through F9.
switch (keyCode)
{
case Keys.F1:
case Keys.F2:
case Keys.F3:
case Keys.F4:
case Keys.F5:
case Keys.F6:
case Keys.F7:
case Keys.F8:
case Keys.F9:
MessageBox.Show("Control.ProcessKeyMessage: '" +
keyCode.ToString() + "' pressed.");
break;
}
}
// Send all messages to the base method.
return base.ProcessKeyMessage(ref m);
}
}
}
Compiling the Code
This example requires:
- References to the System, System.Drawing and System.Windows.Forms assemblies.
For information about building this example from the command line for Visual Basic or Visual C#, see Building from the Command Line (Visual Basic) or Command-line Building With csc.exe. You can also build this example in Visual Studio by pasting the code into a new project. For more information, see How to: Compile and Run a Complete Windows Forms Code Example Using Visual Studio and How to: Compile and Run a Complete Windows Forms Code Example Using Visual Studio and How to: Compile and Run a Complete Windows Forms Code Example Using Visual Studio and How to: Compile and Run a Complete Windows Forms Code Example Using Visual Studio.
See Also
Concepts
User Input in a Windows Forms Application