syncfusion-winforms-percent-textbox

Implementing Syncfusion WinForms PercentTextBox

The PercentTextBox is a textbox-derived control that enables users to display, enter, and manage percentage values in Windows Forms applications. It provides built-in formatting, validation, and data binding capabilities for percentage inputs.

When to Use This Skill

Use this skill when you need to:

• Collect percentage values from users in a Windows Forms application
• Display percentage data with consistent formatting
• Validate percentage inputs within min/max bounds
• Bind percentage values to data sources
• Handle value changes and validation errors programmatically
• Customize number formatting for percentages (decimal places, separators)
• Support both percent and decimal representations of the same value

Component Overview

PercentTextBox derives from the Windows Forms TextBox and adds:

• Automatic percentage formatting and validation
• Support for multiple value representations (PercentValue, DoubleValue, BindableValue)
• Min/Max constraint enforcement with validation
• Customizable number formatting (decimal digits, separators)
• Rich event system for value changes and validation
• Null value handling
• Keyboard input control for negative values

Documentation Navigation Guide

Select a reference based on what you need to accomplish:

Getting Started

📄 Read: references/getting-started.md

• Installation and assembly references
• Adding control via designer and code
• Basic value initialization
• Minimal working example

Value Management

📄 Read: references/value-management.md

• PercentValue vs DoubleValue properties
• BindableValue and BindablePercentValue for data binding
• DefaultValue property usage
• Value retrieval and conversion patterns

Constraints and Validation

📄 Read: references/constraints-and-validation.md

• Setting minimum and maximum percentage values
• Min/Max enforcement during validation
• Null value handling (AllowNull, NullString, NullFormat)
• ValidationError event handling
• Validation error prevention strategies

Formatting and Display

📄 Read: references/formatting-and-display.md

• Customizing decimal digits (PercentDecimalDigits)
• Decimal and group separators
• Group size configuration
• Format customization examples
• Number format patterns

Behavior and Input

📄 Read: references/behavior-and-input.md

• Negative value input handling (NegativeInputPendingOnSelectAll)
• ClipText property for unformatted text
• User input processing
• Keyboard behavior control

Events and Data Binding

📄 Read: references/events-and-data-binding.md

• BindablePercentValueChanged event
• BindableValueChanged event
• DoubleValueChanged event
• Data binding to BindablePercentValue
• Event handler implementation patterns
• Responding to value changes

Properties and API Reference

📄 Read: references/properties-and-api-reference.md

• Complete property reference organized by category
• Essential methods (ResetMaxValue, ResetMinValue, etc.)
• Read-only properties (FormattedText, ClipText)
• Quick lookup guide for common scenarios

Quick Start Example

Basic Setup (Designer)

1. Drag PercentTextBox from toolbox to form
2. Set PercentValue property to initial value (e.g., 50)
3. Set MaxValue and MinValue for constraints
4. Subscribe to BindablePercentValueChanged event to handle changes

Basic Setup (Code)

using Syncfusion.Windows.Forms.Tools;

// Create instance
PercentTextBox percentTextBox1 = new PercentTextBox();
this.Controls.Add(percentTextBox1);

// Set value
percentTextBox1.PercentValue = 50;

// Set constraints
percentTextBox1.MaxValue = 100;
percentTextBox1.MinValue = 0;

// Subscribe to value changed event
percentTextBox1.BindablePercentValueChanged += (sender, e) => 
{
    Console.WriteLine($"Percent: {percentTextBox1.PercentValue}%");
};

Common Patterns

Pattern 1: Initialize with Default Value and Constraints

var percentBox = new PercentTextBox();
percentBox.PercentValue = 25;
percentBox.MinValue = 0;
percentBox.MaxValue = 100;
percentBox.PercentDecimalDigits = 2;

Pattern 2: Bind to Data Source

percentTextBox1.DataBindings.Add("BindablePercentValue", dataSource, "PercentageField");

Pattern 3: Handle Validation Errors

percentTextBox1.ValidationError += (sender, e) =>
{
    MessageBox.Show($"Invalid input: {e.ErrorMessage}");
};

Pattern 4: Custom Number Format

percentTextBox1.PercentDecimalDigits = 3;
percentTextBox1.PercentDecimalSeparator = ".";
percentTextBox1.PercentGroupSeparator = ",";
percentTextBox1.PercentGroupSizes = new int[] { 2 };

Key Properties

Property	Type	Purpose
PercentValue	double	Gets/sets the percentage value (0-100)
DoubleValue	double	Gets/sets the decimal value (0-1)
BindablePercentValue	double?	Nullable percent value for data binding
BindableValue	double?	Nullable decimal value for data binding
MaxValue	double	Maximum allowed value
MinValue	double	Minimum allowed value
DefaultValue	double	Default value when reset
AllowNull	bool	Allows null/empty input
NullString	string	Display text when null
PercentDecimalDigits	int	Number of decimal places
PercentDecimalSeparator	string	Decimal separator character
PercentGroupSeparator	string	Thousands separator
PercentGroupSizes	int[]	Group size for thousands
NegativeInputPendingOnSelectAll	bool	Allow negative on select-all

Common Use Cases

Use Case 1: Percentage of Total

Collect a percentage that must be between 0-100 and represents a portion of a whole.

• Reference: value-management.md + constraints-and-validation.md

Use Case 2: Discount or Commission Rate

Accept percentage rates for calculations with specific decimal precision.

• Reference: formatting-and-display.md + value-management.md

Use Case 3: Form with Validation

Build a form that prevents invalid percentage entries and shows errors.

• Reference: constraints-and-validation.md + events-and-data-binding.md

Use Case 4: Data Binding Scenario

Bind PercentTextBox to a data model field with automatic synchronization.

• Reference: events-and-data-binding.md + value-management.md

---

Next: Choose a reference file above based on your current need, or start with getting-started.md if new to PercentTextBox.