Range Settings

A feature that allows developers to configure the minimum, maximum, and current progress value of the SiticoneVLineProgress control to accurately reflect progress in their applications.

Overview

The Range Settings feature defines the numeric limits and current progress of the vertical progress bar. It is comprised of three main properties—Minimum, Maximum, and Value—which together determine how the progress is calculated and animated. By adjusting these settings, developers can control the scale and behavior of the progress display.

---

Key Points

Property	Description	Default Value
Minimum	Sets the lower bound of the progress range.	0
Maximum	Sets the upper bound of the progress range.	100
Value	Represents the current progress value and initiates an animation if changed.	65 (initial)

---

Best Practices

Practice	Description	Example Scenario
Set realistic bounds	Ensure that the Minimum and Maximum values reflect the true range of progress in your application.	For a file upload progress, use 0 to 100 percentages.
Validate input values	Always validate that the new Value falls within the Minimum and Maximum bounds before setting it programmatically.	Check user input in a custom progress tracker.
Use animations to enhance UX	Leverage the animation triggered by changing the Value to provide a smooth visual transition.	Incremental progress updates in a download manager.

---

Common Pitfalls

Pitfall	Description	How to Avoid
Setting Value outside the defined range	If the Value property is set lower than Minimum or higher than Maximum, it will be clamped automatically.	Always check or enforce value limits before assignment.
Ignoring animation behavior	Changing the Value property without considering the animation can lead to unexpected UI behavior.	Allow animations to complete before triggering a new one.
Misunderstanding default values	Developers might assume a different initial value than what is set by default in the control.	Review the default property values in the documentation.

---

Usage Scenarios

Scenario	Description	Code Sample
Basic progress tracking	Use the Range Settings to display a simple progress bar that updates with task completion.	See code sample below.
Dynamic range adjustment	Adjust the Minimum and Maximum dynamically based on the context (e.g., scaling progress for variable tasks).	See code sample below.
Custom progress validation	Validate progress values entered by a user and update the control accordingly.	See code sample below.

---

Code Examples

Example 1: Basic Integration

The following example demonstrates how to initialize the SiticoneVLineProgress control with custom range settings and update the progress value:

using System;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

namespace MyWinFormsApp
{
    public partial class MainForm : Form
    {
        private SiticoneVLineProgress progressBar;

        public MainForm()
        {
            InitializeComponent();
            InitializeProgressBar();
        }

        private void InitializeProgressBar()
        {
            // Initialize the progress bar control
            progressBar = new SiticoneVLineProgress
            {
                Minimum = 0,
                Maximum = 200, // Custom maximum value
                Value = 50,    // Set initial progress value
                Location = new System.Drawing.Point(30, 30),
                Size = new System.Drawing.Size(16, 240)
            };

            this.Controls.Add(progressBar);
        }

        private void UpdateProgress(double newValue)
        {
            // Update the progress value (animation will be triggered automatically)
            progressBar.Value = newValue;
        }
    }
}

Example 2: Dynamic Range Adjustment

This example shows how to dynamically adjust the range values based on an external parameter, such as the total number of steps in a process:

using System;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

namespace MyWinFormsApp
{
    public partial class ProcessForm : Form
    {
        private SiticoneVLineProgress progressBar;

        public ProcessForm()
        {
            InitializeComponent();
            InitializeProgressBar();
        }

        private void InitializeProgressBar()
        {
            progressBar = new SiticoneVLineProgress
            {
                Minimum = 0,
                Maximum = 100, // Default maximum, will adjust later
                Value = 0,
                Location = new System.Drawing.Point(50, 50),
                Size = new System.Drawing.Size(16, 240)
            };

            this.Controls.Add(progressBar);
        }

        public void SetProcessRange(int totalSteps)
        {
            // Dynamically adjust the maximum value based on the total steps
            progressBar.Maximum = totalSteps;
        }

        public void ProcessStepCompleted(int currentStep)
        {
            // Update the progress value to reflect the current step
            progressBar.Value = currentStep;
        }
    }
}

Example 3: Validation Before Update

In this example, a value is validated before updating the progress bar to ensure it remains within the allowed range:

using System;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

namespace MyWinFormsApp
{
    public partial class ValidationForm : Form
    {
        private SiticoneVLineProgress progressBar;

        public ValidationForm()
        {
            InitializeComponent();
            InitializeProgressBar();
        }

        private void InitializeProgressBar()
        {
            progressBar = new SiticoneVLineProgress
            {
                Minimum = 0,
                Maximum = 100,
                Value = 0,
                Location = new System.Drawing.Point(20, 20),
                Size = new System.Drawing.Size(16, 240)
            };

            this.Controls.Add(progressBar);
        }

        private void SetProgress(double newValue)
        {
            // Validate that newValue is within the range
            if (newValue < progressBar.Minimum)
            {
                newValue = progressBar.Minimum;
            }
            else if (newValue > progressBar.Maximum)
            {
                newValue = progressBar.Maximum;
            }

            progressBar.Value = newValue;
        }
    }
}

---

Review

Aspect	Notes
Ease of Integration	The Range Settings are straightforward to integrate with clear property definitions.
Flexibility	Developers can easily adjust the scale to match varying requirements, from fixed ranges to dynamic adjustments.
Animation Coupling	The Value property not only sets the progress but also automatically triggers a smooth animation.

---

Summary

The Range Settings feature of the SiticoneVLineProgress control is essential for defining how progress is measured and displayed. By setting the Minimum, Maximum, and Value properties, developers can create intuitive and responsive progress indicators. The provided examples and tables illustrate best practices, common pitfalls, and various usage scenarios, ensuring that the integration is both efficient and effective.

---

Additional Sections

Troubleshooting

Issue	Possible Cause	Resolution
Progress value not updating	Value set outside the valid range or rapid successive changes	Ensure values are within bounds and allow animations to complete
Animation stuttering	Excessively high frequency of value updates or complex UI updates	Use debouncing or ensure smooth value transitions

Integration Checklist

Checklist Item	Details
Verify Minimum and Maximum values	Confirm that the range is correctly set based on the application context.
Ensure proper animation behavior	Test the progress updates to see the smooth transition effect.
Validate dynamic adjustments	In dynamic scenarios, confirm that range adjustments are handled gracefully.

---

By following this comprehensive documentation for the Range Settings feature, developers can quickly integrate and customize the SiticoneVLineProgress control within their .NET WinForms applications, ensuring a robust and visually appealing progress display.