Behavior and Data Config

A feature that defines how numeric values are constrained, modified, and input by the user.

Overview

This section covers the properties and behavior related to the control’s numeric data such as minimum and maximum values, current value management, increment settings, decimal formatting, and direct input configurations. It is essential for ensuring that the control responds correctly to user interactions and programmatic changes.

Property Overview Table

Property	Description	Data Type	Default Value
Minimum	Sets the lowest allowable value for the control.	decimal	0
Maximum	Sets the highest allowable value for the control.	decimal	100
Value	Represents the current numeric value; changes trigger a ValueChanged event and may animate.	decimal	0
Increment	The amount by which the value increases or decreases on each step; supports acceleration.	decimal	1
DecimalPlaces	Determines the number of digits displayed after the decimal point (forced to 0 for whole numbers).	int	0
InputType	Specifies whether the control handles whole numbers or decimals, affecting rounding behavior.	InputType enum	Decimals
EnableDirectInput	Enables users to directly input a value via an on-screen text box (triggered by a double-click).	bool	false
StepPoints	A list of predefined numeric values for snapping, allowing non-linear step changes.	List	Empty list
AllowMouseWheel	Determines if the control supports adjusting the value using the mouse wheel.	bool	true

---

Code Examples and Integration

The following code examples illustrate how to integrate and configure the Behavior & Data Configuration feature into a .NET WinForms application.

Example 1: Basic Setup

using SiticoneNetFrameworkUI;
using SiticoneNetFrameworkUI.Helpers.Enum;

// Create an instance of the control and set its properties.
var numericUpDown = new SiticoneUpDown
{
    Minimum = 0M,
    Maximum = 200M,
    Value = 50M,
    Increment = 5M,
    DecimalPlaces = 0, // Whole numbers only
    InputType = InputType.WholeNumbers,
    EnableDirectInput = true,
    AllowMouseWheel = true
};

// Add the control to your form.
this.Controls.Add(numericUpDown);

Example 2: Using StepPoints for Custom Increments

// Create the control instance.
var numericUpDown = new SiticoneUpDown
{
    Minimum = 0M,
    Maximum = 100M,
    Value = 20M,
    Increment = 2M,
    DecimalPlaces = 0,
    InputType = InputType.WholeNumbers,
    EnableDirectInput = true
};

// Define custom step points for snapping.
numericUpDown.StepPoints = new List<decimal> { 10M, 25M, 50M, 75M };

// Add the control to your form.
this.Controls.Add(numericUpDown);

Example 3: Handling Value Changes Programmatically

// Instantiate and configure the control.
var numericUpDown = new SiticoneUpDown
{
    Minimum = 0M,
    Maximum = 500M,
    Value = 100M,
    Increment = 10M,
    DecimalPlaces = 0,
    InputType = InputType.WholeNumbers,
    EnableDirectInput = true
};

// Subscribe to the ValueChanged event.
numericUpDown.ValueChanged += (sender, e) =>
{
    // Perform actions when the value changes.
    Console.WriteLine("New value: " + numericUpDown.Value);
};

// Add the control to the form.
this.Controls.Add(numericUpDown);

---

Key Points

Point	Details
Minimum/Maximum Relationship	The Minimum must be less than or equal to the Maximum; otherwise, an ArgumentException is thrown.
Value Rounding for Whole Numbers	When InputType is set to WholeNumbers, the Value is automatically rounded and DecimalPlaces is set to 0.
Direct Input and StepPoints	EnableDirectInput and StepPoints provide enhanced user control by allowing direct editing and snapping.
Event-Driven Updates	Changes to Value raise the ValueChanged event, enabling responsive data-binding and UI updates.

---

Best Practices

Recommendation	Explanation
Set Minimum and Maximum before assigning Value	Ensures that the initial value falls within the allowed range and prevents exceptions during assignment.
Choose the correct InputType	Use WholeNumbers when decimals are not required to automatically handle rounding and enforce zero decimal places.
Use StepPoints for non-linear progressions	When precise, non-linear adjustments are needed, define StepPoints to control snapping behavior.
Monitor the ValueChanged event	Attach event handlers to update related UI elements or perform data validations when the value changes.

---

Common Pitfalls

Pitfall	How to Avoid It
Setting Minimum greater than Maximum	Always verify that Minimum is set to a value lower than Maximum to avoid runtime exceptions.
Using an Increment value of zero or negative	Ensure that Increment is always greater than zero; otherwise, the control will throw an ArgumentException.
Ignoring InputType consistency	Remember to adjust DecimalPlaces and rounding behavior when switching between Decimals and WholeNumbers.
Overlooking direct input feedback	When EnableDirectInput is true, ensure that any external validations or UI updates account for the direct input mode.

---

Usage Scenarios

Scenario	Description	Example Use Case
Numeric Data Entry	Ideal for forms requiring controlled numeric input, such as quantity selection or budget fields.	Inventory management systems or e-commerce order forms.
Configurable Settings	Useful in settings panels where the user must choose within a specific numeric range.	Application configuration panels or user preference screens.
Step-based Adjustments	When the input requires non-linear jumps or snapping to specific preset values.	Financial applications where thresholds are predefined.

---

Review

This feature offers robust control over numeric input behavior by ensuring that developers can define clear numeric boundaries, customize increments, and support both direct and step-based input. It integrates seamlessly with event-driven programming, making it suitable for a wide range of data entry scenarios. The design enforces proper numeric ranges and rounding while providing feedback mechanisms to prevent invalid operations.

---

Summary

The Behavior & Data Configuration feature of the advanced numeric up/down control is essential for managing numeric boundaries, current value management, and direct input behaviors. It provides granular control over how values are incremented or decremented and supports custom snapping via StepPoints. By following best practices and avoiding common pitfalls, developers can ensure a reliable and user-friendly numeric input experience in their .NET WinForms applications.

---

Additional Sections

Integration Tips

Tip	Explanation
Initialize Early	Configure properties such as Minimum, Maximum, and Value early in the form initialization to prevent unexpected behavior.
Customize via Designer or Code	Properties can be set both in the Visual Studio designer and programmatically, offering flexibility for different workflows.
Validate User Input	Always validate user input when using EnableDirectInput to ensure the entered values meet the business logic requirements.

Demo Application Example

Below is a sample demo application snippet that showcases the integration of the Behavior & Data Configuration feature:

using System;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;
using SiticoneNetFrameworkUI.Helpers.Enum;

namespace DemoApp
{
    public class MainForm : Form
    {
        public MainForm()
        {
            // Set up the form.
            this.Text = "Numeric Up/Down Demo";
            this.Width = 400;
            this.Height = 200;

            // Create and configure the advanced numeric up/down control.
            var numericUpDown = new SiticoneUpDown
            {
                Minimum = 0M,
                Maximum = 100M,
                Value = 25M,
                Increment = 5M,
                DecimalPlaces = 0,
                InputType = InputType.WholeNumbers,
                EnableDirectInput = true,
                AllowMouseWheel = true,
                Location = new System.Drawing.Point(50, 50)
            };

            // Subscribe to the ValueChanged event.
            numericUpDown.ValueChanged += (sender, e) =>
            {
                MessageBox.Show("The value has changed to: " + numericUpDown.Value);
            };

            // Add the control to the form.
            this.Controls.Add(numericUpDown);
        }

        [STAThread]
        static void Main()
        {
            Application.EnableVisualStyles();
            Application.Run(new MainForm());
        }
    }
}

This demo illustrates how to integrate the control into your application, set up its numeric boundaries, and handle value changes.