Class PercentTextBox

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

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

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

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

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

The PercentTextBox 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 PercentTextBox 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 accomodations for percent-related issues.

Constructors

PercentTextBox()

Overloaded. Creates an object of type PercentTextBox.

Declaration
public PercentTextBox()
Remarks

The PercentTextBox 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

AllowNull

Gets or sets the NULL string to be displayed.

Declaration
public override bool AllowNull { get; set; }
Property Value
Type
System.Boolean
Overrides

BindablePercentValue

Wrapper property around the selected value. Use this property if you want to be able to set the value of the control to NULL.

Declaration
public object BindablePercentValue { get; set; }
Property Value
Type
System.Object

ClipText

Returns the clipped text without the formatting.

Declaration
public override string ClipText { get; }
Property Value
Type
System.String
Overrides
Remarks

For example, if the Text in the CurrencyTextBox is $45,000.00, the ClipText property will give 45000.00.

DoubleValue

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

Declaration
public double DoubleValue { get; set; }
Property Value
Type
System.Double

FormattedText

Returns the formatted text with the formatting.

Declaration
public override string FormattedText { get; }
Property Value
Type
System.String
Overrides
Remarks

For example, if the Text in the CurrencyTextBox is $45,000.00, the FormattedText property will give $45,000.00.

MaxValue

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

Declaration
public double MaxValue { get; set; }
Property Value
Type
System.Double

MinValue

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

Declaration
public double MinValue { get; set; }
Property Value
Type
System.Double

PercentDecimalDigits

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

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

If there is a need to have a different value based on the locale, it will be automatically changed if the UseLocaleDefault property is True.

PercentDecimalSeparator

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

Declaration
public string PercentDecimalSeparator { 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.

PercentGroupSeparator

Gets / sets the separator to be used for grouping digits.

Declaration
public string PercentGroupSeparator { 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.

PercentGroupSizes

Gets / sets the grouping of PercentDigits in the PercentTextBox.

Declaration
public int[] PercentGroupSizes { get; set; }
Property Value
Type
System.Int32[]
Remarks

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

PercentNegativePattern

Gets / sets the pattern to use when the value is negative.

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

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

PercentNegativePatterns

The negative patterns.

Declaration
protected string[] PercentNegativePatterns { get; set; }
Property Value
Type
System.String[]

PercentPositivePattern

Gets / sets the pattern to use when the value is positive.

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

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

PercentSymbol

Gets / sets the percent symbol to be used in the PercentTextBox.

Declaration
public string PercentSymbol { 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.

PercentValue

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

Declaration
public double PercentValue { get; set; }
Property Value
Type
System.Double

SwitchModeOnFocus

Indicates whether the PercentTextBox should allow editing in numeric mode when it receives focus.

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

Text

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

Declaration
public override 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) is used to format the data.

ThemeStyle

Gets or sets the PercentTextBoxVisualStyle value used to customize the appearance of the PercentTextBox.

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

This ThemeStyle settings will be applied only when the VisualStyleBased theme has been applied to the control.

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)

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

CheckIfNegative(String)

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

CheckIsZero()

Checks whether the current value is zero and not null.

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

CompleteSubtractKey(NumberModifyState)

Declaration
protected override bool CompleteSubtractKey(NumberModifyState state)
Parameters
Type Name Description
NumberModifyState state
Returns
Type
System.Boolean
Overrides

CreateAccessibilityInstance()

Creates a custom accessibility instance for the control if accessibility is enabled.

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

Dispose(Boolean)

Clean up any resources being used.

Declaration
protected override void Dispose(bool disposing)
Parameters
Type Name Description
System.Boolean disposing
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

GetAdjustedValue(Double)

Declaration
public virtual double GetAdjustedValue(double newValue)
Parameters
Type Name Description
System.Double newValue
Returns
Type
System.Double

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

GetDecimalDigits()

Declaration
protected override int GetDecimalDigits()
Returns
Type
System.Int32
Overrides

GetDecimalSeparator(NumberFormatInfo)

Override this to return PercentDecimalSeparator in PercentTextBox.

Declaration
protected override string GetDecimalSeparator(NumberFormatInfo info)
Parameters
Type Name Description
System.Globalization.NumberFormatInfo info
Returns
Type
System.String
Overrides

GetGroupSeparator(NumberFormatInfo)

Override this to return PercentGroupSeparator in PercentTextBox.

Declaration
protected override string GetGroupSeparator(NumberFormatInfo info)
Parameters
Type Name Description
System.Globalization.NumberFormatInfo info
Returns
Type
System.String
Overrides

GetNumberPartLength(Double)

Declaration
protected int GetNumberPartLength(double numberValue)
Parameters
Type Name Description
System.Double numberValue
Returns
Type
System.Int32

GetNumberValue(String, Int32)

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

GetValue()

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

HandleBackspaceKey()

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

HandleBackspaceKeyChar()

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

HandleCharacterKey(Char)

Overrides the base behavior to implement support for NumberMode. In this mode, the base behavior of formatting each key is not followed. The key is validated internally to check for Max and Min conditions and then displayed as is without the formatting. The key will be ignored if the supressKeyPress value is not set to False. This is set to False when a valid key press is encountered.

Declaration
protected override bool HandleCharacterKey(char charToBeInserted)
Parameters
Type Name Description
System.Char charToBeInserted
Returns
Type
System.Boolean
Overrides

HandleDecimalKey()

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

HandleDeleteKey()

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

HandleSubtractKey()

Invoked when the negative key is pressed.

Declaration
protected override NumberModifyState HandleSubtractKey()
Returns
Type Description
NumberModifyState

True if the key is handled; false otherwise.
Overrides
Remarks

The defined behavior for this key is to toggle the sign (negativity) of the content of the CurrencyTextBox.

InitializeNumberTextBox()

Overrides InitializeNumberTextBox().

Declaration
protected override void InitializeNumberTextBox()
Overrides

IsAssignable(Object)

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

OnBindablePercentValueChanged(EventArgs)

Raises the BindablePercentValueChanged event.

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

A System.EventArgs that contains the event data.

OnDoubleValueChanged(EventArgs)

Raises the DoubleValueChanged event.

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

A System.EventArgs that contains the event data.

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 DoubleValue so that it can be compared during validation. The DoubleValueChanged and TextChanged event will only be raised if the value is different during validation. Also switches mode if the SwitchModeOnFocus property is set.

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

OnLeave(EventArgs)

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

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

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 OnValidated(EventArgs) event and triggers custom 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)

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

ParseForNegativeFormat(String, NumberFormatInfo)

Overrides ParseForNegativeFormat(String).

Declaration
protected override bool ParseForNegativeFormat(string currentText, NumberFormatInfo info)
Parameters
Type Name Description
System.String currentText

The text to be parsed.
System.Globalization.NumberFormatInfo info
Returns
Type Description
System.Boolean

True if the value is negative; false otherwise.
Overrides

Paste()

Pastes the data in the clipboard into the PercentTextBox control.

Declaration
public void Paste()
Remarks

The data will be formatted before being pasted into the text box.

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

Prepares the control for inserting a string, handling formatting and validation.

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 control.
System.Int32 startPosition

The position at which the new text will be inserted.
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

RemoveFormatting(String, NumberFormatInfo, Boolean)

Declaration
protected override string RemoveFormatting(string formattedText, NumberFormatInfo info, bool padIfEmpty)
Parameters
Type Name Description
System.String formattedText
System.Globalization.NumberFormatInfo info
System.Boolean padIfEmpty
Returns
Type
System.String
Overrides

ResetMaxValue()

Resets the value to the default.

Declaration
public void ResetMaxValue()

ResetMinValue()

Resets the value to the default.

Declaration
public void ResetMinValue()

ResetText()

Restores the CurrencyNumberDigits to the MaximumLength.

Declaration
protected void ResetText()

SetDoubleValue(Double)

Declaration
protected void SetDoubleValue(double newValue)
Parameters
Type Name Description
System.Double newValue

SetNullNumberValue()

Declaration
protected override void SetNullNumberValue()
Overrides

SetNullState(Double)

Declaration
protected void SetNullState(double val)
Parameters
Type Name Description
System.Double val

SetPercentValue(Object)

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

SetTextProperty(String)

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

SetValue(Object)

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

ShouldSerializeMaxValue()

Indicates whether the MaxValue property should be serialized.

Declaration
public bool ShouldSerializeMaxValue()
Returns
Type Description
System.Boolean

True if the value is not equal to System.Double.MaxValue.

ShouldSerializeMinValue()

Indicates whether the MinValue property should be serialized.

Declaration
public bool ShouldSerializeMinValue()
Returns
Type Description
System.Boolean

True if the value is not equal to System.Decimal.MaxValue.

ShouldSerializePercentDecimalSeparator()

Indicates whether the PercentDecimalSeparator should not be serialized if the UseLocaleDefault property is set.

Declaration
protected bool ShouldSerializePercentDecimalSeparator()
Returns
Type
System.Boolean

ShouldSerializePercentGroupSeparator()

Indicates whether PercentGroupSeparator should not be serialized if the UseLocaleDefault property is set.

Declaration
protected bool ShouldSerializePercentGroupSeparator()
Returns
Type
System.Boolean

ShouldSerializePercentGroupSizes()

Indicates whether the PercentGroupPattern should not be serialized if the UseLocaleDefault property is set.

Declaration
protected bool ShouldSerializePercentGroupSizes()
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)

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

Validate(Boolean)

Validates the control.

Declaration
public override bool Validate(bool bRaiseValidationError)
Parameters
Type Name Description
System.Boolean bRaiseValidationError

Indicates whether the validation error is to be raised.
Returns
Type
System.Boolean
Overrides

Events

BindablePercentValueChanged

Occurs when the BindableValue property is changed.

Declaration
public event EventHandler BindablePercentValueChanged
Event Type
Type
System.EventHandler

DoubleValueChanged

Occurs when the DoubleValue property is changed.

Declaration
public event EventHandler DoubleValueChanged
Event Type
Type
System.EventHandler

Implements

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