PlaceholderText API addition to TextBox control

With the following PR (https://github.com/dotnet/winforms/pull/96 -> moved to https://github.com/dotnet/winforms/pull/238) we have proposed addition of new property to the TextBox control called PlaceholderText. The property accepts string which will be drawn when the control has no text it in and is not on focus. Quite useful to indicate what is the expected input.

Rationale

Currently, in order to provide guidance for the users what input is expected in a text field, the only option is to have a label next to the TextBox control. However, there are cases, where label is not appropriate and it is much more user friendly to have a placeholder text in the TextBox itself, to guide the user as to what input is expected. Think of scenarios for “Enter your username/password”

Proposed API

public string PlaceholderText {get; set;}

Description

A single public property called PlaceholderText is introduced, with no value. When the property is set, AND the TextBox has no Text set nor focus, the string from the PlaceholderText will be drawn in the TextBox control, using the SystemColors.GrayText. Once the property value is changed the new text will be drawn, if currently visible. Once the user focuses on the control, the text disappears. Different text alignments and RightToLeft are taken into consideration when the PlaceholderText is being drawn. In addition, it also works in Multiline mode.

In addition AccessibilityObject has been implemented to return the PlaceholderText when the Text is empty, hence screen readers read the PlaceholderText value and guide the users to what is expected from them as input.

On the bottom left side of the image you can see a TextBox with PlaceholderText drawn.

[wjk]

Is there any reason why we shouldn’t just use the EM_SETCUEBANNER message available since Windows Vista to do this? (I know that compatibility with really old systems — namely, Windows XP — would be negatively affected were we to do it this way, but I thought we don’t support anything before Windows 7 anyway.)

[stefanov-stefan]

Hey guys, thanks for pinging me and for the inspiration. I was not sure what I should provide, so it helped a lot.

Rationale

Currently, in order to provide guidance for the users what input is expected in a text field, the only option is to have a label next to the TextBox control. However, there are cases, where label is not appropriate and it is much more user friendly to have a placeholder text in the TextBox itself, to guide the user as to what input is expected. Think of scenarios for “Enter your username/password”

Proposed API

public string PlaceholderText {get; set;}

Description

A single public property called PlaceholderText is introduced, with no value. When the property is set, AND the TextBox has no Text set nor focus, the string from the PlaceholderText will be drawn in the TextBox control, using the SystemColors.GrayText. Once the property value is changed the new text will be drawn, if currently visible. Once the user focuses on the control, the text disappears. Different text alignments and RightToLeft are taken into consideration when the PlaceholderText is being drawn. In addition, it also works in Multiline mode.

In addition AccessibilityObject has been implemented to return the PlaceholderText when the Text is empty, hence screen readers read the PlaceholderText value and guide the users to what is expected from them as input.

On the bottom left side of the image you can see a TextBox with PlaceholderText drawn.