TextBoxHint

Elkay

4.50/5 (16 votes)

Mar 8, 2009

CPOL

3 min read

68782

4031

Standard .NET TextBox control with three additional properties that allow the developer to add a 'hint' to the text...sort of like a tooltip but always visible while the control is empty.

Introduction

An application I'm building has numerous Tree controls on a number of forms. Some of the trees produced contain thousands of rows of data. My users requested a search capability that spanned several columns of data in those trees so I was unable to use the built-in search functions.

That left me to write my own search routines which included input from Text Boxes sized and positioned directly above each column the user could search on... unfortunately that also meant no room for a Label to describe what the user could search on so I thought, "Why not put the label contents inside the TextBox?" and that lead me to build the TextBoxHint control.

Background

I didn't want to use the Text property to hold the description - I also wanted the description to 'fade out' like you'll see in some WPF apps.

Immediately I set out to create a User Control that inherits from a TextBox. I figured I could just override the Paint and from there... sounds logical right? WRONG! Turns out, the .NET TextBox isn't really a .NET control at all! It's a wrapper to a very old Win32 control - Searching on how to override the Paint was nothing short of a several hour, hair and tooth pulling experience but in the end I figured out what was needed by reading an article from a very old, VB website called www.vbaccelerator.com.

Using the Cursor

Add a reference to the TextBoxHint.dll into .NET ToolBox and use it just like you would a TextBox control.

TextBoxHint Extended Properties

`HintDetails.HintText`		This is the text that is displayed inside the `Textbox` that will fade out once the user enters data.
`HintDetails.HintColor`		The color used to paint the `HintText`
`HintDetails.HintFadeSpeed`		An integer from 0-5 (if you enter a value < 0, it will default to 0. Enter one > 5 and it will default to 5.
`HintDetails.HintTextAlign`		Can be set to Left (default), Center or Right
`CharFilter`		Can be set to All (default), NumericOnly (0-9) and AlphaOnly (A-Z, a-z)
`CharFilterSpecial`		Allows you to extend the allowed characters selected in `CharFilter` If you select `CharFilter=NumericOnly` and set `CharFilterSpecial` to "`AaBbCc`" the `TextBox` will allow 0-9 and Aa, Bb or Cc.

Using the Control

You can adjust how long the Hint takes to fade out by increasing the HintFadeSpeed:

0 = Instantly vanish when the user enters data into the TextBox
1 = Slow Fade out (approximately 2.5 seconds)
2-9 = Faster Fade out
10 = Fastest Fade out

If you would like to allow for longer or shorter fading, you can adjust the Interval on the Timer used that handles the repainting during fading:

Public Sub New()
	' This call is required by the Windows Form Designer.
	InitializeComponent()

	' Add any initialization after the InitializeComponent() call.
	FadeTimer = New System.Windows.Forms.Timer
	FadeTimer.Interval = 50	' Make this smaller for faster fading 
				' - larger for slower
	FadeTimer.Enabled = False
	AddHandler FadeTimer.Tick, AddressOf FadeTimer_Tick
End Sub

If you would like to extend the range of Fade, adjust the maximum allowed HintFadeSpeed:

Private _HintFadeSpeed As Integer = 3
Public Property HintFadeSpeed() As Integer
	Get
		Return _HintFadeSpeed
	End Get
	Set(ByVal value As Integer)
		_HintFadeSpeed = value
		If value < 0 Then _HintFadeSpeed = 0
		If value > 10 Then _HintFadeSpeed = 10
	End Set
End Property

Sure, I know my use of these rather basic Properties is extremely cryptic. If you would like to see some samples of how you can manage these properties in a more elegant manner, there are numerous, fantastic samples here on CodeProject. (I demonstrate a few in my article, Border Container.)

Points of Interest

This control has the four 'Hint' properties nested inside an expandable Property called HintDetails. You can see how this is done by looking at the Property Converter code found in TextBoxHintDetails.vb.

History

3/5/2009

Control is introduced to CodeProject

3/11/2009 - Control is upgraded

Added HintTextAlign allowing the developer to align where the HintText is displayed (thanks to Frank for the suggestion)
The four Hint properties have been moved into an Expandable Property HintDetails and two additional properties allow the developer to control the type of allowable keys: CharFilter and CharFilterSpecial