C# TextBox Tutorial
You want to add a way for users to type letters into your Windows Forms program based on the C# programming language. The Windows Forms system provides the useful TextBox control, which is included in .NET installations and is easy to get started with. Here we look at how you can begin using the TextBox control in your Windows Forms program with C# and the Visual Studio designer, seeing some common events and then how you can access the text in your C# code and save it to a file.
Understanding TextBox control
First here we note some basics about the TextBox control and Windows Forms programs that accept text input from users. The .NET Framework will take care of reading the keys and displaying the text on the screen for you. However, it will not do anything with the text it accepts. You will need to access the text from the TextBox based on custom logic rules. In GUI programming, you will handle custom events provided by the TextBox to know when to execute your logic rules.
Text property on TextBox. The TextBox control in Windows Forms provides a public instance property called Text and this returns a string that represents the exact characters in the TextBox at any time. You can access the Text property at any time, and you can use the TextChanged event to monitor this property for changes.
Adding important event handlers
Here we note that in the Visual Studio integrated development environment, the lightning bolt symbol describes event handlers. Windows Forms programs are primarily event-based, which means you can use the lightning bolt icon in the Properties dialog to add the most important event handlers. This article is based on Visual Studio 2008.
Some commonly used events. The most useful event handlers on the TextBox control are listed in the Properties pane in Visual Studio. If you cannot locate the Properties pane, visit the View, Properties Window menu item. If you see an event handler you want to add, double click on the row in the Properties pane. If you want to hook an event handler to a method that already exists in your program, use the drop-down menu on the Properties pane. The method signatures must be compatible.
Using TextChanged event
In this part of the tutorial we look at how you can use the TextChanged event to modify another part of your program when the user types text into a TextBox. Note that the TextChanged event is only triggered when the text is changed to something different, not changed to the same value for some reason. This program assigns the base window's title text to the text typed in by the user to the TextBox. This makes the base window's title reflect the user's input. The Windows taskbar will also show this text.
~~~ Program that uses TextBox and TextChanged event (C#) ~~~
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;
namespace WindowsFormsApplication20
{
public partial class Form1 : Form
{
public Form1()
{
InitializeComponent();
}
private void textBox1_TextChanged(object sender, EventArgs e)
{
//
// This changes the main window text when you type into the TextBox.
//
this.Text = textBox1.Text;
}
}
}
Adding TextChanged event. You can add the TextChanged event handler to a TextBox by double-clicking on the TextBox in the Windows Forms designer. You can also add the event handler by typing C# code in the Form1() constructor to add the event handler manually. Additionally, the TextChanged row in the Properties pane can be used to create or assign the TextChanged event handler.
Detecting key events
Here we look at how you can read key down events in the TextBox control in Windows Forms using the C# language. The Windows Forms system provides several key-based events, and this tutorial uses the KeyDown event handler which is called before the key value actually is painted on the TextBox. You can cancel the key event in the KeyDown event handler as well, although this is not demonstrated. The program will display an alert when the Enter key is pressed, and an alternative alert message when the Escape key is pressed.
~~~ Windows Forms class that uses KeyDown on TextBox (C#) ~~~
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;
namespace WindowsFormsApplication20
{
public partial class Form1 : Form
{
public Form1()
{
InitializeComponent();
}
private void textBox1_KeyDown(object sender, KeyEventArgs e)
{
//
// Detect the KeyEventArg's key enumerated constant.
//
if (e.KeyCode == Keys.Enter)
{
MessageBox.Show("You pressed enter! Good job!");
}
else if (e.KeyCode == Keys.Escape)
{
MessageBox.Show("You pressed escape! What's wrong?");
}
}
}
}
Keys enumeration. The Windows Forms platform provides a Keys enumeration that you can use to test individual key values. One of the simplest ways to test keys is to type "Keys" and press period, and then use the IntelliSense feature in Visual Studio to scroll through all the possible key values. Because the KeyCode value is of type Keys enum, you can use it as a switch evaluation expression for faster code as well.
Showing messages and dialogs. The above class text demonstrates the MessageBox.Show method, which is the easiest way to display a dialog box in the Windows Forms system. This site contains a MessageBox.Show tutorial that was featured on the official Microsoft Windows Forms site.
See MessageBox.Show Examples in Windows Forms.
Using multiline textbox
Here we look at how you can use the Multiline boolean property on the TextBox control in Windows Forms to create a longer text input area. For demanding applications, the TextBox control might not be sufficient and it does have performance problems with very large amounts of text, but for shorter multiline input boxes, this is useful. The next parts of this tutorial will show how to save the contents of a multiline TextBox to a file on the disk.
Using TextBox with button. The screenshot shows a TextBox that was modified in the designer to have its multiline property set to true. Additionally, the form has a Button control with the text "Save" on it. The next section in this tutorial will demonstrate how you can use this Save button to write the text to a file.
Saving TextBox content to files
Here we see how you can actually make the TextBox control do something that could be useful in a real program: write the file to disk. This is essentially a primitive word processor, but don't use it to write anything important yet. After adding the multiline TextBox, we can add a Button and then double-click on that button in the designer to add the button1_Click event handler. In that event handler, we can access the TextBox Text property and write it to a location on the hard disk.
--- Windows Forms program that writes text from TextBox (C#) ---
using System;
using System.IO;
using System.Windows.Forms;
namespace WindowsFormsApplication20
{
public partial class Form1 : Form
{
public Form1()
{
InitializeComponent();
}
private void button1_Click(object sender, EventArgs e)
{
//
// This is the button labeled "Save" in the program.
//
File.WriteAllText("C:\\demo.txt", textBox1.Text);
}
}
}
--- Possible written file (matches screenshot) ---
This is some text
written for the textbox tutorial
in the site dotnetperls.comWriting text files tutorial. The example method contains an invocation of the File.WriteAllText method from the System.IO namespace in the .NET Framework base class library. This method will take the string data pointed to by the string reference returned by the Text property and then actually write that to the physical hard disk on the computer. After you run this program, you can open the "demo.txt" file and the text you typed into the program will be there.
Related articles
Here we note some related information you can find on this web site about the TextBox control in Windows Forms. In most Windows Forms programs, the controls and event handlers are interconnected, so understanding as many controls as possible is useful. Additionally, there is often more than one way to accomplish a task with event handlers, and some ways are better than others. These articles may help you decide.
See TextBox.AppendText Method.
See Segoe UI, Tahoma in Windows Forms.
See ToolTip Use in Windows Forms .NET.
TextBox properties
Here we note some of the most important properties on the TextBox control in Windows Forms. In the C# programming language, properties are logically public variables that you can usually get or set in external code. Properties may contain executable code. (Not yet written.)
TextBox events. This section mentions some of the most useful events on the TextBox control in Windows Forms. Events are considered a property in the C# programming language, but contain add-accessors and remove-accessors that receive delegate types that must match the delegate signature required. (Not yet available.)
Summary
Here we looked at the TextBox control in the Windows Forms system provided as a part of the .NET Framework using the C# programming language. This control provides a powerful way for the user to input text with the keyboard or other input device and have it appear directly in your C# program in the managed code. The TextBox control provides the Text property, which enables easy access to the input entered into the program. We saw how you can add event handlers, use the TextChanged event, detect specific key presses in the TextBox, use a TextBox that spans multiple lines, and write the TextBox contents to a file.