»Desktop Development »Edit Controls »General

Licence	CPOL
First Posted	29 Sep 2004
Views	99,995
Downloads	416
Bookmarked	118 times

TextBoxRegex - A Text Box with Data Validation

ByMarek Grzenkowicz | 30 Jun 2010

.NET1.1VS.NET2003C#Windows.NETVisual-StudioDevIntermediate

An enhanced text box control with powerful data validation capabilities

Abstract

TextBoxRegex is a user control that inherits from a regularTextBox (System.Windows.Forms.TextBox). It allows to check data entered by the user against any pattern. The pattern can be chosen from a set of predefined patterns (like 'small letters', 'capital letters', etc.) as well as specified in the form of wildcard orRegex (System.Text.RegularExpressions.Regex) string.

Introduction

It's been about four months since I started learning C#. Some time ago, I decided that it's high time to check how much I learned. I also wanted to find out how TDD (Test-Driven Development) really works, since only reading about it didn't convince me about its usefulness. And I heard of NDoc and it seemed like a great idea. And finally, last but not least, I wanted to write my first CodeProject article. As you can see, I was going to kill many birds with only one stone.

At the time all this thoughts were going through my head, I finished reading a bonus chapter from Platt's 'Introducing Microsoft .NET' (seethe references), the one about Windows Forms controls. I've never written a control before, so I decided to finally give it a try. I used Platt's idea of text box checking entered data, but I went much further than he did in his example.

While developing this project, I was reading another .NET book - 'Extreme Programming Adventures in C#' by Ron Jeffries. I was using unit tests throughout the whole development process and you will find these tests in the source code, but neither this article nor the tests are meant to be a TDD tutorial. Some of the tests should be stronger, sometimes there aren't enough of them. I know that. But, as I mentioned, this project was meant, among other things, to be my TDD training ground.

Compiling the Sources

TextBoxRegex uses NUnit tests and as a result it referencesnunit.framework.dll file. I used#if ...#endif directives to exclude unit test classes from release build. However, if you want to compile the code in debug mode, you will either need to change thenunit.framework.dll reference to point to your location of this file (if you don't have it, seethe software section for NUnit links) or remove this reference completely along with all test classes (the appropriate files are located underTests folder).

Using the Code - Basics

I will start with describing the easiest way to useTextBoxRegex control.

Open a new Windows Application project. You should see an empty Form loaded in design mode.
To add the control to theToolbox, right-click on it, on the tab where you want the control to appear.
ChooseAdd/Remove Items... option from the context menu.
In theCustomize Toolbox window, click theBrowse button and navigate to the folder where you placedChopeen.TextBoxRegex.dll.
Open it and clickOK to close theCustomize Toolbox window. There should be a new control on the tab.
Drag theTextBoxRegex control onto the tab.
That's it! Hit F5 - if you did everything right (and have the same keyboard mapping scheme as I do), the project will compile and run.

Of course, this project is not very useful - no matter what you type, the text box always turns pink - this indicates that your input does not match the pattern. But there isn't much more work to do, before the project turns into something much more interesting.

Let's take a look at the code generated by Visual Studio. I cut and pasted lines that concernTextBoxRegex control below:

private Chopeen.TextBoxRegex textBoxRegex1;this.textBoxRegex1 =new Chopeen.TextBoxRegex();this.textBoxRegex1.Location =new System.Drawing.Point(176,80);this.textBoxRegex1.Name ="textBoxRegex1";this.textBoxRegex1.TabIndex =0;this.textBoxRegex1.Text ="textBoxRegex1";this.textBoxRegex1.BackColor = System.Drawing.SystemColors.Window;this.textBoxRegex1.InvalidTextBackColor = System.Drawing.Color.LightPink;this.textBoxRegex1.Pattern = Chopeen.TextBoxRegex.Patterns.None;this.textBoxRegex1.PatternString ="";this.textBoxRegex1.UseColors =true;this.textBoxRegex1.UseInvalidTextException =true;this.textBoxRegex1.ValidTextBackColor = System.Drawing.Color.LightGreen;this.Controls.Add(this.textBoxRegex1);

There are four blocks of code. The most important one for you is the third one. There are six properties that you can set and that determine the wayTextBoxRegex control works. All of them are described in detail in the documentation - you can download it in the form of a CHM help file.

You can also download a demo application and check everything experimentally. I added a property grid to the form and all the additional properties are grouped under a single category (Regex), so just runTextBoxRegexDemo.exe, expand the last group of properties, change their values, and see what happens.

Using the Code - Going Further

Enough about the easy stuff. Let's talk about something a little bit more advanced now.

One of the problems I encountered whilst developingTextBoxRegex was how to tell the application whether the text that it is reading from the control is valid or not.

The first idea was to create a method - let's call itIsValid() - returning a boolean value indicating whether user's input matches the chosen pattern. It would be the developer's duty to remember to runIsValid() before reading the text from the control to check if there is a match. But I didn't like this idea, because the developer would face a necessity of building an additional logic every time he wanted to useTextBoxRegex control.

Then, I wanted to override theText property. But I realized that this way I would break the Rule of Least Astonishment. When there is a text box, enhanced or not, what do you expect to get when you try to read itsText property? So my second idea was even worse, wasn't it?

And at last, a third idea came to my mind. I implemented an additional property -TextValidated. As long as the control's text is valid, this property behaves exactly likeText.

But when the text doesn't match the chosen pattern, an attempt to read the value ofTextValidated property either throws anInvalidTextException or returns an empty string - that depends on the value ofUseInvalidTextException property. It is set totrue by default, but change its value tofalse, if you prefer not to use exceptions.

Below, you can see an example of usingTextValidated property in atry-catch block:

textBoxRegex1.UseInvalidTextException =true;try{// there is a match    MessageBox.Show("You entered" +       textBoxRegex1.TextValidated +"and you were right.");}catch (Chopeen.InvalidTextException ex){// there is no match    MessageBox.Show("You were wrong.");}

What Did I Learn?

David Platt says in his book that'ActiveX controls were difficult to write because the operating system didn't supply any infrastructure for them; you had to write every bit of it yourself. I wrote one in raw C++ once, just for the sheer pain of it, and I'd rather have a root canal without anaesthesia than do it again'. I don't know (and I don't want to know) how it feels to have a root canal, but creating a .NET Windows control wasn't like a visit to the dentist in any way. Even though I have never written a control before.

When I first heard about TDD from Peter Provost's article (seethe references), I was skeptical. Really skeptical. But it didn't take more than a month to turn my skepticism into enthusiasm. I admit that writing unit tests requires some additional work, but isn't it better to spend a few more minutes writing more code than hours debugging? And what's even more important - once you have created the tests, you can use them many times instead of manually checking your application after every change you made.

Thanks to this project, I also got to know the power of code refactoring. I always knew that it is important to keep the code as clean as possible, but until now, there was always this fear that the application would suddenly break after I had changed something, and I wouldn't know why. So I usually refrained from refactoring. Unit tests solve this problem. Write good, strong tests and then you can refactor as much as you want - the tests are always there to tell you when something goes wrong.

References

Marc Clifton, jdunlap, 'What Is Extreme Programming?', The Code Project, 2003
Ron Jeffries, 'Extreme Programming Adventures in C#', Microsoft Press, 2004
James W. Newkirk and Alexei A. Vorontsov, 'Test-Driven Development in Microsoft .NET', Microsoft Press, 2004
David S. Platt, 'Introducing Microsoft .NET, 3rd Edition', Microsoft Press, 2003
Peter Provost, 'Test-Driven Development in .NET', The Code Project, 2003
Sami Vaaraniemi, 'The benefits of automated unit testing', The Code Project, 2003