Progress and Range Settings

Progress and Range Settings provide mechanisms to define the allowable range of progress and manage updates to the progress value in a controlled manner.

Overview

This section covers how to configure and control the progress value and its range using properties and methods. Developers can set the minimum and maximum bounds for the progress bar, update the progress value with smooth animations or immediate changes, and retrieve calculated percentage values for integration with application logic.

---

Properties and Methods

The following table summarizes the key properties and methods for managing progress values and their range:

Property/Method	Type / Signature	Description
Minimum	double	Sets the minimum allowed value for the progress bar.
Maximum	double	Sets the maximum allowed value for the progress bar.
Value	double (get/set)	Gets or sets the current progress value; updating this property triggers animation (if enabled) and fires the ProgressChanged event.
Percentage	int (read-only)	Returns the progress value as a percentage relative to the defined Minimum and Maximum.
ResetValue()	public void ResetValue()	Resets the progress value to the defined Minimum.
IncrementValue(double amount = 1)	public void IncrementValue(double amount = 1)	Increases the current progress value by the specified amount, ensuring it does not exceed the Maximum.
DecrementValue(double amount = 1)	public void DecrementValue(double amount = 1)	Decreases the current progress value by the specified amount, ensuring it does not fall below the Minimum.
GetValueAtPosition(Point position)	public double GetValueAtPosition(Point position)	Calculates the progress value corresponding to a specific location within the control (useful for interactive scenarios).
GetPositionFromValue(double value)	public Point GetPositionFromValue(double value)	Computes the graphical position (in pixels) for a given progress value, aiding in custom rendering or interaction.
ProgressChanged (Event)	EventHandler<ProgressChangedEventArgs>	Fired when the progress value changes, providing both the old and new values as well as the difference between them.

---

Code Examples and Samples

Below are extensive code examples to demonstrate how to integrate and use the progress and range settings.

Example 1: Basic Progress Configuration

This example shows how to set up the progress bar with a specific range and update its value with an animated transition.

// Instantiate the progress bar control
SiticoneVBarsProgress progressBar = new SiticoneVBarsProgress
{
    Minimum = 0,
    Maximum = 100,
    Value = 25 // Initial progress value (will animate to this value if AnimationEnabled is true)
};

// Optionally subscribe to the ProgressChanged event
progressBar.ProgressChanged += (sender, e) =>
{
    Console.WriteLine($"Progress changed from {e.OldValue} to {e.NewValue}");
};

Example 2: Incrementing and Decrementing Progress

This sample demonstrates how to adjust the progress value using increment and decrement methods.

// Increment the progress by 10 units
progressBar.IncrementValue(10);

// Decrement the progress by 5 units
progressBar.DecrementValue(5);

Example 3: Interactive Progress Update Using Mouse Position

In scenarios where the progress bar is used interactively, you can determine the value from a mouse position.

// Assume this method is called from a MouseMove event handler
private void UpdateProgressFromMouse(Point mousePosition)
{
    // Get the progress value based on the current mouse position
    double valueAtMouse = progressBar.GetValueAtPosition(mousePosition);
    progressBar.Value = valueAtMouse;
}

Example 4: Immediate Value Update Without Animation

For cases where an immediate update is preferred over an animated transition, use the provided method:

// Instantly update the progress value to 75 without animation
progressBar.SetValueWithoutAnimation(75);

---

Key Points

Key Point	Details
Define Range Precisely	Ensure that the Minimum and Maximum values are set correctly to avoid unexpected behavior in value calculations.
Percentage Calculation	The Percentage property dynamically computes the progress percentage based on the current Value, Minimum, and Maximum settings.
Event Handling	Subscribe to the ProgressChanged event to synchronize progress updates with other parts of the application logic.
Method Choice	Use ResetValue, IncrementValue, or DecrementValue methods to manage progress updates programmatically while maintaining constraints defined by Minimum and Maximum.

---

Best Practices

Best Practice	Recommendation
Consistent Range Definition	Always define both Minimum and Maximum values explicitly before setting a Value to avoid boundary issues.
Validate Value Changes	Ensure that any programmatic changes to Value respect the defined range to prevent the progress from exceeding boundaries.
Use Immediate Updates When Needed	For critical UI updates where animation might delay visual feedback, consider using SetValueWithoutAnimation to ensure responsiveness.
Event Subscription Management	Unsubscribe from events like ProgressChanged when the control is disposed to prevent memory leaks and unintended behavior.

---

Common Pitfalls

Common Pitfall	Solution
Overstepping Range Limits	Always validate that the new progress value is between Minimum and Maximum before applying changes.
Unintended Animated Transitions	When immediate updates are needed, use SetValueWithoutAnimation to bypass the animation logic, ensuring instant visual feedback.
Ignoring ProgressChanged Events	Failing to handle the ProgressChanged event may result in unsynchronized application logic; always implement proper event handling.

---

Usage Scenarios

Scenario	Description	Sample Code Snippet
File Download Progress	Update the progress bar to reflect the progress of a file download operation, with the progress value ranging from 0 to 100.	progressBar.Value = currentDownloadPercentage;
Interactive User Input	Allow users to set the progress value through a slider or mouse interaction, utilizing GetValueAtPosition to convert user input into a progress value.	double newValue = progressBar.GetValueAtPosition(mouseLocation); progressBar.Value = newValue;
Resetting Progress	When a task is restarted or canceled, use ResetValue to quickly revert the progress bar to its initial state.	progressBar.ResetValue();

---

Review

The Progress and Range Settings feature provides a comprehensive mechanism for managing progress values within a defined range. With properties to specify minimum and maximum bounds and methods to adjust the progress value, developers gain precise control over how progress is represented and updated. The integration of event handling ensures that any change in the progress value can be monitored and acted upon within the application.

---

Summary

Progress and Range Settings in the control offer:

• Precise definition of allowed progress values via Minimum and Maximum properties.

• Dynamic updating of the progress value with optional animations and event notifications.

• Utility methods for incrementing, decrementing, resetting, and converting between graphical positions and progress values.

By leveraging these features, developers can ensure accurate and responsive progress representations in .NET WinForms applications.

---

Additional Sections

Integration Tips

Tip	Details
Set Range Early	Define the Minimum and Maximum values as early as possible during control initialization to ensure consistent behavior.
Validate Updates	Always validate any updates to the Value property to ensure they lie within the defined range.
Leverage Events	Utilize the ProgressChanged event to synchronize progress with other UI elements or business logic effectively.

Demo Application Sample

Below is a complete sample demonstrating how to integrate the Progress and Range Settings into a basic WinForms application.

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

namespace DemoApplication
{
    public partial class MainForm : Form
    {
        private SiticoneVBarsProgress progressBar;

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

        private void InitializeProgressBar()
        {
            // Instantiate and configure the progress bar control
            progressBar = new SiticoneVBarsProgress
            {
                Location = new Point(50, 50),
                Size = new Size(30, 200),
                Minimum = 0,
                Maximum = 100,
                Value = 20 // Initial value
            };

            // Subscribe to the ProgressChanged event to handle progress updates
            progressBar.ProgressChanged += (sender, e) =>
            {
                Console.WriteLine($"Progress changed from {e.OldValue} to {e.NewValue}");
            };

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

        // Sample button event to simulate a progress increment
        private void btnIncrement_Click(object sender, EventArgs e)
        {
            // Increment progress by 10 units
            progressBar.IncrementValue(10);
        }

        // Sample button event to reset progress
        private void btnReset_Click(object sender, EventArgs e)
        {
            // Reset progress to minimum
            progressBar.ResetValue();
        }
    }
}

This demo illustrates the initialization, configuration, and interaction with the progress bar control using the Progress and Range Settings features.

---

By following this extensive guide, developers can effectively manage progress values and ranges in their applications, ensuring robust and user-friendly integration of the control's features.