AdvTextBox extends the standard WPF TextBox by adding several features:
- Password entry
- Masked text
- Auto complete
- Invalid character rejection
- Non numeric character rejection
- Select all on load or got focus
- Empty value display text
- Update binding source value on enter key press
Masking, Auto complete and character rejection make use of a feature that is unique to AdvTextBox, called a PreviewTextChangeHandler. PreviewTextChangeHandler is an abstract class with methods to preview text input, key press and text change events. These methods all return a PreviewTextChangeResponse which indicates whether the triggering event should be allowed to proceed normally, should be rejected, or if the resulting text should be coerced in some way.
Specify text to display when the value of the Text property is null or empty with property EmptyValueDisplayText.
Use property SelectAllOption to specify that all text is to be selected when the text box loads or receives focus. SelectAllOption is a flags enum with possible values None, OnFocused and OnLoaded.
Set UpdateOnEnter to true if you are using data binding and want the underlying source to be updated when the user hits the enter key.
If AttemptFocusOnLoad is set, the Focus method will be called after the control has loaded.
To use AdvTextBox for password entry, set property PasswordOption to a value other than PlainText.
The following AdvTextBox properties control password entry:
- PasswordOption – An enumeration with the following values:
- PlainText – the text box is in plain text mode.
- HidePassword – visible text is obscured with the password character. Text property contains the password.
- SecurePassword – visible text is obscured and the Text property does not contain the password. Password is obtained in code via the SecurePassword property.
- SecurePasswordBindable – visible text is obscured and Text property does not contain the password. Password is available via SecurePassword property. SecurePassword is a bindable Dependency Property.
- PasswordChar – The character that is displayed in place of the password characters.
- ShowPassword – When true, the password is displayed and can be edited in plain text.
- ShowPasswordPeekButton – When true, a button is displayed inside the text box which, when pressed, causes the password to be shown in plain text.
- SecurePassword – A value of type System.Security.SecureString which contains the password when PasswordOption is either SecurePassword or SecurePasswordBindable.
To use text masking, set property PreviewTextChangeHandler to an instance of MaskingTextChangeHandler. MaskingTextChangeHandler has bindable dependency properties Mask, PromptChar and AllowPromptAsInput. It also has a CLR property MaskProvider of type System.ComponentModel.MaskedTextProvider, which is used for all masking related logic. This property uses lazy initialization to instantiate an instance of MaskedTextProvider with the correct property values, but it does have a setter if you need to define your own.
Here is an example:
<dc:AdvTextBox> <dc:AdvTextBox.PreviewTextChangeHandler> <dc:MaskedTextChangeHandler Mask="(000) 000-0000" PromptChar="_" /> </dc:AdvTextBox.PreviewTextChangeHandler> </dc:AdvTextBox>
To enable auto complete, set PreviewTextChangeHandler to an instance of AutoCompleteTextChangeHandler with its AutoCompleteList set to an enumeration of the allowable strings. Behavior is controlled with the AutoCompleteOptions property, a flags enum with the following possible values:
- Off – auto complete is turned off.
- ReadOnly – only values in the auto complete list are allowed, but not case sensitive.
- FreeText – auto complete is enabled for strings in the auto complete list, but the user is free to type anything into the text box.
- DontConvertCase – Causes string comparisons to be case sensitive.
To display an informational message to the user when a typed character is rejected, use the AutoCompleteTextChangeHandler’s RejectionMessage property.
Here is an example:
<dc:AdvTextBox> <dc:AdvTextBox.PreviewTextChangeHandler> <dc:AutoCompleteTextChangeHandler AutoCompleteList="True, False" AutoCompleteOption="ReadOnly" RejectionMessage="Please enter either True or False."/> </dc:AdvTextBox.PreviewTextChangeHandler> </dc:AdvTextBox>
Invalid character rejection
To reject invalid characters as they are typed in, use a ValidatingTextChangeHandler. This can be used for rejecting non-numeric input or rejecting characters you specify. You can also specify the set of valid characters.
If the RejectionMessage property has a value, it will be displayed to the user when an invalid character is rejected.
To reject non-numeric input, use a ValidatingTextChangeHandler with property RejectNonNumericCharacters set to true. Property ValidNumberStyles is used to specify what characters other than integral decimal digits are to be allowed. ValidNumberStyles is an enum of type System.Globalization.NumberStyles. Its default value is Number, which will allow decimal values with thousands separator and a sign character. The following example will reject input which would result in a string that cannot be parsed into a double, with special allowance for the the currency symbol.
<dc:AdvTextBox> <dc:AdvTextBox.PreviewTextChangeHandler> <dc:ValidatingTextChangeHandler RejectNonNumericCharacters="True" ValidNumberStyles="Currency" RejectionMessage="Please enter an amount." /> </dc:AdvTextBox.PreviewTextChangeHandler> </dc:AdvTextBox>
To reject any character from a set which you specify, use property InvalidCharacters which is type IEnumerable. Alternatively, you can specify the set of valid characters through property ValidCharacters. The following example will reject the following characters: !@#$%^&*
dc:AdvTextBox> <dc:AdvTextBox.PreviewTextChangeHandler> <dc:ValidatingTextChangeHandler InvalidCharacters="!@#$%^&*" RejectionMessage="The following characters are invalid: !@#$%^&*" /> </dc:AdvTextBox.PreviewTextChangeHandler> </dc:AdvTextBox>
You can define your own class which inherits from PreviewTextChangeHandler and set an instance of it as the value of an AdvTextBox’s property of the same name. The following virtual methods can optionally be overridden.
- PreviewTextSet – Called when the text box’s Text property is set from outside. A single parameter contains the proposed text.
- PreviewTextInput – Called from the text box’s OnPreviewTextInput override. Parameters contain the new text, the current text, the caret index and the selection length.
- PreviewKeyPress – Called from the text box’s OnPreviewKeyPress override. Parameters for the pressed key, current text, caret index and selection length.
- Refresh – Called from a handler of the Freezable.Changed event. Parameters for current text, caret index and selection length.
Each of the above methods returns an instance of PreviewTextChangeResponse. PreviewTextChangeResponse has the following settable properties:
- Action – an enum of type PreviewTextChangeAction with the following possible values:
- Default – indicates take no action.
- Reject – indicates that the triggering event should be handled, canceling the change.
- Coerce – indicates that the resulting text should be coerced as defined by the CoerceTextInfo property.
- CoerceTextInfo – specifies the text, caret index and selection length resulting when Action is Coerce.
- Message – An optional value which will be displayed to the user.
- ShowMessage – set to false to override the default showing of Message or of the Message that is associated with the PreviewTextChangeHandler.
PreviewTextChangeHandler has a Message property which if set will be displayed when a rejection occurs (and the response’s ShowMessage is not false.) Likewise if a PreviewTextChangeResponse has a non-null Message. The public method ShowMessage is used for this purpose.
You can call method ShowMessage to display a message using the same technique.
The message itself is presented using a MessageAdorner. MessageAdorner inherits from System.Windows.Documents.Adorner and uses a ContentPresenter to display the message content. The ContentPresenter’s ContentTemplate defines exactly how to render the message.
Use property MessageTemplate of AdvTextBox to specify a custom DataTemplate for the message.