Class IntegerTextBox

Extends the System.Windows.Forms.TextBox class to handle integer input and validation.

Inheritance
System.Object
TextBoxExt
NumberTextBoxBase
NumericTextBox
IntegerTextBox
GridIntegerTextBox
Implements
System.ComponentModel.ISupportInitialize
System.Runtime.Serialization.ISerializable
Inherited Members
Namespace: Syncfusion.Windows.Forms.Tools
Assembly: Syncfusion.Shared.Base.dll
Syntax
public class IntegerTextBox : NumericTextBox, IThemeProvider, IVisualStyle, ISupportInitialize, ISerializable
Remarks

The IntegerTextBox is derived from textbox and provides all the functionality of a textbox and adds additional functionality of its own.

Collecting integer input in a consistent format requires validation code that needs to be built into the application when using the Windows Forms textbox control. The IntegerTextBox includes all this logic into its methods and properties and makes it easy for the developer and the end user to collect and enter double data.

The IntegerTextBox is also closely tied to the globalization settings of the operating system for number related properties. Please refer to the System.Globalization.NumberFormatInfo class for a detailed explanation of globalization and number related attributes.

The IntegerTextBox has full support for the Windows Forms designer and you can just drag-and-drop and set properties on the control just as you would with the Windows Forms textbox.

The IntegerTextBox also raises a ValidationError event when inappropriate data is entered into the control.

All clipboard functions such as copy, paste and cut are also supported with special accommodations for a number related issues.

Constructors

IntegerTextBox()

Overloaded. Creates an object of type IntegerTextBox.

Declaration
public IntegerTextBox()
Remarks

The IntegerTextBox object will be initialized with the default values for the display and data properties. You need to set any specific values.

Properties

AccessibilityEnabled

Gets or sets a value indicating whether the control should enable its Accessibility support.

Declaration
public bool AccessibilityEnabled { get; set; }
Property Value
Type
System.Boolean

AllowLeadingZeros

Indicates whether to allow insets zero in the beginning value.

Declaration
public bool AllowLeadingZeros { get; set; }
Property Value
Type
System.Boolean

IntegerValue

Gets / sets the integer value of the control. This will be formatted and displayed.

Declaration
public long IntegerValue { get; set; }
Property Value
Type
System.Int64

IsNullValue

Gets or sets a value indicating whether the current value is considered null.

Declaration
[Obsolete("This property will not be used in future. Use NullState property to get the null state of the text box")]
public bool IsNullValue { get; set; }
Property Value
Type
System.Boolean

MaxValue

Gets / sets the maximum value that can be set through the IntegerTextBox.

Declaration
public long MaxValue { get; set; }
Property Value
Type
System.Int64

MinValue

Gets / sets the minimum value that can be set through the IntegerTextBox.

Declaration
public long MinValue { get; set; }
Property Value
Type
System.Int64

NumberDecimalDigits

Gets / sets the maximum number of digits for the decimal portion.

Declaration
public int NumberDecimalDigits { get; set; }
Property Value
Type
System.Int32
Remarks

This property is always set to zero for the IntegerTextBox.

NumberDecimalSeparator

Gets / sets the decimal separator character that will be used for the display.

Declaration
public string NumberDecimalSeparator { get; set; }
Property Value
Type
System.String
Remarks

This value is initially set from the System.Globalization.NumberFormatInfo and can be changed based on your requirements or based on the locale.

Text

Overrides the Text property of System.Windows.Forms.TextBox.

Declaration
public string Text { get; set; }
Property Value
Type
System.String
Remarks

This property is overriden in order to normalize the data that is set to the Text property and format it as needed. The method InsertString(String, Int32, Int32, String, Boolean) is used to format the data.

ThemeStyle

Gets or sets the IntegerTextBoxVisualStyle used to customize the appearance of the IntegerTextBox.

Declaration
public IntegerTextBoxVisualStyle ThemeStyle { get; set; }
Property Value
Type
IntegerTextBoxVisualStyle
Remarks

This ThemeStyle setting is applied only when a VisualStyle-based theme is active on the control.

UseNullString

Gets or sets a value indicating whether the NullString should be used to represent null values.

Declaration
[Obsolete("This property will not be used in future.")]
public bool UseNullString { get; set; }
Property Value
Type
System.Boolean

Methods

ApplyFormatting(String)

Formats the given text according to the current setting.

Declaration
protected override string ApplyFormatting(string rawValue)
Parameters
Type Name Description
System.String rawValue
Returns
Type
System.String
Overrides

CheckForMinMax(String, Boolean)

Validates whether the given numeric string falls within the configured minimum and maximum range.

Declaration
protected override bool CheckForMinMax(string currentTextValue, bool ignoreLength)
Parameters
Type Name Description
System.String currentTextValue

The string representation of the numeric value to validate.
System.Boolean ignoreLength

Indicates whether to ignore length constraints during validation.
Returns
Type
System.Boolean
Overrides

CheckIfNegative(String)

Determines whether the given numeric string represents a negative value.

Declaration
protected override bool CheckIfNegative(string rawValue)
Parameters
Type Name Description
System.String rawValue

The raw string value to check.
Returns
Type
System.Boolean
Overrides

CheckIsZero()

Checks whether the current value is zero.

Declaration
protected override bool CheckIsZero()
Returns
Type
System.Boolean
Overrides

CheckNullStringIsInRange(String)

Checks whether the provided null string value falls within the valid numeric range.

Declaration
protected override bool CheckNullStringIsInRange(string nullString)
Parameters
Type Name Description
System.String nullString

The string to validate.
Returns
Type
System.Boolean
Overrides

CreateAccessibilityInstance()

Creates a custom accessibility instance for the IntegerTextBox control.

Declaration
protected override AccessibleObject CreateAccessibilityInstance()
Returns
Type
System.Windows.Forms.AccessibleObject
Overrides

CursorShouldBeMoved(Int32, Boolean)

Determines whether the cursor should be moved based on the current position and decimal context.

Declaration
protected override int CursorShouldBeMoved(int startPosition, bool inDecimalPosition)
Parameters
Type Name Description
System.Int32 startPosition

The current cursor position.
System.Boolean inDecimalPosition

Indicates whether the cursor is in the decimal portion of the number.
Returns
Type
System.Int32
Overrides

Dispose(Boolean)

Releases the unmanaged resources used by the IntegerTextBox and optionally releases the managed resources.

Declaration
protected override void Dispose(bool disposing)
Parameters
Type Name Description
System.Boolean disposing

true to release both managed and unmanaged resources; false to release only unmanage resources.
Overrides

FormatChanged(String, NumberFormatInfo)

Declaration
protected override void FormatChanged(string currentText, NumberFormatInfo previousFormat)
Parameters
Type Name Description
System.String currentText
System.Globalization.NumberFormatInfo previousFormat
Overrides

GetControlName(String)

Helps to override the ThemeName property settings

Declaration
public override string GetControlName(string controlName)
Parameters
Type Name Description
System.String controlName

ThemeName
Returns
Type
System.String
Overrides

GetInitialZeroCount(String, Int32)

Gets the count of leading zeros in the current text starting from a given position.

Declaration
protected override int GetInitialZeroCount(string currentText, int startPosition)
Parameters
Type Name Description
System.String currentText

The current text in the control.
System.Int32 startPosition

The position from which to start counting zeros.
Returns
Type
System.Int32
Overrides

GetNumberPartLength(Int64)

Gets the length of the numeric part of a given integer value.

Declaration
protected int GetNumberPartLength(long numberValue)
Parameters
Type Name Description
System.Int64 numberValue

The integer value to evaluate.
Returns
Type
System.Int32

GetNumberValue(String, Int32)

Extracts and returns the numeric value from a formatted text string starting at a given position.

Declaration
protected override string GetNumberValue(string formattedText, int startPosition)
Parameters
Type Name Description
System.String formattedText

The formatted string containing the number.
System.Int32 startPosition

The position in the string from which to begin extraction.
Returns
Type
System.String
Overrides

GetValue()

Gets the current numeric value of the control.

Declaration
protected override object GetValue()
Returns
Type
System.Object
Overrides

HandleBackspaceKey()

Handles the behavior of the Backspace key in a custom numeric text box control.

Declaration
protected override bool HandleBackspaceKey()
Returns
Type
System.Boolean
Overrides

HandleDecimalKey()

Handles the behavior when the decimal key is pressed.

Declaration
protected override bool HandleDecimalKey()
Returns
Type
System.Boolean
Overrides

HandleDeleteKey()

Handles the behavior of the Delete key in a custom text box control.

Declaration
protected override bool HandleDeleteKey()
Returns
Type
System.Boolean
Overrides

InitializeNumberTextBox()

Overrides InitializeNumberTextBox().

Declaration
protected override void InitializeNumberTextBox()
Overrides

InsertString(String, Int32, Int32, String, Boolean)

Inserts a string into the current text box content, handling null values and applying custom logic for paste operations.

Declaration
protected override bool InsertString(string currentText, int startPosition, int selectionLength, string textToBeInserted, bool pasteOperation)
Parameters
Type Name Description
System.String currentText

The current text in the text box.
System.Int32 startPosition

The position at which to begin the insertion.
System.Int32 selectionLength

The length of the selected text to be replaced.
System.String textToBeInserted

The string to be inserted.
System.Boolean pasteOperation

Indicates whether the operation is a paste action.
Returns
Type
System.Boolean
Overrides

IsAssignable(Object)

Determines whether the given object can be assigned to the control's numeric value.

Declaration
protected override bool IsAssignable(object val)
Parameters
Type Name Description
System.Object val

The object to check.
Returns
Type
System.Boolean
Overrides

IsValidNumberValue(String)

Validates whether the given string represents a valid integer number.

Declaration
protected override bool IsValidNumberValue(string intString)
Parameters
Type Name Description
System.String intString

The input string to validate.
Returns
Type
System.Boolean
Overrides

OnEnabledChanged(EventArgs)

Raises the System.Windows.Forms.Control.EnabledChanged event.

Declaration
protected override void OnEnabledChanged(EventArgs e)
Parameters
Type Name Description
System.EventArgs e

An System.EventArgs that contains the event data.
Overrides

OnEnter(EventArgs)

Overrides the System.Windows.Forms.Control.OnEnter(System.EventArgs) method.

Declaration
protected override void OnEnter(EventArgs args)
Parameters
Type Name Description
System.EventArgs args

The event data.
Overrides
Remarks

Saves the current IntegerValue so that it can be compared during validation. The IntegerValueChanged and TextChanged event will only be raised if the value is different during validation.

OnGotFocus(EventArgs)

Helps to override the OnGotFocus events

Declaration
protected override void OnGotFocus(EventArgs e)
Parameters
Type Name Description
System.EventArgs e

An System.EventArgs that contains the event data.
Overrides

OnIntegerValueChanged(EventArgs)

Raises the IntegerValueChanged event.

Declaration
protected virtual void OnIntegerValueChanged(EventArgs e)
Parameters
Type Name Description
System.EventArgs e

A System.EventArgs that contains the event data.

OnTextChanged(EventArgs)

Overrides OnTextChanged.

Declaration
protected override void OnTextChanged(EventArgs e)
Parameters
Type Name Description
System.EventArgs e

The event data.
Overrides

OnThemeNameChanged(String)

Helps to apply the ThemeName settings in control

Declaration
public override void OnThemeNameChanged(string themeName)
Parameters
Type Name Description
System.String themeName

ThemeName
Overrides

OnValidated(EventArgs)

Raises the Validated event and performs additional control-specific validation logic.

Declaration
protected override void OnValidated(EventArgs e)
Parameters
Type Name Description
System.EventArgs e

An System.EventArgs that contains the event data.

OnValidating(CancelEventArgs)

Performs validation logic when the control is validating.

Declaration
protected override void OnValidating(CancelEventArgs e)
Parameters
Type Name Description
System.ComponentModel.CancelEventArgs e

An System.ComponentModel.CancelEventArgs that contains the event data.
Overrides

PerformMinMaxValidation()

performs the Min/Max validation.

Declaration
protected virtual void PerformMinMaxValidation()

PrepareInsertString(String, Int32, Int32, String, Boolean)

Prepares the string to be inserted into the text box, adjusting the current text if the integer value is zero.

Declaration
protected override NumberModifyState PrepareInsertString(string currentText, int startPosition, int selectionLength, string textToBeInserted, bool pasteOperation)
Parameters
Type Name Description
System.String currentText

The current text in the text box.
System.Int32 startPosition

The starting position for the insertion.
System.Int32 selectionLength

The length of the selected text to be replaced.
System.String textToBeInserted

The text to be inserted.
System.Boolean pasteOperation

Indicates whether the operation is a paste action.
Returns
Type
NumberModifyState
Overrides

ResetText()

Resets the text of the control to its default value.

Declaration
public override void ResetText()

SetIntegerValue(Int64)

Sets the integer value of the control and applies formatting.

Declaration
protected void SetIntegerValue(long newValue)
Parameters
Type Name Description
System.Int64 newValue

The new integer value to set.

SetNullNumberValue()

Sets the control's value to represent a null numeric value.

Declaration
protected override void SetNullNumberValue()
Overrides

SetTextProperty(String)

Sets the text property of the control and updates the internal value accordingly.

Declaration
protected override void SetTextProperty(string newText)
Parameters
Type Name Description
System.String newText

The new text to set.
Overrides

SetValue(Object)

Sets the control's numeric value from a given object.

Declaration
protected override void SetValue(object val)
Parameters
Type Name Description
System.Object val

The object containing the value to set.
Overrides

ShouldSerializeNumberDecimalDigits()

Indicates whether to serialize NumberDecimalDigits property value.

Declaration
public bool ShouldSerializeNumberDecimalDigits()
Returns
Type
System.Boolean

ShouldSerializeNumberDecimalSeparator()

Indicates whether to serialize NumberDecimalSeparator property value

Declaration
public bool ShouldSerializeNumberDecimalSeparator()
Returns
Type
System.Boolean

ShouldSerializeText()

Indicates whether to serialize the Text property if it is null or quals NullString

Declaration
protected bool ShouldSerializeText()
Returns
Type
System.Boolean

ToggleNegative(String)

Toggles the sign of the integer value represented by the current text.

Declaration
protected override string ToggleNegative(string currentText)
Parameters
Type Name Description
System.String currentText

The current text representing an integer value.
Returns
Type
System.String
Overrides

Events

IntegerValueChanged

Occurs when the DecimalValue property is changed.

Declaration
public event EventHandler IntegerValueChanged
Event Type
Type
System.EventHandler

Implements

System.ComponentModel.ISupportInitialize
System.Runtime.Serialization.ISerializable