# Behavior and Data Config

## 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**

```csharp
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**

```csharp
// 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**

```csharp
// 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:

```csharp
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.