Demo project
Calendar displayed by DateTextbox
Contents
Introduction
This article offers two user controls that are alternatives to the standard VB.NET TextBox.
DateTextbox ... an aggregate of a standard TextBox and a calendar button. ExtendedTextbox ... adds six properties to the standard TextBox for controlling textbox behavior.
Background
For longer than I can remember, I've been providing a calendar button next to textboxes where the user has to enter a date. Prior to VB.NET, this involved adding the necessary code for each and every date textbox. I've also been controlling user keystrokes in textboxes where specific types of data are required (e.g., numbers only). I find this technique preferable to waiting until edit time to inform the user that they have to go back and correct their work. This keystroke monitoring also required adding repetitive functionality for each textbox where keystrokes were to be policed. Of course, using Double Text, this repetitive code was repeated quickly and accurately; however, the time needed to configure each textbox was substantial, and, to be honest, a bit tiresome.
User controls in VB.NET have freed me from these tedious, yet necessary chores. Now, I use the date and extended textboxes in all projects (except other user controls). I no longer use the standard textbox because modifying how a textbox responds to keystrokes is a simple matter of changing properties. If I have to change how a textbox will behave, I am not faced with deleting one control and adding another. Life is good.
Using the Code
- Download the DLL files and place them in an appropriate folder of your choosing.
- In the Visual Studio Toolbox, right click in the My User Controls tab to open a popup menu (a form must be open for the Toolbox to be visible). Click on the Add/Remove Items menu item.
- In the Customize Toolbox dialog box, click on the Browse button to open one of the DLL files, and then browse to open the other.
- Click the OK button.
DateTextbox and ExtendedTextbox will be listed on the My User Controls tab. Add either of the user controls to a form by dragging them to the form, the same as you do with any of the controls listed in the Windows Forms tab.
The DateTextbox is an aggregate of a standard TextBox and a Button. When the button is clicked, a calendar is displayed. When the user clicks on the OK button, the selected date from the calendar is placed in the textbox. Regardless of whether the user clicks OK or Cancel in the calendar window, the focus is placed on the textbox. Using the calendar button is, of course, optional for the user. The user can just type whatever they want in the textbox. An editing property is available to test whether or not the control's textbox contains a valid date.
The DateTextbox has four custom properties. You set the ButtonIsTabStop and DateName properties at design time. The DateValid and Textbox_Text properties are used at runtime.
| Property |
Type |
Description |
ButtonIsTabStop |
Boolean |
Gets/sets whether the calendar button is a tab stop |
DateName |
Text |
Gets/sets the text displayed in the calendar form's title bar |
DateValid |
Read-only Boolean |
Returns true when the textbox contains a valid date. Ensures the displayed date is in the short date format (see Points of Interest below). Returns false when the textbox does not contain a string that can be converted to a valid date. |
Textbox_Text |
Text |
Gets/sets the text in the user control's textbox. A null exception is raised when this property is referenced in code and the control's textbox has not been changed in any way. To avoid this null exception, initialize the Textbox_Text property in the form's Load event. For example:
uctlDateTextbox.Textbox_Text = ""
|
The DateTextbox control raises three custom events.
| Event |
Description |
TextboxGotFocus |
Raised when the user control textbox GotFocus event fires |
|
TextboxLostFocus |
Raised when the user control textbox LostFocus event fires |
|
TextboxTextChanged |
Raised when the user control textbox TextChanged event fires |
|
The ExtendedTextbox can be used in any VB.NET project as a replacement for the standard TextBox. This user control adds several extension properties that can be used to determine how the textbox will respond to keystrokes, and what happens when the textbox gets and loses focus.
If none of the default extension properties are changed, the extension textbox behaves the same as a standard textbox. To make the setting of the extension properties more intuitive, all of the extension property names have a leading underscore so that they are listed together at the top of the sorted Visual Studio Properties window. All of the extension properties have descriptions that are displayed at the bottom of the Visual Studio Properties window. The extended textbox is also locale aware. The characters recognized by the extended textbox for minus sign, decimal point, and thousands separator are as set in the OS region settings.
The ExtendedTextbox has six custom properties that are all set at design time.
| Property |
Type |
Description |
_HighlightText |
Boolean |
When true, any pre-existing text is highlighted when the textbox receives the focus. The user can replace the pre-existing text by just starting to type. When false, text is not highlighted, and the insertion cursor is placed at the end of the text. |
_TrimSpaces |
Boolean |
When true, any leading and trailing spaces are removed from the text when the textbox loses focus. |
_Keystrokes |
Multiple options |
All ... Accepts all keystrokes the same as the standard TextBox. LettersOnly ... Accepts upper and lower case letters (a-z, A-Z) and space (to accept only lower or upper case letters, set the standard CharacterCasing property). NumbersOnly ... Accepts numbers (0-9) plus allowed number related special characters (minus sign, decimal point, thousands separator). NoSpecialChar ... Accepts upper and lower case letters (a-z, A-Z), numbers (0-9), and space. PhoneChar ... Accepts numbers (0-9) plus (), -, and space.
|
_MinusSign |
Boolean |
When true, accepts a minus sign (the minus sign character set in the OS region settings) in the first character position of the textbox. In effect only when the _Keystrokes property is set to NumbersOnly. |
_DecimalPoint |
Boolean |
When true, accepts one decimal point (the decimal point character set in the OS region settings). In effect only when the _Keystrokes property is set to NumbersOnly. |
_ThousandsSeparator |
Boolean |
When true, accepts any number of thousands separators (the digit grouping character set in the OS region settings). In effect only when the _Keystrokes property is set to NumbersOnly. |
Points of Interest
IsDate Function
The DateTextbox user control uses the IsDate function to determine whether or not the string in the control's textbox could be a valid date. This distinction is important because the string evaluated by IsDate may or may not be a complete date string as expected. For example, IsDate will return true for the string "2/13" with a US-EN region setting. This is because the string, when cast to a date, will have the current year appended. It is necessary, therefore, when a string tests as valid by IsDate, to cast that string to a date and then format the resulting date with .ToShortDateString. This ensures that you have a date string that is complete and formatted correctly.
Keyboard Cultural Sensitivity
I received an email from a teacher in Normandy, France, who was using the Extended Textbox to write software that limited student input to numerical values. The number format in France is 999 999 999,99 ... spaces for thousand separators, and a comma between whole and fractional numbers. The teacher explained that the decimal point key on his number keypad entered a period regardless of the operating system cultural setting. Instead of being able to press the decimal key on the number pad, he had to use the comma key on the keyboard. So much for speed on the 10-key!
It has been my assumption that keyboards behaved in accordance with a person's cultural settings. My assumption proved to be rash. While researching the situation raised by the teacher in Normandy, I also discovered that the space bar does not work for entering a thousands separator when the region number format calls for a space as the number grouping character. The ASCII numeric value for a space and a space thousands separator are very different.
It took until 1:00am to find a solution, but, the Extended Textbox now appears to be culturally sensitive to the number pad decimal point and the space bar. The number pad decimal key now enters the correct decimal equivalent, and the space bar can be used to enter spaces for number groupings. I have tested these enhancements with different region settings on my PC; however, I'm hoping that persons for whom 99,999.99 is not the normal number format will give the revised Extended Textbox a workout. If any other cultural insensitivities are discovered, I would appreciate hearing about them.
Conclusion
I have found many, many custom textboxes that modify how the control will respond to keystrokes. I created ExtendedTextbox so that I would have a user control that I could use in all cases, not just when I needed something different.
The DateTextbox has proven to be most valuable in my current project which depends on dates for so much of the program's functionality. Both user controls have saved me a considerable amount of development time. I hope you find them just as useful.
Licensing and Limitation of Liability
You may use all code offered in this article any way you choose without restriction.
Under no circumstances, and under no legal theory, tort, contract, or otherwise, will George Gilbert (hereafter referred to as "software author") or his licensors, be liable to the user of the Double Text library and all code offered in this article (hereafter referred to collectively as "article code"), for any damages, including any lost profits, lost data, or other indirect, special, incidental, or consequential damages, arising out of the use or inability to use the article code, and data or information supplied, even if the software author, his licensors, or authorized dealer have been advised of the possibility of such damages, or for any claim by any other party.
- 4/28/2006 ...
ExtendedTextbox changes.
- The decimal point key on the keyboard number pad has been made culturally sensitive. Likewise, the space bar works as a thousands separator when the region settings specify a space for the number grouping character. The decimal point, minus sign, and the thousands separator specified by the region settings are now obtained from the
CultureInfo object.
- 5/31/2006 ...
DateTextbox changes.
- Reduced the size of the control container to just fit the textbox and button controls.
- Added the
ButtonIsTabStop property with a default setting of False.
- Added the
TextboxGotFocus and TextboxLostFocus events.
- In the
DateValid property, removed placing of the focus on the DateTextbox when the date is not valid.
- The demo project has been updated to show off the new properties.
