ENHANCED NumberTextBoxes
| Platform | Windows Forms |
| Product | Tools |
| Control | Editors Package >> Editor Controls>> NumberTextBoxes |
| Feature(s) | Enhancing Editor Controls |
We’ve revamped NumberTextBoxControls ( IntegerTextBox, DoubleTextBox, CurrencyTextBox and PercentageTextBox). In this revamping process we’ve redefined the controls behavior and ensured the functionality of all the APIs in the mentioned controls.
We’ve moved all the common features and behaviors in to a single base class which is NumberTextBoxBase and overridden the required behavior alone in the respective controls.
PROPERTIES DEPRECIATED
| PROPERTY | ALTERNATIVES | COMMENTS |
| NullState | IsNull | Depreciated as it had Getter and Setter and was confusing. See IsNull for more details. |
| UseNullString | AllowNull | This behavior is incorporated with AllowNull; previously both AllowNull and UseNullString existed. They were removed for better clarity |
| IsNullValue | IsNull | IsNullValue means the same as NullState and IsNull; it has been deprecated for better clarity. |
| MaxLength | MaxValue, NumberDecimalDigits (This is not available for IntegerTextBox) | This makes validation complex with MaxValue as 1000 and MaxLength as 2. The same behavior can be achieved with the alternatives suggested. |
| EnforceMinMaxDuringValidating | OnValidationFailed.KeepFocus | No need for EnforceMinMaxDuringValidating, as MinMaxValidation exists already. We’ve tweaked the controls to keep the focus inside the control when validation fails, which was the original intention of EnforceMinMaxDuringValidating, if needed by using OnValidationFailed. |
NEWLY ADDED APIs
| PROPERTY | DESCRIPTION | BEHAVIOR |
| IsNull (Read Only) | Returns a Boolean specifying the NullState of the control | True when Control.Text equals String.Empty or NullString |
| AllowNull | Specifies whether the field can be null. | Related to NullString. When the field is null, NullString will be set. If you want to empty the control when the entire content is deleted then set AllowNull to true and NullString to String.Empty. |
| NullString | Specifies the string that will be set when the field is null. | Allow null must be true to set this string. If false, then Zero or MinValue, whichever is higher, will be set. Leave it blank if the field has to be empty |
| *OnValidationFailed | Specifies the action to be performed when validation fails on a control loosing focus.
| SetNullString, SeMinOrMax, KeepFocus. (Refer to the notes for more details.) |
BEHAVIORAL CHANGES
| PROPERTY | DESCRIPTION | BEHAVIOR |
| *MinMaxValidation.OnKeyPress | Each and every key press is validated to ensure the value meets the constraints. | This is most useful when MinValue is a single digit. (Refer to the notes for more details.) |
| *MinMaxValidation.OnLostFocus | Validation happens only when the control loses focus. | This allows the user to enter any value that will be validated when the focus is lost. You can make use of the OnValidationFailed property to gain control over what has to be done when validation fails. (Refer to the notes for more details.) |
| MinValue | Sets the minimum value allowed for the control. It cannot be greater than MaxValue. | An exception will be thrown; reset the MaxValue accordingly. |
| MaxValue | Sets the maximum value allowed in the control. It cannot be lesser than MinValue. | An exception will be thrown; reset the MinValue accordingly. |
| NullString | String to be displayed when the control’s value is made null. Cannot be a numeric value that could break the MinValue or MaxValue constraints. | Example: MinValue 10, MaxValue 100 and NullString as “111” will break the min-max values. |
Note:
Below are some general use-case scenarios for a better understanding of the behavior changes of the NumberTextBox controls (IntegerTextBox, DoubleTextBox, CurrencyTextBox, and PercentageTextBox).
Scenarios for better understanding:
- With MinMaxValidation.OnKeyPress and MinValue as 10 – Each and every key press will be validated to meet the constraints, so this will not allow you to enter values less than 10, even if you try to enter 11 you cannot input the value as every keystroke is validated. This behavior is useful when MinValue is a single digit; in such cases, go for inMaxValidation.OnLostFocus.
- With MinMaxValidation.OnLostFocus – User input will be validated only when a control loses focus. Hence, end-users can input any value. OnValidationFailed will give you access to what action [SetNullString, SetMinorMax, KeepFocus] has to be done when validation for the input fails.
- With OnValidationFailed.SetNullString and AllowNull as False – The control will keep its focus as AllowNull is False.
If you need any clarifications or find any difficulties in using the control, please feel free to contact Syncfusion Technical support through Direct-Trac or our public Community Forums.
Thanks.
