The WinNumericTextBox class represents an extensible and themable numerical textbox control for Windows Forms.
Textbox area
The WinNumericTextBox control is a container control which contains an inner textbox. All of the inner textbox's properties and events are accessed via the WinNumericTextBox control's TextBoxArea. Any properties that are set directly on the WinNumericTextBox control will also affect any embedded child controls. For example, if the ForeColor property of the WinNumericTextBox control is set to Color.Green, then the foreground color of all the embedded controls, including the TextBoxArea, will be changed to green. If the ForeColor property of the TextBoxArea is set to Color.Green, then only the foreground color of the TextBoxArea will be changed to green.
Input mode
The InputMode property indicates how values entered into the WinNumericTextBox control are treated. If set to NumericInputModes.FreeText (default), the control allows text selection but does not process mathematically formulas. If set to NumericInputModes.InLineCalculator, text selection is not supported and all keys are redirected to the WinCalculator control used as the WinNumericTextBox control's DropDownControl.
When the WinNumericTextBox controls is in InLineCalculator mode and an overflow or division by zero error occurs during the calculation of a mathematical equation, the WinCalculator's OverflowErrorText or DivisionByZeroText will be displayed in both the WinNumericTextBox and the formula box of the WinCalculator used as the dropdown control. If an equation that ends with "equal" (=) is pasted in the WinNumericTextBox control while it is in InLineCalculator mode, it will automatically be resolved and the result displayed. If the pasted equation does not end with "equal", the equation will be resolved when the "enter" or "equal" keys are pressed.
In FreeText mode, the DecimalSeparatorInputChars, DigitInputChars, and NegativeSignInputChars properties can be used to define what characters will be considered decimal separators, digits, and negative signs. These properties are not supported when the InputMode property is set to InLineCalculator.
Display and edit formats
The format with which the value is displayed is defined by the DisplayFormatProvider and DisplayFormatSpecifier properties. To change the formatting pattern used to display the value, the DisplayFormatSpecifier property can be set to any one of the supported formatting characters . If the WinNumericTextBox control's underlying DataType does not support the specified DisplayFormatSpecifier, an exception will be thrown.
The following code demonstrates how to use the DisplayFormatProvider and DisplayFormatSpecifier properties to display a custom formatted currency value.
The format with which the value is edited is defined by the EditFormatProvider property. In edit mode, it is not possible to specify the formatting pattern through a format specifier.
Validation, parsing, and null values
By default, values entered into the WinNumericTextBox control are handled as doubles . To change the datatype of the values, the WinNumericTextBox control's DataType property can be set to the required datatype. At all times, the Value will be limited by the MinValue and MaxValue properties. If these values are not explicitly set, the DataType's minimum and maximum values will be used.
Every time the focus is removed from the WinNumericTextBox control's TextBoxArea, the TextBoxArea's Validating event is raised. In the case where the date entered into the TextBoxArea does not match the EditFormatProvider, the Validating event's e.Cancel property will automatically be set to true (indicating that there was an error) and the focus will remain in the TextBoxArea. If the date is valid, e.Cancel will be false, and the focus will be sent to the next control.
Note that the TextBoxArea will also raise the ValidatingText event during the Validating event where extra custom text validation can be provided. e. FullValidation indicates if the text is currently being validated only against its mask or against all of the validation criteria. If the custom validation detects that the e. EditText is invalid, e. Valid should be set to false.
The number of decimals specified by the Decimals property will also be included in the validation process.
The WinNumericTextBox's Value property will always contain the last valid value. If a value is not yet entered, the NullValue and DisplayNullText properties can be used to display a string (by default, "(null)").
The TryParse method can be used to convert a string to its numeric equivalent using the formatting information retrieved from the NumericFormatInfo object assigned to the EditFormatProvider property.